Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MooX::Cmd(3)	      User Contributed Perl Documentation	  MooX::Cmd(3)

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.

perl v5.32.1			  2017-12-19			  MooX::Cmd(3)

NAME | SYNOPSIS | DESCRIPTION | SUPPORT | THANKS | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MooX::Cmd&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help