.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "App::Cmd 3pm"
.TH App::Cmd 3pm "2014-10-20" "perl v5.20.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
App::Cmd \- write command line apps with less suffering
.SH "VERSION"
.IX Header "VERSION"
version 0.324
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
in \fIyourcmd\fR:
.PP
.Vb 2
\&  use YourApp;
\&  YourApp\->run;
.Ve
.PP
in \fIYourApp.pm\fR:
.PP
.Vb 3
\&  package YourApp;
\&  use App::Cmd::Setup \-app;
\&  1;
.Ve
.PP
in \fIYourApp/Command/blort.pm\fR:
.PP
.Vb 3
\&  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;
\&  }
.Ve
.PP
and, finally, at the command line:
.PP
.Vb 1
\&  knight!rjbs$ yourcmd blort \-\-recheck
\&
\&  All blorts successful.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
App::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.
.PP
For information on how to start using App::Cmd, see App::Cmd::Tutorial.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&  my $cmd = App::Cmd\->new(\e%arg);
.Ve
.PP
This method returns a new App::Cmd object.  During initialization, command
plugins will be loaded.
.PP
Valid arguments are:
.PP
.Vb 1
\&  no_commands_plugin \- if true, the command list plugin is not added
\&
\&  no_help_plugin     \- if true, the help plugin is not added
\&
\&  no_version_plugin  \- if true, the version plugin is not added
\&
\&  plugin_search_path \- The path to search for commands in. Defaults to
\&                       results of plugin_search_path method
.Ve
.PP
If \f(CW\*(C`no_commands_plugin\*(C'\fR 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.
.PP
If \f(CW\*(C`no_help_plugin\*(C'\fR 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. \fBNote:\fR \*(L"help\*(R" is the default command, so if you do not load
the default help plugin, you should provide your own or override the
\&\f(CW\*(C`default_command\*(C'\fR method.
.PP
If \f(CW\*(C`no_version_plugin\*(C'\fR is not given, App::Cmd::Command::version will be
required to show the application's version with command \f(CW\*(C`\-\-version\*(C'\fR. The
version command is not included in the command list.
.SS "run"
.IX Subsection "run"
.Vb 1
\&  $cmd\->run;
.Ve
.PP
This method runs the application.  If called the class, it will instantiate a
new App::Cmd object to run.
.PP
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.
.PP
It passes the contents of the global argument array (\f(CW@ARGV\fR) to
"\f(CW\*(C`prepare_command\*(C'\fR", but \f(CW@ARGV\fR is not altered by running an App::Cmd.
.SS "prepare_args"
.IX Subsection "prepare_args"
Normally App::Cmd uses \f(CW@ARGV\fR for its commandline arguments. You can override
this method to change that behavior for testing or otherwise.
.SS "default_args"
.IX Subsection "default_args"
If \f(CW"prepare_args"\fR is not changed and there are no arguments in \f(CW@ARGV\fR,
this method is called and should return an arrayref to be used as the arguments
to the program.  By default, it returns an empty arrayref.
.SS "arg0"
.IX Subsection "arg0"
.SS "full_arg0"
.IX Subsection "full_arg0"
.Vb 1
\&  my $program_name = $app\->arg0;
\&
\&  my $full_program_name = $app\->full_arg0;
.Ve
.PP
These methods return the name of the program invoked to run this application.
This is determined by inspecting \f(CW$0\fR 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.
.PP
If the program was run like this:
.PP
.Vb 1
\&  knight!rjbs$ ~/bin/rpg dice 3d6
.Ve
.PP
Then the methods return:
.PP
.Vb 2
\&  arg0      \- rpg
\&  full_arg0 \- /Users/rjbs/bin/rpg
.Ve
.PP
These values are captured when the App::Cmd object is created, so it is safe to
assign to \f(CW$0\fR later.
.SS "prepare_command"
.IX Subsection "prepare_command"
.Vb 1
\&  my ($cmd, $opt, @args) = $app\->prepare_command(@ARGV);
.Ve
.PP
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.
.SS "default_command"
.IX Subsection "default_command"
This method returns the name of the command to run if none is given on the
command line.  The default default is \*(L"help\*(R"
.SS "execute_command"
.IX Subsection "execute_command"
.Vb 1
\&  $app\->execute_command($cmd, \e%opt, @args);
.Ve
.PP
This method will invoke \f(CW\*(C`validate_args\*(C'\fR and then \f(CW\*(C`run\*(C'\fR on \f(CW$cmd\fR.
.SS "plugin_search_path"
.IX Subsection "plugin_search_path"
This method returns the plugin_search_path as set.  The default implementation,
if called on \*(L"YourApp::Cmd\*(R" will return \*(L"YourApp::Cmd::Command\*(R"
.PP
This is a method because it's fun to override it with, for example:
.PP
.Vb 1
\&  use constant plugin_search_path => _\|_PACKAGE_\|_;
.Ve
.SS "allow_any_unambiguous_abbrev"
.IX Subsection "allow_any_unambiguous_abbrev"
If this method returns true (which, by default, it does \fInot\fR), 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:
.PP
.Vb 3
\&  reticulate
\&  reload
\&  rasterize
.Ve
.PP
Then the user could use \f(CW\*(C`ret\*(C'\fR for \f(CW\*(C`reticulate\*(C'\fR or \f(CW\*(C`ra\*(C'\fR for \f(CW\*(C`rasterize\*(C'\fR and
so on.
.SS "global_options"
.IX Subsection "global_options"
.Vb 1
\&  if ($cmd\->app\->global_options\->{verbose}) { ... }
.Ve
.PP
This method returns the running application's global options as a hashref.  If
there are no options specified, an empty hashref is returned.
.SS "set_global_options"
.IX Subsection "set_global_options"
.Vb 1
\&  $app\->set_global_options(\e%opt);
.Ve
.PP
This method sets the global options.
.SS "command_names"
.IX Subsection "command_names"
.Vb 1
\&  my @names = $cmd\->command_names;
.Ve
.PP
This returns the commands names which the App::Cmd object will handle.
.SS "command_plugins"
.IX Subsection "command_plugins"
.Vb 1
\&  my @plugins = $cmd\->command_plugins;
.Ve
.PP
This method returns the package names of the plugins that implement the
App::Cmd object's commands.
.SS "plugin_for"
.IX Subsection "plugin_for"
.Vb 1
\&  my $plugin = $cmd\->plugin_for($command);
.Ve
.PP
This method returns the plugin (module) for the given command.  If no plugin
implements the command, it returns false.
.SS "get_command"
.IX Subsection "get_command"
.Vb 1
\&  my ($command_name, $opt, @args) = $app\->get_command(@args);
.Ve
.PP
Process arguments and into a command name and (optional) global options.
.SS "usage"
.IX Subsection "usage"
.Vb 1
\&  print $self\->app\->usage\->text;
.Ve
.PP
Returns the usage object for the global options.
.SS "usage_desc"
.IX Subsection "usage_desc"
The top level usage line. Looks something like
.PP
.Vb 1
\&  "yourapp <command> [options]"
.Ve
.SS "global_opt_spec"
.IX Subsection "global_opt_spec"
Returns an empty list. Can be overridden for pre-dispatch option processing.
This is useful for flags like \-\-verbose.
.SS "usage_error"
.IX Subsection "usage_error"
.Vb 1
\&  $self\->usage_error("Something\*(Aqs wrong!");
.Ve
.PP
Used to die with nice usage output, during \f(CW\*(C`validate_args\*(C'\fR.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
publish and bring in Log::Speak (simple quiet/verbose output)
.IP "\(bu" 4
publish and use our internal enhanced describe_options
.IP "\(bu" 4
publish and use our improved simple input routines
.SH "AUTHOR"
.IX Header "AUTHOR"
Ricardo Signes <rjbs@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Ricardo Signes.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.