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)