CLI::Framework::Application - Build standardized, flexible, testable command-line applications
See CLI::Framework::Tutorial for examples.
CLI::Framework ("CLIF") provides a framework and conceptual pattern for building full-featured command line applications. It intends to make this process easy and consistent. It assumes responsibility for common details that are application-independent, making it possible for new CLI applications adhering to well-defined conventions to be built without the need to address the same details over and over again.
For instance, a complete application supporting commands and subcommands, with options and arguments for the application itself as well as its commands, can be built by writing concise, understandable code in packages that are easy to test and maintain. The classes can focus on implementation of their essential requirements (details that are unique to a specific application or command) without being concerned with the many details involved in building an interface around those commands. This methodology for building CLI apps can be adopted as a standardized convention.
CLIF offers many features and some alternative approaches to building applications, but if you are new to using it, you probably want a succinct introduction, not a specification of all the alternatives. For this reason, the CLI::Framework::Tutorial is provided. That document is the recommended starting point.
After you gain a basic understanding, CLI::Framework::Application and CLI::Framework::Command will continue to be valuable references.
There are a few other distributions on CPAN intended to simplify building modular command line applications. None of them met my requirements, which are documented in DESIGN GOALS AND FEATURES.
CLIF was designed to offer the following features...
A clear conceptual pattern for creating CLI apps
Guiding documentation and examples
Convenience for simple cases, flexibility for complex cases
Support for both non-interactive and interactive modes (with almost no additional work -- define the necessary hooks and both modes will be supported)
Naturally encourages MVC applications: decouple data model, control flow, and presentation
Commands that can be shared between apps (and uploaded to CPAN)
The possibility to share some components with MVC web apps
Validation of application options
Validation of command options and arguments
A model that encourages easily-testable applications
A flexible means to provide usage/help information for the application as a whole and for individual commands
Support for subcommands that work just like commands
Support for recursively-defined subcommands (sub-sub-...commands to any level of depth)
Support for aliases for commands and subcommands
Allow Application and [sub]commands to be defined inline (some or all packages involved may be defined in the same file) or split across multiple files (for flexibility in organization)
Support the concept of a default command for the application
Exception handling that allows individual applications to define custom exception handlers
Application Script - The wrapper program that invokes the CLIF Application's run method. It may or may not also include the code for Application and Command packages.
Metacommand - An application-aware command. Metacommands are subclasses of CLI::Framework::Command::Meta. They are identical to regular commands except they hold a reference to the application within which they are running. This means they are able to "know about" and affect the application. For example, the built-in command 'Menu' is a Metacommand because it needs to produce a list of the other commands in its application.
In general, your commands should be designed to operate independently of the application, so they should simply inherit from CLI::Framework::Command. The Metacommand facility is useful but it is best to avoid using it unless it is really needed.
Non-interactive Command - In interactive mode, some commands need to be disabled. For instance, the built-in 'console' command should not be presented as a menu option in interactive mode because it is already running (the console presents a command menu and responds to user selection). You can designate which commands are non-interactive by overriding the noninteractive_commands method.
Registration of commands - Each CLIF application defines the commands it will support. These may be built-in CLIF commands or may be any other CLIF Commands (e.g. commands built specifically for an individual application). These commands are lazily "registered" as they are called upon for use.
When a command of the form:
$ app [app-opts] <cmd> [cmd-opts] { <cmd> [cmd-opts] {...} } [cmd-args]
...causes your application script, <app>, to invoke the run method in your application class, CLI::Framework::Application performs the following actions:
Parse the request
Validate application options
Initialize application
Invoke command pre-dispatch hook
Dispatch command
These steps are explained in more detail below...
Parse the application options [app-opts], command name <cmd>, command options [cmd-opts], and the remaining part of the command line (which includes command arguments [cmd-args] for the last command on the command line and may include multiple subcommands; everything between the inner brackets ({ ... }) represents recursive subcommand processing -- the "..." represents another string of "<cmd> [cmd-opts] {...}").
[app-opts]
<cmd>
[cmd-opts]
[cmd-args]
{ ... }
...
<cmd> [cmd-opts] {...}
If the command request is not well-formed, it is replaced with the default command and any arguments present are ignored. Generally, the default command prints a help or usage message (but you may change this behavior if desired).
Your application class can optionally define the validate_options method.
If your application class does not override this method, validation is skipped -- any received options are considered to be valid.
Your application class can optionally override the init method. This is a hook that can be used to perform any application-wide initialization that needs to be done independent of individual commands. For example, your application may use the init method to connect to a database and store a connection handle which may be needed by most of the commands in your application.
Your application class can optionally have a pre_dispatch method that is called with one parameter: the Command object that is about to be dispatched.
CLIF uses the dispatch method to actually dispatch a specific command. That method is responsible for running the command or delegating responsibility to a subcommand, if applicable.
See dispatch for the specifics.
After building your CLIF-based application, in addition to basic non-interactive functionality, you will instantly benefit from the ability to (optionally) run your application in interactive mode. A readline-enabled application command console with an event loop, a command menu, and built-in debugging commands is provided by default.
This distribution comes with some default built-in commands, and more CLIF built-ins can be installed as they become available on CPAN.
Use of the built-ins is optional in most cases, but certain features require specific built-in commands (e.g. the Help command is a fundamental feature of all apps and the Menu command is required in interactive mode). You can override any of the built-ins.
A new application that does not override the command_map hook will include all of the built-ins listed below.
The existing built-ins and their corresponding packages are as follows (for more information on each, see the respective documentation):
CLI::Framework::Command::Help: print application or command-specific usage messages
Note: This command is registered automatically. All CLIF apps must have the 'help' command defined (though this built-in can replaced by your subclass to change the 'help' command behavior or to do nothing if you specifically do not want a help command).
CLI::Framework::Command::List
CLI::Framework::Command::Dump
CLI::Framework::Command::Tree
CLI::Framework::Command::Alias
CLI::Framework::Command::Console
CLI::Framework::Command::Menu
Note: This command is registered automatically when an application runs in interactive mode. This built-in may be replaced by a user-defined 'menu' command, but any command class to be used for the 'menu' command MUST be a subclass of this one.
$app = My::Application->new( interactive => 1 );
Recognized parameters:
interactive: set this to a true value if the application is to be run interactively (or call set_interactivity_mode later)
interactive
set_interactivity_mode
Constructs and returns a new CLIF Application object. As part of this process, some validation is performed on SUBCLASS HOOKS defined in the application class. If validation fails, an exception is thrown.
The methods in this section are responsible for providing access to the commands in an application.
$app->is_valid_command_pkg( 'My::Command::Swim' );
Returns a true value if the specified command class (package name) is valid within the application. Returns a false value otherwise.
A command class is "valid" if it is included in command_map or if it is a built-in command that was included automatically in the application.
$app->is_valid_command_name( 'swim' );
Returns a true value if the specified command name is valid within the application. Returns a false value otherwise.
A command name is "valid" if it is included in command_map or if it is a built-in command that was included automatically in the application.
@registered_commands = $app->registered_command_names();
Returns a list of the names of all registered commands. These are the names that each command was given in command_map (plus any auto-registered built-ins).
$command_object = $app->registered_command_object( 'fly' );
Given the name of a registered command, returns the CLI::Framework::Command object that is registered in the application under that name. If the command is not registered, returns undef.
# Register by name... $command_object = $app->register_command( $command_name ); # ...or register by object reference... $command_object = CLI::Framework::Command->new( ... ); $app->register_command( $command_object );
Register a command to be recognized by the application. This method accepts either the name of a command or a reference to a CLI::Framework::Command object.
If a CLI::Framework::Command object is given and it is one of the command types specified (as a value in the hash returned by command_map) to be valid, the command is registered and returned.
If the name of a command (one of the keys in the command_map) is given, the corresponding command class is registered and returned.
If $cmd is not recognized, an exception is thrown.
$cmd
get_defualt_command() retrieves the name of the command that is currently set as the default command for the application.
get_defualt_command()
my $default_command = $app->get_default_command();
Given a command name, set_default_command makes it the default command for the application.
set_default_command
$app->set_default_command( 'jump' );
get_current_command returns the name of the current command (or the one that was most recently run).
get_current_command
$status = $app->run(); print 'The command named: ', $app->get_current_command(), ' was just run';
Given a command name, set_current_command forwards execution to that command. This might be useful (for instance) to "redirect" to another command.
set_current_command
$app->set_current_command( 'fly' );
The "default usage" message is used as a last resort when usage information is unavailable by other means. See usage.
get_default_usage gets the default usage message for the application.
get_default_usage
$usage_msg = $app->get_default_usage();
set_default_usage sets the default usage message for the application.
set_default_usage
$app->set_default_usage( $usage_message );
# Application usage... print $app->usage(); # Command-specific usage... print $app->usage( $command_name, @subcommand_chain );
Returns a usage message for the application or a specific (sub)command.
If a command name is given (optionally with subcommands), returns a usage message string for that (sub)command. If no command name is given or if no usage message is defined for the specified command, returns a general usage message for the application.
Here is how the usage message is produced:
If a valid command name (or alias) is given, attempt to get a usage message from the command (this step takes into account @subcommand_chain so that a subcommand usage message will be shown if applicable); if no usage message is defined for the command, use the application usage message instead.
@subcommand_chain
If the application object has defined usage_text, use its return value as the usage message.
Finally, fall back to using the default usage message returned by get_default_usage.
CLIF Applications may have the need for global data shared between all components (individual CLIF Commands and the Application object itself). cache() provides a way for this data to be stored, retrieved, and shared between components.
cache()
$cache_object = $app->cache();
cache() returns a cache object. The following methods demonstrate usage of the resulting object:
$cache_object->get( 'key' ); $cache_object->set( 'key' => $value );
Note: The underlying cache class is currently limited to these rudimentary features. In the future, the object returned by cache() may be changed to an instance of a real caching class, such as CHI (which would maintain backwards compatibility but offer expiration, serialization, multiple caching backends, etc.).
# For convenience when direct access to application is unnecessary: My::App->run(); # ...or using a direct object reference: my $app = My::App->new(); $app->run(); ... # Explicitly specify whether or not initialization should be done: $app->run( initialize => 0 );
This method controls the request processing and dispatching of a single command. It takes its input from @ARGV (which may be populated by a script running non-interactively on the command line) and dispatches the indicated command, capturing its return value. The command's return value represents the output produced by the command. This value is passed to render for final display.
If errors occur, they result in exceptions that are handled by handle_exception.
The following parameters are accepted:
initialize: This controls whether or not application initialization should be performed. If not specified, initialization is performed upon the first call to run. Should there be subsequent calls, initialization is not repeated. Passing initialize explicitly can modify this behavior.
initialize
run
get_interactivity_mode returns a true value if the application is in an interactive state and a false value otherwise.
get_interactivity_mode
print "running interactively" if $app->get_interactivity_mode();
set_interactivity_mode sets the interactivity state of the application. One parameter is recognized: a true or false value to indicate whether the application state should be interactive or non-interactive, respectively.
$app->set_interactivity_mode(1);
$help_command_is_interactive = $app->is_interactive_command( 'help' );
Returns a true value if there is a valid command with the specified name that is an interactive command (i.e. a command that is enabled for this application in interactive mode). Returns a false value otherwise.
my @interactive_commands = $app->get_interactive_commands();
Return a list of all commands that are to be available in interactive mode ("interactive commands").
MyApp->run_interactive(); # ...or with an object: $app->run_interactive();
Start an event processing loop to prompt for and run commands in sequence. The menu command is used to display available command selections (the built-in menu command, CLI::Framework::Command::Menu, will be used unless the application defines its own menu command).
menu
Within this loop, valid input is the same as in non-interactive mode except that application options are not accepted (any application options should be handled upon app initialization and before the interactive command loop is entered -- see the description of the initialize parameter below).
The following parameters are recognized:
initialize: causes any application options that are present in @ARGV to be procesed/validated and causes init to be invoked prior to entering the interactive event loop to recognize commands. If run_interactive() is called after app options have already been handled, this parameter can be omitted.
@ARGV
run_interactive()
invalid_request_threshold: the number of unrecognized command requests the user can enter before the menu is re-displayed.
invalid_request_threshold
$app->read_cmd();
This method is responsible for retrieving a command request and placing the user input into @ARGV. It is called in void context.
The default implementation uses Term::ReadLine to prompt the user and read a command request, supporting command history.
Subclasses are free to override this method if a different means of accepting user input is desired. This makes it possible to read command selections without assuming that the console is being used for I/O.
until( $app->is_quit_signal(read_string_from_user()) ) { ... }
Given a string, return a true value if it is a quit signal (indicating that the application should exit) and a false value otherwise. quit_signals is an application subclass hook that defines what strings signify that the interactive session should exit.
There are several hooks that allow CLIF applications to influence the command execution process. This makes customizing the critical aspects of an application as easy as overriding methods.
Except where noted, all hooks are optional -- subclasses may choose not to override them (in fact, runnable CLIF applications can be created with very minimal subclasses).
This hook is called in void context with these parameters:
$options_hash is a hash of pre-validated application options received and parsed from the command line. The options hash has already been checked against the options defined to be accepted by the application in option_spec.
$options_hash
This method allows CLIF applications to perform any common initialization tasks that are necessary regardless of which command is to be run. Some examples of this include connecting to a database and storing a connection handle in the shared cache slot for use by individual commands, setting up a logging facility that can be used by each command by storing a logging object in the cache, or initializing settings from a configuration file.
This hook is called in void context. It allows applications to perform actions after each command object has been prepared for dispatch but before the command dispatch actually takes place. Its purpose is to allow applications to do whatever may be necessary to prepare for running the command. For example, a log entry could be inserted in a database to store a record of every command that is run.
An example definition of this hook is as follows:
sub option_spec { [ 'verbose|v' => 'be verbose' ], [ 'logfile=s' => 'path to log file' ], }
This method should return an option specification as expected by describe_options. The option specification defines what options are allowed and recognized by the application.
This hook is called in void context. It is provided so that applications can perform validation of received options.
$options_hash is an options hash parsed from the command-line.
This method should throw an exception if the options are invalid (die() is sufficient).
die()
Note that Getopt::Long::Descriptive, which is used internally for part of the options processing, will perform some validation of its own based on the option_spec. However, the validate_options hook allows for additional flexibility in validating application options.
Return a (HASH ref) mapping between command names and Command classes (classes that inherit from CLI::Framework::Command). The mapping is a hashref where the keys are names that should be used to install the commands in the application and the values are the package names of the packages that implement the corresponding commands, as in this example:
sub command_map { { # custom commands: fly => 'My::Command::Fly', run => 'My::Command::Run', # overridden built-in commands: menu => 'My::Command::Menu', # built-in commands: help => 'CLI::Framework::Command::Help', list => 'CLI::Framework::Command::List', tree => 'CLI::Framework::Command::Tree', 'dump' => 'CLI::Framework::Command::Dump', console => 'CLI::Framework::Command::Console', alias => 'CLI::Framework::Command::Alias', } }
This hook allows aliases for commands to be specified. The aliases will be recognized in place of the actual command names. This is useful for setting up shortcuts to longer command names.
command_alias should return a hash where the keys are aliases and the values are command names.
command_alias
An example of its definition:
sub command_alias { h => 'help', l => 'list', ls => 'list', sh => 'console', c => 'console', }
Certain commands do not make sense to run interactively (e.g. the "console" command, which itself puts the application into interactive mode). This method should return a list of their names. These commands will be disabled during interactive mode. By default, all commands are interactive commands except for console and menu.
console
sub quit_signals { qw( q quit exit ) }
An application can specify exactly what input represents a request to end an interactive session. By default, the example definition above is used.
sub handle_exception { my ($app, $e) = @_; # Handle the exception represented by object $e... $app->my_error_logger( error => $e->error, pid => $e->pid, gid => $e->gid, ... ); warn "caught error ", $e->error, ", continuing..."; return; }
Error conditions are caught by CLIF and forwarded to this exception handler. It receives an exception object (see Exception::Class::Base for methods that can be called on the object).
If not overridden, the default implementation extracts the error message from the exception object processes it through the render method
$app->render( $output );
This method is responsible for presentation of the result from a command. The default implementation simply attempts to print the $output scalar, assuming that it is a string.
$output
Subclasses are encouraged to override this method to provide more sophisticated behavior such as processing the $output scalar through a templating system, if desired.
To provide application usage information, this method may be defined. It accepts no parameters and should return a string containing a useful help message for the overall application.
Internally, CLIF handles errors by throwing exceptions.
The handle_exception/ method provides an opportunity for customizing the way errors are treated in a CLIF app.
Application and Command class hooks such as validate_options and validate (remember to notice the specifics documented in the POD) are expected to indicate success or failure by throwing exceptions (via die() or something more elaborate, such as exception objects).
For interactive usage, Term::ReadLine is used. Depending on which readline libraries are available on your system, your interactive experience will vary (for example, systems with GNU readline can benefit from a command history buffer).
Getopt::Long::Descriptive
Text::ParseWords (only for interactive use)
Term::ReadLine (only for interactive use)
CLI::Framework::Exceptions
CLI::Framework::Command
No known bugs.
Command-line completion of commands in interactive mode
Features to make it simpler to use templates for output
Features to instantly web-enable your CLIF Applications, making them accessible via a "web console"
Better automatic usage message generation
An optional inline automatic class generation interface similar to Class::Exception that will make the simple "inline" form of usage even simpler
Many thanks to Allen May and other colleagues at Informatics Corporation of America who have supported this development effort.
CLI::Framework::Tutorial
Copyright (c) 2009 Karl Erisman (karl.erisman@icainformatics.com), Informatics Corporation of America. All rights reserved.
This is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
Karl Erisman (karl.erisman@icainformatics.com)
1 POD Error
The following errors were encountered while parsing the POD:
alternative text 'handle_exception/' contains non-escaped | or /
To install CLI::Framework::Command, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CLI::Framework::Command
CPAN shell
perl -MCPAN -e shell install CLI::Framework::Command
For more information on module installation, please visit the detailed CPAN module installation guide.