Cmd.pm

filter: Statementstmt 100% 45 / 45 Branchbran 95.0% 19 / 20 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 9 / 9 Podpod n/a totaltotal 98.6% 73 / 74 CC 12 SCAR 15.7
CC
12
Cov
98%
import
8.0
__ANON__
5.0
BEGIN
1.0
CRAP 4.8
« Cmd/Role.pm ↑ Summary Cmd/Role/ConfigFromFile.pm »
1 package MooX::Cmd;
2  
3 6 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 6 our $VERSION = "0.016_001";
7  
8 6 ▶use Package::Stash;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 sub import
11 {
12 21 ▶ my (undef, %import_options) = @_;
Subroutine import: called CC=8 SCAR=20.8
13 21 my $caller = caller;
14 21 my @caller_isa;
15 ## no critic qw(ProhibitNoStrict)
16 6 ▶ { no strict 'refs'; @caller_isa = @{"${caller}::ISA"} };
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 #don't add this to a role
19 #ISA of a role is always empty !
20 21 ▶ @caller_isa or return;
Branch: 1 branch
BranchTrueFalseTotal
@caller_isa or return 0 21 21
21  
22 21 my $execute_return_method_name = $import_options{execute_return_method_name};
23  
24 21 ▶ exists $import_options{execute_from_new} or $import_options{execute_from_new} = 1; # set default until we want other way
Branch: 1 branch
BranchTrueFalseTotal
exists $import_options{"execute_from_new"} or $import_options{"execute_from_new"} = 1 14 7 21
25  
26 21 my $stash = Package::Stash->new($caller);
27 defined $import_options{execute_return_method_name}
28 and $stash->add_symbol('&' . $import_options{execute_return_method_name},
29 21 ▶ sub { shift->{$import_options{execute_return_method_name}} });
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 1 branch
BranchTrueFalseTotal
defined $import_options{"execute_return_method_name"} and $stash->add_symbol('&' . $import_options{"execute_return_method_name"}, sub { (shift())->{$import_options{"execute_return_method_name"}}; } ) 1 20 21
30 21 ▶ defined $import_options{creation_method_name} or $import_options{creation_method_name} = "new_with_cmd";
Branch: 1 branch
BranchTrueFalseTotal
defined $import_options{"creation_method_name"} or $import_options{"creation_method_name"} = "new_with_cmd" 20 1 21
31 21 ▶ $stash->add_symbol('&' . $import_options{creation_method_name}, sub { shift->_initialize_from_cmd(@_); });
Subroutine __ANON__: called CC=1 SCAR=0.0
32  
33 my $apply_modifiers = sub {
34 21 ▶ $caller->can('_initialize_from_cmd') and return;
Subroutine __ANON__: called CC=5 SCAR=16.1
Branch: 1 branch
BranchTrueFalseTotal
$caller->can("_initialize_from_cmd") and return 1 20 21
35 20 my $with = $caller->can('with');
36 20 $with->('MooX::Cmd::Role');
37 # XXX prove whether it can chained ...
38 20 ▶ $import_options{with_config_from_file} and $with->('MooX::ConfigFromFile::Role');
Branch: 1 branch
BranchTrueFalseTotal
$import_options{"with_config_from_file"} and &$with("MooX::ConfigFromFile::Role") 5 15 20
39 20 ▶ $import_options{with_config_from_file} and $with->('MooX::Cmd::Role::ConfigFromFile');
Branch: 1 branch
BranchTrueFalseTotal
$import_options{"with_config_from_file"} and &$with("MooX::Cmd::Role::ConfigFromFile") 5 15 20
40 20 ▶ $import_options{with_abbrev_cmds} and $with->('MooX::Cmd::Role::AbbrevCmds');
Branch: 1 branch
BranchTrueFalseTotal
$import_options{"with_abbrev_cmds"} and &$with("MooX::Cmd::Role::AbbrevCmds") 2 18 20
41 21 };
42 21 $apply_modifiers->();
43  
44 21 my %default_modifiers = (
45 base => '_build_command_base',
46 execute_method_name => '_build_command_execute_method_name',
47 execute_return_method_name => '_build_command_execute_return_method_name',
48 creation_chain_methods => '_build_command_creation_chain_methods',
49 creation_method_name => '_build_command_creation_method_name',
50 execute_from_new => '_build_command_execute_from_new',
51 );
52  
53 21 my $around;
54 21 foreach my $opt_key (keys %default_modifiers)
55 {
56 126 ▶ exists $import_options{$opt_key} or next;
Branch: 1 branch
BranchTrueFalseTotal
exists $import_options{$opt_key} or next 83 43 126
57 43 ▶ $around or $around = $caller->can('around');
Branch: 1 branch
BranchTrueFalseTotal
$around or $around = $caller->can("around") 21 22 43
58 43 ▶ $around->($default_modifiers{$opt_key} => sub { $import_options{$opt_key} });
Subroutine __ANON__: called CC=1 SCAR=0.0
59 }
60  
61 21 return;
62 }
63  
64 6 1;
65  
66 =encoding utf8
67  
68 =head1 NAME
69  
70 MooX::Cmd - Giving an easy Moo style way to make command organized CLI apps
71  
72 =head1 SYNOPSIS
73  
74 package MyApp;
75  
76 use Moo;
77 use MooX::Cmd;
78  
79 sub execute {
80 my ( $self, $args_ref, $chain_ref ) = @_;
81 my @extra_argv = @{$args_ref};
82 my @chain = @{$chain_ref} # in this case only ( $myapp )
83 # where $myapp == $self
84 }
85  
86 1;
87
88 package MyApp::Cmd::Command;
89 # for "myapp command"
90  
91 use Moo;
92 use MooX::Cmd;
93  
94 # gets executed on "myapp command" but not on "myapp command command"
95 # there MyApp::Cmd::Command still gets instantiated and for the chain
96 sub execute {
97 my ( $self, $args_ref, $chain_ref ) = @_;
98 my @chain = @{$chain_ref} # in this case ( $myapp, $myapp_cmd_command )
99 # where $myapp_cmd_command == $self
100 }
101  
102 1;
103  
104 package MyApp::Cmd::Command::Cmd::Command;
105 # for "myapp command command"
106  
107 use Moo;
108 use MooX::Cmd;
109  
110 # gets executed on "myapp command command" and will not get instantiated
111 # on "myapp command" cause it doesnt appear in the chain there
112 sub execute {
113 my ( $self, $args_ref, $chain_ref ) = @_;
114 my @chain = @{$chain_ref} # in this case ( $myapp, $myapp_cmd_command,
115 # $myapp_cmd_command_cmd_command )
116 # where $myapp_cmd_command_cmd_command == $self
117 }
118  
119 package MyZapp;
120  
121 use Moo;
122 use MooX::Cmd execute_from_new => 0;
123  
124 sub execute {
125 my ( $self ) = @_;
126 my @extra_argv = @{$self->command_args};
127 my @chain = @{$self->command_chain} # in this case only ( $myzapp )
128 # where $myzapp == $self
129 }
130  
131 1;
132
133 package MyZapp::Cmd::Command;
134 # for "myapp command"
135  
136 use Moo;
137 use MooX::Cmd execute_from_new => 0;
138  
139 # gets executed on "myapp command" but not on "myapp command command"
140 # there MyApp::Cmd::Command still gets instantiated and for the chain
141 sub execute {
142 my ( $self ) = @_;
143 my @extra_argv = @{$self->command_args};
144 my @chain = @{$self->command_chain} # in this case ( $myzapp, $myzapp_cmd_command )
145 # where $myzapp_cmd_command == $self
146 }
147  
148 1;
149 package main;
150  
151 use MyApp;
152  
153 MyZapp->new_with_cmd->execute();
154 MyApp->new_with_cmd;
155  
156 1;
157  
158 =head1 DESCRIPTION
159  
160 Eases the writing of command line utilities, accepting commands and
161 subcommands and so on. These commands can form a tree, which is
162 mirrored in the package structure. On invocation each command along
163 the path through the tree (starting from the toplevel command
164 through to the most specific one) is instanciated.
165  
166 Each command needs to have an C<execute> function, accepting three
167 parameters:
168  
169 =over
170  
171 =item C<self>
172  
173 A reference to the specific L<MooX::Cmd> object that is executing.
174  
175 =item C<args>
176  
177 An ArrayRef of arguments passed to C<self>. This only encompasses
178 arguments of the most specific (read: right-most) command.
179  
180 =item C<chain>
181  
182 An ArrayRef of C<MooX::Cmd>s along the tree path, as specified on
183 the command line.
184  
185 =back
186  
187 B<Note that only the execute function of the most specific command is executed.>
188  
189 =head3 L<MooX::Cmd> Attributes
190  
191 Each command has some attributes set by L<MooX::Cmd> during
192 initialization:
193  
194 =over
195  
196 =item C<command_chain>
197  
198 Same as C<chain> argument to C<execute>.
199  
200 =item C<command_name>
201  
202 TODO
203  
204 =item C<command_commands>
205  
206 TODO
207  
208 =item C<command_args>
209  
210 TODO
211  
212 =item C<command_base>
213  
214 TODO
215  
216 =back
217  
218 =head2 Examples
219  
220 =head3 A Single Toplevel Command
221  
222 #!/usr/bin/env perl
223 package MyApp;
224 use Moo;
225 use MooX::Cmd;
226  
227 sub execute {
228 my ($self,$args,$chain) = @_;
229 printf("%s.execute(\$self,[%s],[%s])\n",
230 ref($self), # which command is executing?
231 join(", ", @$args ), # what where the arguments?
232 join(", ", map { ref } @$chain) # what's in the command chain?
233 );
234 }
235  
236 package main;
237 MyApp->new_with_cmd();
238  
239 Some sample invocations:
240  
241 $ ./MyApp.pl
242 MyApp.execute($self,[],[MyApp])
243  
244 $./MyApp.pl --opt1
245 MyApp.execute($self,[--opt1],[MyApp])
246  
247 $ ./MyApp.pl --opt1 arg
248 MyApp.execute($self,[--opt1, arg],[MyApp])
249  
250 =head3 Toplevel Command with Subcommand
251  
252 #!/usr/bin/env perl
253 # let's define a base class containing our generic execute
254 # function to save some typing...
255 package CmdBase;
256 use Moo;
257  
258 sub execute {
259 my ($self,$args,$chain) = @_;
260 printf("%s.execute(\$self,[%s],[%s])\n",
261 ref($self),
262 join(", ", @$args ),
263 join(", ", map { ref } @$chain)
264 );
265 }
266  
267 package MyApp;
268 # toplevel command/app
269 use Moo;
270 use MooX::Cmd;
271 extends 'CmdBase';
272  
273 package MyApp::Cmd::frobnicate;
274 # can be called via ./MyApp.pl frobnicate
275 use Moo;
276 use MooX::Cmd;
277 extends 'CmdBase';
278  
279 package main;
280 MyApp->new_with_cmd();
281  
282 And some sample invocations:
283  
284 $ ./MyApp.pl frobnicate
285 MyApp::Cmd::frobnicate.execute($self,[],[MyApp, MyApp::Cmd::frobnicate])
286  
287 As you can see the chain contains our toplevel command object and
288 then the specififc one.
289  
290 $ ./MyApp.pl frobnicate arg1
291 MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])
292  
293 Arguments are passed via the C<args> parameter.
294  
295 $ ./MyApp.pl some --stuff frobnicate arg1
296 MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])
297  
298 Arguments to commands higher in the tree get ignored if they don't
299 match a command.
300  
301 =head3 Access Toplevel Attributes via Chain
302  
303 #!/usr/bin/env perl
304 package CmdBase;
305 use Moo;
306  
307 sub execute {
308 my ($self,$args,$chain) = @_;
309 printf("%s.execute(\$self,[%s],[%s])\n",
310 ref($self),
311 join(", ", @$args ),
312 join(", ", map { ref } @$chain)
313 );
314 }
315  
316 package MyApp;
317 use Moo;
318 use MooX::Cmd;
319 extends 'CmdBase';
320  
321 has somevar => ( is => 'ro', default => 'someval' );
322  
323 package MyApp::Cmd::frobnicate;
324 use Moo;
325 use MooX::Cmd;
326 extends 'CmdBase';
327  
328 around execute => sub {
329 my ($orig,$self,$args,$chain) = @_;
330 $self->$orig($args,$chain);
331 # we can access toplevel attributes via the chain...
332 printf("MyApp->somevar = '%s'\n", $chain->[0]->somevar);
333 };
334  
335 package main;
336 MyApp->new_with_cmd();
337  
338 A sample invocation
339  
340 $ ./MyApp.pl some --stuff frobnicate arg1
341 MyApp::Cmd::frobnicate.execute($self,[arg1],[MyApp, MyApp::Cmd::frobnicate])
342 MyApp->somevar = someval
343  
344  
345 =head2 L<MooX::Options> integration
346  
347 You can integrate L<MooX::Options> simply by using it and declaring
348 some options, like so:
349  
350 #!/usr/bin/env perl
351 package MyApp;
352 use Moo;
353 use MooX::Cmd;
354 use MooX::Options;
355  
356 option debug => ( is => 'ro' );
357  
358 sub execute {
359 my ($self,$args,$chain) = @_;
360 print "debugging enabled!\n" if $self->{debug};
361 }
362  
363 package main;
364 MyApp->new_with_cmd();
365  
366 A sample invocation
367  
368 $ ./MyApp-Options.pl --debug
369 debugging enabled!
370  
371 B<Note, that each command and subcommand has its own options.>, so options are
372 parsed for the specific context and used for the instantiation:
373  
374 $ ./MyApp.pl --argformyapp command --argformyappcmdcommand ...
375  
376 =head1 SUPPORT
377  
378 Repository
379  
380 http://github.com/Getty/p5-moox-cmd
381 Pull request and additional contributors are welcome
382  
383 Issue Tracker
384  
385 http://github.com/Getty/p5-moox-cmd/issues
386 http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooX-Cmd
387 bug-moox-cmd at rt.cpan.org
388  
389 =head1 THANKS
390  
391 =over
392  
393 =item Lukas Mai (mauke), Toby Inkster (tobyink)
394  
395 Gave some helpful advice for solving difficult issues
396  
397 =item Celogeek San
398  
399 Integration into MooX::Options for better help messages and suit team play
400  
401 =item Torsten Raudssus (Getty)
402  
403 did the initial work and brought it to CPAN
404  
405 =back
406  
407 =head1 LICENSE AND COPYRIGHT
408  
409 Copyright 2012-2013 Torsten Raudssus, Copyright 2013-2017 Jens Rehsack.
410  
411 This program is free software; you can redistribute it and/or modify it
412 under the terms of either: the GNU General Public License as published
413 by the Free Software Foundation; or the Artistic License.
414  
415 See L<http://dev.perl.org/licenses/> for more information.
416  
417 =cut
« Cmd/Role.pm ↑ Summary Cmd/Role/ConfigFromFile.pm »