Provided by: libcli-framework-perl_0.05-1_all bug

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)