Karl Erisman > CLI-Framework-0.03 > CLI::Framework::Application

Download:
CLI-Framework-0.03.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.03   Source   Latest Release: CLI-Framework-0.05

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

CONCEPTS AND DEFINITIONS ^

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

menu: show a command menu including the commands that are available to the running application

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:

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 ^

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)

syntax highlighting: