/ 
CLI-Framework-0.03
River stage one • 4 direct dependents • 4 total dependents
/ CLI::Framework::Application

NAME

CLI::Framework::Application - Build standardized, flexible, testable command-line applications

SYNOPSIS

See CLI::Framework::Tutorial for examples.

OVERVIEW

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.

LEARNING CLIF: RECOMMENDATIONS

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.

MOTIVATION

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.

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

CONCEPTS AND DEFINITIONS

  • 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.

APPLICATION RUN SEQUENCE

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:

  1. Parse the request

  2. Validate application options

  3. Initialize application

  4. Invoke command pre-dispatch hook

  5. Dispatch command

These steps are explained in more detail below...

Request parsing

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] {...}").

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).

Validation of application options

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.

Application initialization

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.

Command pre-dispatch

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.

Dispatching a command

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.

INTERACTIVITY

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.

BUILT-IN COMMANDS INCLUDED IN THIS DISTRIBUTION

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):

help

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).

list: print a list of commands available to the running application

CLI::Framework::Command::List

dump: show the internal state of a running application

CLI::Framework::Command::Dump

tree: display a tree representation of the commands that are currently registered with the running application

CLI::Framework::Command::Tree

alias: display the command aliases that are in effect for the running application and its commands

CLI::Framework::Command::Alias

console: invoke CLIF's interactive mode

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.

OBJECT CONSTRUCTION

new( [interactive => 1] )

$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)

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.

COMMAND INTROSPECTION & REGISTRATION

The methods in this section are responsible for providing access to the commands in an application.

is_valid_command_pkg( $package_name )

$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.

is_valid_command_name( $command_name )

$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_command_names()

@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).

registered_command_object( $command_name )

$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_command( $cmd )

# 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.

get_default_command() / set_default_command( $default_cmd )

get_defualt_command() retrieves the name of the command that is currently set as the default command for the application.

my $default_command = $app->get_default_command();

Given a command name, set_default_command makes it the default command for the application.

$app->set_default_command( 'jump' );

get_current_command() / set_current_command( $current )

get_current_command returns the name of the current command (or the one that was most recently run).

$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.

$app->set_current_command( 'fly' );

get_default_usage() / set_default_usage( $default_usage )

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.

$usage_msg = $app->get_default_usage();

set_default_usage sets the default usage message for the application.

$app->set_default_usage( $usage_message );

PARSING & RUNNING COMMANDS

usage( $command_name, @subcommand_chain )

# 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.

  • 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.

cache()

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_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.).

run()

# 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.

INTERACTIVITY

get_interactivity_mode() / set_interactivity_mode( $is_interactive )

get_interactivity_mode returns a true value if the application is in an interactive state and a false value otherwise.

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);

is_interactive_command( $command_name )

$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.

get_interactive_commands()

my @interactive_commands = $app->get_interactive_commands();

Return a list of all commands that are to be available in interactive mode ("interactive commands").

run_interactive( [%param] )

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).

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.

invalid_request_threshold: the number of unrecognized command requests the user can enter before the menu is re-displayed.

read_cmd()

$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.

is_quit_signal()

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.

SUBCLASS HOOKS

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).

init( $options_hash )

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.

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.

pre_dispatch( $command_object )

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.

option_spec()

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.

validate_options( $options_hash )

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).

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.

command_map()

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',
    }
}

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.

An example of its definition:

sub command_alias {
    h   => 'help',
    l   => 'list',
    ls  => 'list',
    sh  => 'console',
    c   => 'console',
}

noninteractive_commands()

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.

quit_signals()

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.

handle_exception( $e )

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

render( $output )

$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.

Subclasses are encouraged to override this method to provide more sophisticated behavior such as processing the $output scalar through a templating system, if desired.

usage_text()

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.

ERROR HANDLING IN CLIF

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).

CONFIGURATION & ENVIRONMENT

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).

DEPENDENCIES

Getopt::Long::Descriptive

Text::ParseWords (only for interactive use)

Term::ReadLine (only for interactive use)

CLI::Framework::Exceptions

CLI::Framework::Command

DEFECTS AND LIMITATIONS

No known bugs.

PLANS FOR FUTURE VERSIONS

  • 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

ACKNOWLEDGEMENTS

Many thanks to Allen May and other colleagues at Informatics Corporation of America who have supported this development effort.

SEE ALSO

CLI::Framework::Tutorial

CLI::Framework::Command

LICENSE AND COPYRIGHT

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.

AUTHOR

Karl Erisman (karl.erisman@icainformatics.com)

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1427:

alternative text 'handle_exception/' contains non-escaped | or /