NAME

       MooX::Cmd - Giving an easy Moo style way to make command organized CLI apps

SYNOPSIS

         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;

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.

       Each command needs to have an "execute" function, accepting three parameters:

       "self"
           A reference to the specific MooX::Cmd object that is executing.

       "args"
           An ArrayRef of arguments passed to "self". This only encompasses arguments of the most
           specific (read: right-most) command.

       "chain"
           An ArrayRef of "MooX::Cmd"s along the tree path, as specified on the command line.

       Note that only the execute function of the most specific command is executed.

       MooX::Cmd Attributes

       Each command has some attributes set by MooX::Cmd during initialization:

       "command_chain"
           Same as "chain" argument to "execute".

       "command_name"
           TODO

       "command_commands"
           TODO

       "command_args"
           TODO

       "command_base"
           TODO

   Examples
       A Single Toplevel Command

         #!/usr/bin/env perl
         package MyApp;
         use Moo;
         use MooX::Cmd;

         sub execute {
           my ($self,$args,$chain) = @_;
           printf("%s.execute(\$self,[%s],[%s])\n",
             ref($self),                       # which command is executing?
             join(", ", @$args ),              # what where the arguments?
             join(", ", map { ref } @$chain)   # what's in the command chain?
           );
         }

         package main;
         MyApp->new_with_cmd();

       Some sample invocations:

        $ ./MyApp.pl
        MyApp.execute($self,[],[MyApp])

        $./MyApp.pl --opt1
        MyApp.execute($self,[--opt1],[MyApp])

        $ ./MyApp.pl --opt1 arg
        MyApp.execute($self,[--opt1, arg],[MyApp])

       Toplevel Command with Subcommand

         #!/usr/bin/env perl
         # let's 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(\$self,[%s],[%s])\n",
             ref($self),
             join(", ", @$args ),
             join(", ", map { ref } @$chain)
           );
         }

         package MyApp;
         # toplevel command/app
         use Moo;
         use MooX::Cmd;
         extends 'CmdBase';

         package MyApp::Cmd::frobnicate;
         # can be called via ./MyApp.pl frobnicate
         use Moo;
         use MooX::Cmd;
         extends 'CmdBase';

         package main;
         MyApp->new_with_cmd();

       And some sample invocations:

         $ ./MyApp.pl frobnicate
         MyApp::Cmd::frobnicate.execute($self,[],[MyApp, MyApp::Cmd::frobnicate])

       As you can see the chain contains our toplevel command object and then the specififc one.

         $ ./MyApp.pl frobnicate arg1
         MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])

       Arguments are passed via the "args" parameter.

         $ ./MyApp.pl some --stuff frobnicate arg1
         MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])

       Arguments to commands higher in the tree get ignored if they don't match a command.

       Access Toplevel Attributes via Chain

         #!/usr/bin/env perl
         package CmdBase;
         use Moo;

         sub execute {
           my ($self,$args,$chain) = @_;
           printf("%s.execute(\$self,[%s],[%s])\n",
             ref($self),
             join(", ", @$args ),
             join(", ", map { ref } @$chain)
           );
         }

         package MyApp;
         use Moo;
         use MooX::Cmd;
         extends 'CmdBase';

         has somevar => ( is => 'ro', default => 'someval' );

         package MyApp::Cmd::frobnicate;
         use Moo;
         use MooX::Cmd;
         extends 'CmdBase';

         around execute => sub {
           my ($orig,$self,$args,$chain) = @_;
           $self->$orig($args,$chain);
           # we can access toplevel attributes via the chain...
           printf("MyApp->somevar = '%s'\n", $chain->[0]->somevar);
         };

         package main;
         MyApp->new_with_cmd();

       A sample invocation

         $ ./MyApp.pl some --stuff frobnicate arg1
         MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])
         MyApp->somevar = someval

   MooX::Options integration
       You can integrate MooX::Options simply by using it and declaring some options, like so:

         #!/usr/bin/env perl
         package MyApp;
         use Moo;
         use MooX::Cmd;
         use MooX::Options;

         option debug => ( is => 'ro' );

         sub execute {
           my ($self,$args,$chain) = @_;
           print "debugging enabled!\n" if $self->{debug};
         }

         package main;
         MyApp->new_with_cmd();

       A sample invocation

         $ ./MyApp-Options.pl --debug
         debugging enabled!

       Note, that each command and subcommand has its own options., so options are parsed for the
       specific context and used for the instantiation:

         $ ./MyApp.pl --argformyapp command --argformyappcmdcommand ...

SUPPORT

       Repository

         http://github.com/Getty/p5-moox-cmd
         Pull request and additional contributors are welcome

       Issue Tracker

         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

THANKS

       Lukas Mai (mauke), Toby Inkster (tobyink)
           Gave some helpful advice for solving difficult issues

       Celogeek San
           Integration into MooX::Options for better help messages and suit team play

       Torsten Raudssus (Getty)
           did the initial work and brought it to CPAN

LICENSE AND COPYRIGHT

       Copyright 2012-2013 Torsten Raudssus, Copyright 2013-2017 Jens Rehsack.

       This program is free software; you can redistribute it and/or modify it under the terms of
       either: the GNU General Public License as published by the Free Software Foundation; or
       the Artistic License.

       See <http://dev.perl.org/licenses/> for more information.