view release on metacpan or  search on metacpan

lib/CLI/Framework/Application.pm  view on Meta::CPAN

    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',
    }

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

C<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',
    }

=head2 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
C<console> and C<menu>.

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

=head2 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 L<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 L<render|/render( $output )>
method.

=head2 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 C<$output> scalar,
assuming that it is a string.

Subclasses are free to override this method to provide more
sophisticated behavior such as processing the C<$output> scalar through a
templating system.

=head2 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
L<usage|/usage( $command_name, @subcommand_chain )>.

=head1 ERROR HANDLING IN CLIF

Internally, CLIF handles errors by throwing exceptions.  

The L<handle_exception|/handle_exception( $e )> method provides an opportunity
for customizing the way errors are treated in a CLIF application.

Application and Command class hooks such as
L<validate_options|/validate_options( $options_hash )>
and L<validate|CLI::Framework::Command/validate( $cmd_opts, @args )> are