Provided by: libcli-framework-perl_0.05-1_all 
NAME
CLI::Framework::Application - CLIF Application superclass
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.
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 application.
Application and Command class hooks such as validate_options and validate 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 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
SEE ALSO
CLI::Framework
CLI::Framework::Command
CLI::Framework::Tutorial
LICENSE AND COPYRIGHT
Copyright (c) 2009 Karl Erisman (kerisman@cpan.org). 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 (kerisman@cpan.org)