/ 
App-CmdDispatch-0.4
River stage one • 1 direct dependent • 1 total dependent
/ App::CmdDispatch

NAME

App::CmdDispatch - Handle command line processing for programs with subcommands

VERSION

This document describes App::CmdDispatch version 0.4

SYNOPSIS

use App::CmdDispatch;

my %cmds = (
    start => {
        code => sub { my $app = shift; print "start: @_\n"; },
        clue => 'start [what]',
        abstract => 'Start something',
        help => 'Start whatever is to be run.',
    },
    stop => {
        code => sub { my $app = shift; print "stop @_\n"; },
        clue => 'stop [what]',
        abstract => 'Stop something',
        help => 'Stop whatever is to be run.',
    },
    stuff => {
        code => sub { my $app = shift; print "stuff: @_\n"; },
        clue => 'stuff [what]',
        abstract => 'Do stuff',
        help => 'Stuff to do.',
    },
    jump => {
        code => sub { my $app = shift; print "jump: @_\n"; },
        clue => 'jump [what]',
        abstract => 'Jump it',
        help => 'Jump the item requested to be jumped.',
    },
);

my $processor = App::CmdDispatch->new( \%cmds );
$processor->run( @ARGV );

DESCRIPTION

One way to map a series of command strings to the code to execute for that string is a dispatch table. The simplest dispatch table maps strings directly to code refs. A more complicated dispatch table maps strings to objects that provide a wider interface than just a single function call. I often find I want more than a single function and less than a full object.

App::CmdDispatch falls in between these two extremes. One thing I always found that I needed with my dispatch table-driven scripts was decent help that covered all of the commands. App::CmdDispatch makes each command map to a hash containing a code reference and some help strings.

Since beginning to use git, I have found git's alias feature to be extremely helpful. App::CmdDispatch supports reading aliases from a config file.

INTERFACE

new( $cmdhash, $options )

Create a new App::CmdDispatch object. This method can take one or two hashrefs as arguments.

The $cmdhash hash

The first is required and describes the commands. The second is optional and provides option information for the App::CmdDispatch object. The keys of the hash are the command names. Each value is a hash describing the command. The entries in this description hash are dependent on which features are enabled. The currently known keys are:

code

This is the only required key. The value for the key must be a coderef that is executed when the command is requested. The parameters for the command are a reference to the App::CmdDispatch object that contains the command and a list of the parameters that were supplied to the command.

clue

This optional parameter provides a clue to the usage of the command. This would normally be the command name and some indication of the possible parameters. It is used when either the hint or help features of App::CmdDispatch::Help are invoked.

If the parameter is not supplied and either hint or help are invoked, the name of the command is used by default.

abstract

This optional parameter gives a short (less than a line) explanation of the command. The idea is to give a hint of the functionality to remind someone who is mostly familiar with the commands.

When hint is invoked, the abstract is displayed on the same line as the clue.

If the parameter is not supplied and hint is invoked, nothing is used by default.

help

This optional parameter gives a fuller explanation of the command. It often extends across several lines. The idea is to explain the functionality of the command to someone that is not familiar with it.

When help is invoked, the help text is displayed after the line containing the clue.

If the parameter is not supplied and help is invoked, nothing is used by default.

The $options hash

This hash determines some of the default behavior of the App::CmdDispatch object.

config_file

This option is the name of a configuration file that is read using the format specified in Config::Tiny. This sets default configuration parameters and aliases.

default_commands

This string provides a space separated list of default command behaviors. The two supported behaviors are:

help

Provide a help command and a hint command through the App::CmdDispatch::Help module.

shell

Prove a shell interface that loops asking for subcommands. Each command is executed and contol returns to the loop.

io

An object supplying input and output services for the CmdDispatcher. This object must provide both a print method and a prompt method. See App::CmdDispatch::IO for more information on the interface.

help:*

The options beginning with the string 'help:' are described in the docs for App::CmdDispatch::Help.

run( $cmd, @args )

This method looks up the supplied command and executes it.

command_hint( $cmd )

This method prints a short hint listing all commands and aliases or just the hint for the supplied command.

hint( $cmd )

This method prints a short hint listing all commands and aliases or just the hint for the supplied command.

help( $cmd )

This method prints help for the program or just help on the supplied command.

shell()

This method start a read/execute loop which supports running multiple commands in the same execution of the main program.

get_config()

This method returns a reference to the configuration hash for the dispatcher.

command_list()

This method returns the list of commands in a defined order.

alias_list()

This method returns the list of aliases in sorted order.

CONFIGURATION AND ENVIRONMENT

App::CmdDispatch can read a configuration file specified in a Config::Tiny supported format. Should be specified in the config parameter.

DEPENDENCIES

Config::Tiny Term::Readline

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-app-cmddispatch@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

G. Wade Johnson <wade@cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 2013, G. Wade Johnson <wade@cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.