.\" 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 "MooX::Cmd 3pm"
.TH MooX::Cmd 3pm "2015-05-29" "perl v5.20.2" "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"
MooX::Cmd \- Giving an easy Moo style way to make command organized CLI apps
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package MyApp;
\&
\&  use Moo;
\&  use MooX::Cmd;
\&
\&  sub execute {
\&    my ( $self, $args_ref, $chain_ref ) = @_;
\&    my @extra_argv = @{$args_ref};
\&    my @chain = @{$chain_ref} # in this case only ( $myapp )
\&                              # where $myapp == $self
\&  }
\&
\&  1;
\& 
\&  package MyApp::Cmd::Command;
\&  # for "myapp command"
\&
\&  use Moo;
\&  use MooX::Cmd;
\&
\&  # gets executed on "myapp command" but not on "myapp command command"
\&  # there MyApp::Cmd::Command still gets instantiated and for the chain
\&  sub execute {
\&    my ( $self, $args_ref, $chain_ref ) = @_;
\&    my @chain = @{$chain_ref} # in this case ( $myapp, $myapp_cmd_command )
\&                              # where $myapp_cmd_command == $self
\&  }
\&
\&  1;
\&
\&  package MyApp::Cmd::Command::Cmd::Command;
\&  # for "myapp command command"
\&
\&  use Moo;
\&  use MooX::Cmd;
\&
\&  # gets executed on "myapp command command" and will not get instantiated
\&  # on "myapp command" cause it doesnt appear in the chain there
\&  sub execute {
\&    my ( $self, $args_ref, $chain_ref ) = @_;
\&    my @chain = @{$chain_ref} # in this case ( $myapp, $myapp_cmd_command,
\&                              # $myapp_cmd_command_cmd_command )
\&                              # where $myapp_cmd_command_cmd_command == $self
\&  }
\&
\&  package MyZapp;
\&
\&  use Moo;
\&  use MooX::Cmd execute_from_new => 0;
\&
\&  sub execute {
\&    my ( $self ) = @_;
\&    my @extra_argv = @{$self\->command_args};
\&    my @chain = @{$self\->command_chain} # in this case only ( $myzapp )
\&                              # where $myzapp == $self
\&  }
\&
\&  1;
\& 
\&  package MyZapp::Cmd::Command;
\&  # for "myapp command"
\&
\&  use Moo;
\&  use MooX::Cmd execute_from_new => 0;
\&
\&  # gets executed on "myapp command" but not on "myapp command command"
\&  # there MyApp::Cmd::Command still gets instantiated and for the chain
\&  sub execute {
\&    my ( $self ) = @_;
\&    my @extra_argv = @{$self\->command_args};
\&    my @chain = @{$self\->command_chain} # in this case ( $myzapp, $myzapp_cmd_command )
\&                              # where $myzapp_cmd_command == $self
\&  }
\&
\&  1;
\&  package main;
\&
\&  use MyApp;
\&
\&  MyZapp\->new_with_cmd\->execute();
\&  MyApp\->new_with_cmd;
\&
\&  1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Eases the writing of command line utilities, accepting commands and
subcommands and so on. These commands can form a tree, which is
mirrored in the package structure. On invocation each command along
the path through the tree (starting from the toplevel command
through to the most specific one) is instanciated.
.PP
Each command needs to have an \f(CW\*(C`execute\*(C'\fR function, accepting three
parameters:
.ie n .IP """self""" 4
.el .IP "\f(CWself\fR" 4
.IX Item "self"
A reference to the specific MooX::Cmd object that is executing.
.ie n .IP """args""" 4
.el .IP "\f(CWargs\fR" 4
.IX Item "args"
An ArrayRef of arguments passed to \f(CW\*(C`self\*(C'\fR. This only encompasses
arguments of the most specific (read: right-most) command.
.ie n .IP """chain""" 4
.el .IP "\f(CWchain\fR" 4
.IX Item "chain"
An ArrayRef of \f(CW\*(C`MooX::Cmd\*(C'\fRs along the tree path, as specified on
the command line.
.PP
\&\fBNote that only the execute function of the most specific command is executed.\fR
.PP
\fIMooX::Cmd Attributes\fR
.IX Subsection "MooX::Cmd Attributes"
.PP
Each command has some attributes set by MooX::Cmd during
initialization:
.ie n .IP """command_chain""" 4
.el .IP "\f(CWcommand_chain\fR" 4
.IX Item "command_chain"
Same as \f(CW\*(C`chain\*(C'\fR argument to \f(CW\*(C`execute\*(C'\fR.
.ie n .IP """command_name""" 4
.el .IP "\f(CWcommand_name\fR" 4
.IX Item "command_name"
\&\s-1TODO\s0
.ie n .IP """command_commands""" 4
.el .IP "\f(CWcommand_commands\fR" 4
.IX Item "command_commands"
\&\s-1TODO\s0
.ie n .IP """command_args""" 4
.el .IP "\f(CWcommand_args\fR" 4
.IX Item "command_args"
\&\s-1TODO\s0
.ie n .IP """command_base""" 4
.el .IP "\f(CWcommand_base\fR" 4
.IX Item "command_base"
\&\s-1TODO\s0
.SS "Examples"
.IX Subsection "Examples"
\fIA Single Toplevel Command\fR
.IX Subsection "A Single Toplevel Command"
.PP
.Vb 4
\&  #!/usr/bin/env perl
\&  package MyApp;
\&  use Moo;
\&  use MooX::Cmd;
\&
\&  sub execute {
\&    my ($self,$args,$chain) = @_;
\&    printf("%s.execute(\e$self,[%s],[%s])\en",
\&      ref($self),                       # which command is executing?
\&      join(", ", @$args ),              # what where the arguments?
\&      join(", ", map { ref } @$chain)   # what\*(Aqs in the command chain?
\&    );
\&  }
\&
\&  package main;
\&  MyApp\->new_with_cmd();
.Ve
.PP
Some sample invocations:
.PP
.Vb 2
\& $ ./MyApp.pl
\& MyApp.execute($self,[],[MyApp])
\&
\& $./MyApp.pl \-\-opt1
\& MyApp.execute($self,[\-\-opt1],[MyApp])
\&
\& $ ./MyApp.pl \-\-opt1 arg
\& MyApp.execute($self,[\-\-opt1, arg],[MyApp])
.Ve
.PP
\fIToplevel Command with Subcommand\fR
.IX Subsection "Toplevel Command with Subcommand"
.PP
.Vb 5
\&  #!/usr/bin/env perl
\&  # let\*(Aqs define a base class containing our generic execute
\&  # function to save some typing...
\&  package CmdBase;
\&  use Moo;
\&
\&  sub execute {
\&    my ($self,$args,$chain) = @_;
\&    printf("%s.execute(\e$self,[%s],[%s])\en",
\&      ref($self),
\&      join(", ", @$args ),
\&      join(", ", map { ref } @$chain)
\&    );
\&  }
\&
\&  package MyApp;
\&  # toplevel command/app
\&  use Moo;
\&  use MooX::Cmd;
\&  extends \*(AqCmdBase\*(Aq;
\&
\&  package MyApp::Cmd::frobnicate;
\&  # can be called via ./MyApp.pl frobnicate
\&  use Moo;
\&  use MooX::Cmd;
\&  extends \*(AqCmdBase\*(Aq;
\&
\&  package main;
\&  MyApp\->new_with_cmd();
.Ve
.PP
And some sample invocations:
.PP
.Vb 2
\&  $ ./MyApp.pl frobnicate
\&  MyApp::Cmd::frobnicate.execute($self,[],[MyApp, MyApp::Cmd::frobnicate])
.Ve
.PP
As you can see the chain contains our toplevel command object and
then the specififc one.
.PP
.Vb 2
\&  $ ./MyApp.pl frobnicate arg1
\&  MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])
.Ve
.PP
Arguments are passed via the \f(CW\*(C`args\*(C'\fR parameter.
.PP
.Vb 2
\&  $ ./MyApp.pl some \-\-stuff frobnicate arg1
\&  MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])
.Ve
.PP
Arguments to commands higher in the tree get ignored if they don't
match a command.
.PP
\fIAccess Toplevel Attributes via Chain\fR
.IX Subsection "Access Toplevel Attributes via Chain"
.PP
.Vb 3
\&  #!/usr/bin/env perl
\&  package CmdBase;
\&  use Moo;
\&
\&  sub execute {
\&    my ($self,$args,$chain) = @_;
\&    printf("%s.execute(\e$self,[%s],[%s])\en",
\&      ref($self),
\&      join(", ", @$args ),
\&      join(", ", map { ref } @$chain)
\&    );
\&  }
\&
\&  package MyApp;
\&  use Moo;
\&  use MooX::Cmd;
\&  extends \*(AqCmdBase\*(Aq;
\&
\&  has somevar => ( is => \*(Aqro\*(Aq, default => \*(Aqsomeval\*(Aq );
\&
\&  package MyApp::Cmd::frobnicate;
\&  use Moo;
\&  use MooX::Cmd;
\&  extends \*(AqCmdBase\*(Aq;
\&
\&  around execute => sub {
\&    my ($orig,$self,$args,$chain) = @_;
\&    $self\->$orig($args,$chain);
\&    # we can access toplevel attributes via the chain...
\&    printf("MyApp\->somevar = \*(Aq%s\*(Aq\en", $chain\->[0]\->somevar);
\&  };
\&
\&  package main;
\&  MyApp\->new_with_cmd();
.Ve
.PP
A sample invocation
.PP
.Vb 3
\&  $ ./MyApp.pl some \-\-stuff frobnicate arg1
\&  MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])
\&  MyApp\->somevar = someval
.Ve
.SS "MooX::Options integration"
.IX Subsection "MooX::Options integration"
You can integrate MooX::Options simply by using it and declaring
some options, like so:
.PP
.Vb 5
\&  #!/usr/bin/env perl
\&  package MyApp;
\&  use Moo;
\&  use MooX::Cmd;
\&  use MooX::Options;
\&
\&  option debug => ( is => \*(Aqro\*(Aq );
\&
\&  sub execute {
\&    my ($self,$args,$chain) = @_;
\&    print "debugging enabled!\en" if $self\->{debug};
\&  }
\&
\&  package main;
\&  MyApp\->new_with_cmd();
.Ve
.PP
A sample invocation
.PP
.Vb 2
\&  $ ./MyApp\-Options.pl \-\-debug
\&  debugging enabled!
.Ve
.PP
\&\fBNote, that each command and subcommand has its own options.\fR, so options are
parsed for the specific context and used for the instantiation:
.PP
.Vb 1
\&  $ ./MyApp.pl \-\-argformyapp command \-\-argformyappcmdcommand ...
.Ve
.SH "SUPPORT"
.IX Header "SUPPORT"
Repository
.PP
.Vb 2
\&  http://github.com/Getty/p5\-moox\-cmd
\&  Pull request and additional contributors are welcome
.Ve
.PP
Issue Tracker
.PP
.Vb 3
\&  http://github.com/Getty/p5\-moox\-cmd/issues
\&  http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooX\-Cmd
\&  bug\-moox\-cmd at rt.cpan.org
.Ve
.SH "THANKS"
.IX Header "THANKS"
.IP "Lukas Mai (mauke), Toby Inkster (tobyink)" 4
.IX Item "Lukas Mai (mauke), Toby Inkster (tobyink)"
Gave some helpful advice for solving difficult issues
.IP "Celogeek San" 4
.IX Item "Celogeek San"
Integration into MooX::Options for better help messages and suit team play
.IP "Torsten Raudssus (Getty)" 4
.IX Item "Torsten Raudssus (Getty)"
did the initial work and brought it to \s-1CPAN\s0
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2012\-2013 Torsten Raudssus, Copyright 2013\-2015 Jens Rehsack.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See <http://dev.perl.org/licenses/> for more information.