App::Cmd(3) User Contributed Perl Documentation App::Cmd(3)NAMEApp::Cmd - write command line apps with less suffering
VERSION
version 0.311
SYNOPSIS
in yourcmd:
use YourApp;
YourApp->run;
in YourApp.pm:
package YourApp;
use App::Cmd::Setup -app;
1;
in YourApp/Command/blort.pm:
package YourApp::Command::blort;
use YourApp -command;
use strict; use warnings;
sub opt_spec {
return (
[ "blortex|X", "use the blortex algorithm" ],
[ "recheck|r", "recheck all results" ],
);
}
sub validate_args {
my ($self, $opt, $args) = @_;
# no args allowed but options!
$self->usage_error("No args allowed") if @$args;
}
sub execute {
my ($self, $opt, $args) = @_;
my $result = $opt->{blortex} ? blortex() : blort();
recheck($result) if $opt->{recheck};
print $result;
}
and, finally, at the command line:
knight!rjbs$ yourcmd blort --recheck
All blorts successful.
DESCRIPTIONApp::Cmd is intended to make it easy to write complex command-line
applications without having to think about most of the annoying things
usually involved.
For information on how to start using App::Cmd, see App::Cmd::Tutorial.
METHODS
new
my $cmd = App::Cmd->new(\%arg);
This method returns a new App::Cmd object. During initialization,
command plugins will be loaded.
Valid arguments are:
no_commands_plugin - if true, the command list plugin is not added
no_help_plugin - if true, the help plugin is not added
plugin_search_path - The path to search for commands in. Defaults to
results of plugin_search_path method
If "no_commands_plugin" is not given, App::Cmd::Command::commands will
be required, and it will be registered to handle all of its command
names not handled by other plugins.
If "no_help_plugin" is not given, App::Cmd::Command::help will be
required, and it will be registered to handle all of its command names
not handled by other plugins. Note: "help" is the default command, so
if you do not load the default help plugin, you should provide our own
or override the "default_command" method.
run
$cmd->run;
This method runs the application. If called the class, it will
instantiate a new App::Cmd object to run.
It determines the requested command (generally by consuming the first
command-line argument), finds the plugin to handle that command, parses
the remaining arguments according to that plugin's rules, and runs the
plugin.
It passes the contents of the global argument array (@ARGV) to
""prepare_command"", but @ARGV is not altered by running an App::Cmd.
arg0
full_arg0
my $program_name = $app->arg0;
my $full_program_name = $app->full_arg0;
These methods return the name of the program invoked to run this
application. This is determined by inspecting $0 when the App::Cmd
object is instantiated, so it's probably correct, but doing weird
things with App::Cmd could lead to weird values from these methods.
If the program was run like this:
knight!rjbs$ ~/bin/rpg dice 3d6
Then the methods return:
arg0 - rpg
full_arg0 - /Users/rjbs/bin/rpg
These values are captured when the App::Cmd object is created, so it is
safe to assign to $0 later.
prepare_command
my ($cmd, $opt, @args) = $app->prepare_command(@ARGV);
This method will load the plugin for the requested command, use its
options to parse the command line arguments, and eventually return
everything necessary to actually execute the command.
default_command
This method returns the name of the command to run if none is given on
the command line. The default default is "help"
execute_command
$app->execute_command($cmd, \%opt, @args);
This method will invoke "validate_args" and then "run" on $cmd.
plugin_search_path
This method returns the plugin_search_path as set. The default
implementation, if called on "YourApp::Cmd" will return
"YourApp::Cmd::Command"
This is a method because it's fun to override it with, for example:
use constant plugin_search_path => __PACKAGE__;
allow_any_unambiguous_abbrev
If this method returns true (which, by default, it does not), then any
unambiguous abbreviation for a registered command name will be allowed
as a means to use that command. For example, given the following
commands:
reticulate
reload
rasterize
Then the user could use "ret" for "reticulate" or "ra" for "rasterize"
and so on.
global_options
if ($cmd->app->global_options->{verbose}) { ... }
This method returns the running application's global options as a
hashref. If there are no options specified, an empty hashref is
returend.
set_global_options
$app->set_global_options(\%opt);
This method sets the global options.
command_names
my @names = $cmd->command_names;
This returns the commands names which the App::Cmd object will handle.
command_plugins
my @plugins = $cmd->command_plugins;
This method returns the package names of the plugins that implement the
App::Cmd object's commands.
plugin_for
my $plugin = $cmd->plugin_for($command);
This method returns the plugin (module) for the given command. If no
plugin implements the command, it returns false.
get_command
my ($command_name, $opt, @args) = $app->get_command(@args);
Process arguments and into a command name and (optional) global
options.
usage
print $self->app->usage->text;
Returns the usage object for the global options.
usage_desc
The top level usage line. Looks something like
"yourapp [options] <command>"
global_opt_spec
Returns an empty list. Can be overridden for pre-dispatch option
processing. This is useful for flags like --verbose.
usage_error
$self->usage_error("Something's wrong!");
Used to die with nice usage output, during "validate_args".
TODO
· publish and bring in Log::Speak (simple quiet/verbose output)
· publish and use our internal enhanced describe_options
· publish and use our improved simple input routines
AUTHOR
Ricardo Signes <rjbs@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Ricardo Signes.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
perl v5.14.1 2011-03-18 App::Cmd(3)
