.\" 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 "MooseX::App 3pm"
.TH MooseX::App 3pm "2014-10-15" "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"
MooseX::App \- Write user\-friendly command line apps with even less suffering
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In your base class:
.PP
.Vb 2
\&  package MyApp;
\&  use MooseX::App qw(Color);
\& 
\&  option \*(Aqglobal_option\*(Aq => (
\&      is            => \*(Aqrw\*(Aq,
\&      isa           => \*(AqBool\*(Aq,
\&      documentation => q[Enable this to do fancy stuff],
\&  ); # Global option
\&  
\&  has \*(Aqprivate\*(Aq => ( 
\&      is              => \*(Aqrw\*(Aq,
\&  ); # not exposed
.Ve
.PP
Write multiple command classes (If you have only a single command class
you should use MooseX::App::Simple instead)
.PP
.Vb 3
\&  package MyApp::SomeCommand;
\&  use MooseX::App::Command; # important (also imports Moose)
\&  extends qw(MyApp); # optional, only if you want to use global options from base class
\&  
\&  # Positional parameter
\&  parameter \*(Aqsome_parameter\*(Aq => (
\&      is            => \*(Aqrw\*(Aq,
\&      isa           => \*(AqStr\*(Aq,
\&      required      => 1,
\&      documentation => q[Some parameter that you need to supply],
\&  );
\&  
\&  option \*(Aqsome_option\*(Aq => (
\&      is            => \*(Aqrw\*(Aq,
\&      isa           => \*(AqInt\*(Aq,
\&      required      => 1,
\&      documentation => q[Very important option!],
\&  ); # Option
\&  
\&  sub run {
\&      my ($self) = @_;
\&      # Do something
\&  }
.Ve
.PP
And then you need a simple wrapper script (called eg. myapp):
.PP
.Vb 3
\& #!/usr/bin/env perl
\& use MyApp;
\& MyApp\->new_with_command\->run;
.Ve
.PP
On the command line:
.PP
.Vb 4
\& bash$ myapp help
\& usage:
\&     myapp <command> [long options...]
\&     myapp help
\& 
\& global options:
\&     \-\-global_option    Enable this to do fancy stuff [Flag]
\&     \-\-help \-\-usage \-?  Prints this usage information. [Flag]
\& 
\& available commands:
\&     some_command    Description of some command
\&     another_command Description of another command
\&     help            Prints this usage information
.Ve
.PP
or
.PP
.Vb 5
\& bash$ myapp some_command \-\-help
\& usage:
\&     myapp some_command <SOME_PARAMETER> [long options...]
\&     myapp help
\&     myapp some_command \-\-help
\& 
\& parameters:
\&     some_parameter     Some parameter that you need to supply [Required]
\& 
\& options:
\&     \-\-global_option    Enable this to do fancy stuff [Flag]
\&     \-\-some_option      Very important option! [Int,Required]
\&     \-\-help \-\-usage \-?  Prints this usage information. [Flag]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
MooseX-App is a highly customisable helper to write user-friendly 
command line applications without having to worry about most of the annoying 
things usually involved. Just take any existing Moose class, add a single 
line (\f(CW\*(C`use MooseX\-App qw(PluginA PluginB ...);\*(C'\fR) and create one class
for each command in an underlying namespace. Options and positional parameters
can be defined as simple Moose accessors.
.PP
MooseX-App will then
.IP "\(bu" 4
Find, load and initialise the command classes (see MooseX-App-Simple
for single command applications)
.IP "\(bu" 4
Create automated help and documentation from modules \s-1POD\s0 as well as
attributes metadata and type constraints
.IP "\(bu" 4
Read, encode and validate the command line options and positional 
parameters entered by the user from \f(CW@ARGV\fR and \f(CW%ENV\fR
.IP "\(bu" 4
Provide helpful error messages if user input cannot be validated (
either missing or wrong attributes or Moose type constraints not satisfied)
.PP
Commandline options are defined using the 'option' keyword which accepts
the same attributes as Moose' 'has' keyword.
.PP
.Vb 4
\&  option \*(Aqsome_option\*(Aq => (
\&      is            => \*(Aqrw\*(Aq,
\&      isa           => \*(AqStr\*(Aq,
\&  );
.Ve
.PP
This is equivalent to
.PP
.Vb 6
\&  has \*(Aqsome_option\*(Aq => (
\&      is            => \*(Aqrw\*(Aq,
\&      isa           => \*(AqStr\*(Aq,
\&      traits        => [\*(AqAppOption\*(Aq],   # Load extra metaclass
\&      cmd_type      => \*(Aqoption\*(Aq,        # Set attribute type
\&  );
.Ve
.PP
Positional parameters are defined with the 'parameter' keyword
.PP
.Vb 4
\&  parameter \*(Aqsome_option\*(Aq => (
\&      is            => \*(Aqrw\*(Aq,
\&      isa           => \*(AqStr\*(Aq,
\&  );
.Ve
.PP
This is equivalent to
.PP
.Vb 6
\&  has \*(Aqsome_option\*(Aq => (
\&      is            => \*(Aqrw\*(Aq,
\&      isa           => \*(AqStr\*(Aq,
\&      traits        => [\*(AqAppOption\*(Aq],
\&      cmd_type      => \*(Aqparameter\*(Aq,
\&  );
.Ve
.PP
Furthermore all options and parameters can also be supplied vie \f(CW%ENV\fR
.PP
.Vb 5
\&  option \*(Aqsome_option\*(Aq => (
\&      is            => \*(Aqrw\*(Aq,
\&      isa           => \*(AqStr\*(Aq,
\&      cmd_env       => \*(AqSOME_OPTION\*(Aq,
\&  );
.Ve
.PP
Read the Tutorial for getting started with a simple 
MooseX::App command line application.
.SH "METHODS"
.IX Header "METHODS"
.SS "new_with_command"
.IX Subsection "new_with_command"
.Vb 1
\& my $myapp_command = MyApp\->new_with_command();
.Ve
.PP
This constructor reads the command line arguments and tries to create a 
command class instance. If it fails it retuns a 
MooseX::App::Message::Envelope object holding an error message.
.PP
You can pass a hash of default/fallback params to new_with_command
.PP
.Vb 1
\& my $obj = MyApp\->new_with_command(%default);
.Ve
.SS "initialize_command_class"
.IX Subsection "initialize_command_class"
.Vb 1
\& my $obj = MyApp\->initialize_command_class($command_name,%default);
.Ve
.PP
Helper method to instantiate the command class for the given command.
.SH "GLOBAL OPTIONS"
.IX Header "GLOBAL OPTIONS"
.SS "app_base"
.IX Subsection "app_base"
.Vb 1
\& app_base \*(Aqmy_script\*(Aq; # Defaults to $0
.Ve
.PP
Usually MooseX::App will take the name of the calling wrapper script to 
construct the program name in various help messages. This name can 
be changed via the app_base function.
.SS "app_namespace"
.IX Subsection "app_namespace"
.Vb 1
\& app_namespace \*(AqMyApp::Commands\*(Aq, \*(AqYourApp::MoreCommands\*(Aq;
.Ve
.PP
Usually MooseX::App will take the package name of the base class as the 
namespace for commands. This namespace can be changed and you can add
multiple extra namespaces.
.SS "app_fuzzy"
.IX Subsection "app_fuzzy"
.Vb 3
\& app_fuzzy(1); # default
\& OR
\& app_fuzzy(0);
.Ve
.PP
Enables fuzzy matching of commands and attributes. Is turned on by default.
.SS "app_strict"
.IX Subsection "app_strict"
.Vb 3
\& app_strict(0); # default 
\& OR
\& app_strict(1);
.Ve
.PP
If strict is enabled the program will terminate with an error message if
superfluous/unknown positional parameters are supplied. If disabled all 
extra parameters will be copied to the extra_argv attribute.
.PP
The command_strict config in the command classes allows one to set this option
individually for each command.
.SS "app_prefer_commandline"
.IX Subsection "app_prefer_commandline"
.Vb 3
\& app_prefer_commandline(0); # default
\& or
\& app_prefer_commandline(1);
.Ve
.PP
Specifies if parameters/options supplied via \f(CW@ARGV\fR,%ENV should take precedence
over arguments passed to new_with_command.
.SS "app_command_name"
.IX Subsection "app_command_name"
.Vb 5
\& app_command_name {
\&     my ($package) = shift;
\&     # munge package name;
\&     return $command_name;
\& };
.Ve
.PP
This sub can be used to control how package names should be translated
to command names.
.SS "app_description"
.IX Subsection "app_description"
Set the description. If not set this information will be taken from the
Pod \s-1DESCRIPTION\s0 or \s-1OVERVIEW\s0 sections.
.SS "app_usage"
.IX Subsection "app_usage"
Set custom usage. If not set this will be taken from the Pod \s-1SYNOPSIS\s0 or 
\&\s-1USAGE\s0 section. If those sections are not available, the usage
information will be autogenerated.
.SH "GLOBAL ATTRIBUTES"
.IX Header "GLOBAL ATTRIBUTES"
All MooseX::App classes will have two extra attributes
.SS "extra_argv"
.IX Subsection "extra_argv"
Carries all parameters from \f(CW@ARGV\fR that were not consumed (only if app_strict
is turned off, otherwise superfluous parameters will raise an exception).
.SS "help_flag"
.IX Subsection "help_flag"
Help flag that is set when help was requested.
.SH "ATTRIBUTE OPTIONS"
.IX Header "ATTRIBUTE OPTIONS"
.IP "\(bu" 4
cmd_tags \- Extra tags
.IP "\(bu" 4
cmd_flag \- Override option name
.IP "\(bu" 4
cmd_aliases \- Alternative option names
.IP "\(bu" 4
cmd_split \- Split values
.IP "\(bu" 4
cmd_position \- Option/Parameter order
.IP "\(bu" 4
cmd_env \- Read options from \f(CW%ENV\fR
.PP
Refer to MooseX::App::Meta::Role::Attribute::Option for detailed 
documentation.
.SH "METADATA"
.IX Header "METADATA"
MooseX::App will use your class metadata and \s-1POD\s0 to construct the commands and
helpful error\- or usage\- messages. These bits of information are utilised 
and should be provided if possible:
.IP "\(bu" 4
Package names
.IP "\(bu" 4
required options for Moose attributes
.IP "\(bu" 4
documentation options for Moose attributes
.IP "\(bu" 4
Moose type constraints (Bool, ArrayRef, HashRef, Int, Num, and Enum)
.IP "\(bu" 4
\&\s-1POD \s0(\s-1NAME, ABSTRACT, DESCRIPTION, USAGE, SYNOPSIS\s0 and \s-1OVERVIEW\s0 sections)
.IP "\(bu" 4
Dzil \s-1ABSTRACT\s0 tag if no \s-1POD\s0 is available yet
.SH "PLUGINS"
.IX Header "PLUGINS"
The behaviour of MooseX-App can be customised with plugins. To load a
plugin just pass a list of plugin names after the \f(CW\*(C`use MooseX\-App\*(C'\fR statement.
(Attention: order sometimes matters)
.PP
.Vb 1
\& use MooseX::App qw(PluginA PluginB);
.Ve
.PP
Currently the following plugins are shipped with MooseX::App
.IP "\(bu" 4
MooseX::App::Plugin::BashCompletion
.Sp
Adds a command that genereates a bash completion script for your application
.IP "\(bu" 4
MooseX::App::Plugin::Color
.Sp
Colorful output for your MooseX::App applications
.IP "\(bu" 4
MooseX::App::Plugin::Config
.Sp
Config files for MooseX::App applications
.IP "\(bu" 4
MooseX::App::Plugin::ConfigHome
.Sp
Search config files in users home directory
.IP "\(bu" 4
MooseX::App::Plugin::Term
.Sp
Prompt user for options and parameters that were not provided via options or params
.IP "\(bu" 4
MooseX::App::Plugin::Typo
.Sp
Handle typos in command names
.IP "\(bu" 4
MooseX::App::Plugin::Version
.Sp
Adds a command to display the version and license of your application
.IP "\(bu" 4
MooseX::App::Plugin::Man
.Sp
Display full manpage
.PP
Refer to Writing MooseX-App Plugins 
for documentation on how to create your own plugins.
.SH "CAVEATS & KNOWN BUGS"
.IX Header "CAVEATS & KNOWN BUGS"
Startup time may be an issue \- escpecially if you load many plugins. If you do
not require the functionality of plugins and ability for fine grained 
customisation (or Moose for that matter) then you should probably 
use MooX::Options or MooX::Cmd.
.PP
In some cases \- especially when using non-standard class inheritance \- you may
end up with command classes lacking the help attribute. In this case you need
to include the following line in your base class
.PP
.Vb 1
\& with qw(MooseX::App::Role::Common);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Read the Tutorial for getting started with a simple 
MooseX::App command line application.
.PP
For alternatives you can check out
.PP
MooseX::App::Cmd, MooseX::Getopt, MooX::Options, 
MooX::Cmd  and App::Cmd
.SH "SUPPORT"
.IX Header "SUPPORT"
Please report any bugs or feature requests to 
\&\f(CW\*(C`bug\-moosex\-app@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/Public/Bug/Report.html?Queue=MooseX\-App>.  
I will be notified, and then you'll automatically be notified of progress on 
your report as I make changes.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 3
\&    MaroX Kolla\*'r
\&    CPAN ID: MAROS
\&    maros [at] k\-1.com
\&    
\&    http://www.k\-1.com
.Ve
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
In no particular order: Andrew Jones, George Hartzell, Steve Nolte, 
Michael G, Thomas Klausner, Yanick Champoux, Edward Baudrez, David Golden,
J.R. Mash, Thilo Fester, Gregor Herrmann
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
MooseX::App is Copyright (c) 2012\-14 MaroX Kolla\*'r.
.PP
This library is free software and may be distributed under the same terms as 
perl itself. The full text of the licence can be found in the \s-1LICENCE\s0 file 
included with this module.