SYNOPSIS

# The code below shows a few of the methods your application class is likely
# to override...
package My::Journal;
use base qw( CLI::Framework );
sub usage_text { q{
$0 [--verbose|v]
OPTIONS
--db [path] : path to SQLite database file
-v --verbose : be verbose
-h --help : show help
COMMANDS
help - show application or command-specific help
menu - print command menu
entry - work with journal entries
publish - publish a journal
console - start a command console for the application
} }
sub option_spec {
[ 'help|h' => 'show help' ],
[ 'verbose|v' => 'be verbose' ],
[ 'db=s' => 'path to SQLite database file' ],
}
sub command_map {
help => 'CLI::Framework::Command::Help',
menu => 'My::Journal::Command::Menu',
entry => 'My::Journal::Command::Entry',
publish => 'My::Journal::Command::Publish',
console => 'CLI::Framework::Command::Console',
}
sub command_alias {
h => 'help',
m => 'menu',
e => 'entry',
p => 'publish',
sh => 'console',
c => 'console',
}
sub init {
my ($self, $opts) = @_;
my $db = DBI->connect( ... );
$self->cache->set( db => $db );
return 1;
}
1;

OBJECT CONSTRUCTION

new( [interactive => 1] )

    $app = My::Application->new( interactive => 1 );

"interactive": Optional parameter. 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.

command_map_hashref()

    $h = $app->command_map_hashref();

Returns a HASH ref built from the command_map for an Application (by direct conversion from the command map array).

If the list returned by the definition of command_map in the application is not hash-worthy, an exception is thrown.

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 $cmd is a CLI::Framework::Command object and it is one of the command types specified in command_map to be valid, the command object is registered and returned.

If $cmd is the name of a valid command specified in command_map, an object of 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...
    $command_name = 'task';
    @subcommand_chain = qw( list completed );
    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 (sub)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.

  Note: It is advisable to define usage_text because the default usage message, produced via Getopt::Long::Descriptive, is terse and is not context-specific to the command request.

cache()

CLIF Applications may have the need to share data between 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()

    # as class method:
    My::App->run();
    # as object method (when having an object reference to call other methods
    # is desirable):
    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 (via init) 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 as an object method:
    $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 application 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 application 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 one parameter:

$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 Getopt::Long::Descriptive. 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 (throwing the exception using "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 mapping between command names and Command classes (classes that inherit from CLI::Framework::Command). The mapping is a list of key-value pairs. The list should be ``hash-worthy'', meaning that it can be directly converted to a hash.

Note that the order of the commands in this list determines the order that the commands are displayed in the built-in interactive menu.

The keys are names that should be used to install the commands in the application. The values are the 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-worthy'' list 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()

    sub noninteractive_commands { qw( console menu ) }

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 and 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 free to override this method to provide more sophisticated behavior such as processing the $output scalar through a templating system.

usage_text()

    sub usage_text {
        q{
        OPTIONS
            -v --verbose : be verbose
            -h --help    : show help
    
        COMMANDS
            tree        - print a tree of only those commands that are currently-registered in your application
            menu        - print command menu
            help        - show application or command-specific help
            console     - start a command console for the application
            list        - list all commands available to the application
        }
    }

To provide application usage information, this method may be overridden. It accepts no parameters and should return a string containing a useful help message for the overall application.

Overriding this method is encouraged in order to provide a better usage message than the default. See usage.

CONFIGURATION & ENVIRONMENT

For interactive usage, Term::ReadLine is used by default. 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

Exception::Class::TryCatch

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 that of Exception::Class that will make the simple ``inline'' form of usage even more compact

LICENSE AND COPYRIGHT

Copyright (c) 2009 Karl Erisman ([email protected]). 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 ([email protected])