Cmd.pm untested

filter: Statementstmt 0.0% 0 / 79 Branchbran 0.0% 0 / 28 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 11 Podpod 0.0% 0 / 4 totaltotal 0.0% 0 / 122 CC 15 SCAR 41.1
CC
15
Cov
0%
_attr_to_cmd_options
132.0
run
12.0
build_bin_name
6.0
CRAP 61.0
1 package MooseX::Role::Cmd;
2  
3 use strict;
4 use warnings;
5  
6 use Carp ();
7 use IPC::Cmd ();
8 use Moose::Role;
9 use MooseX::Role::Cmd::Meta::Attribute::Trait;
10  
11 our $VERSION = '0.10';
12  
13 =head1 NAME
14  
15 MooseX::Role::Cmd - Wrap system command binaries the Moose way
16  
17 =head1 SYNOPSIS
18  
19 Create your command wrapper:
20  
21 package Cmd::Perl;
22  
23 use Moose;
24  
25 with 'MooseX::Role::Cmd';
26  
27 has 'e' => (isa => 'Str', is => 'rw');
28  
29 # other perl switches here...
30  
31 1;
32  
33 Use it somewhere else:
34  
35 use Cmd::Perl;
36  
37 my $perl = Cmd::Perl->new(e => q{'print join ", ", @ARGV'});
38  
39 print $perl->run(qw/foo bar baz/);
40  
41 # prints the STDOUT captured from running:
42 # perl -e 'print join ", ", @ARGV' foo bar baz
43  
44 =head1 DESCRIPTION
45  
46 MooseX::Role::Cmd is a L<Moose> role intended to ease the task of building
47 command-line wrapper modules. It automatically maps L<Moose> objects into
48 command strings which are passed to L<IPC::Cmd>.
49  
50 =head1 ATTRIBUTES
51  
52 =head2 $cmd->bin_name
53  
54 Sets the binary executable name for the command you want to run. Defaults
55 the to last part of the class name.
56  
57 =cut
58  
59 has 'bin_name' => (
60 isa => 'Str',
61 is => 'rw',
62 lazy => 1,
63 default => sub { shift->build_bin_name },
64 );
65  
66 =head2 $cmd->stdout
67  
68 Returns the STDOUT buffer captured after running the command.
69  
70 =cut
71  
72 has 'stdout' => ( isa => 'ArrayRef', is => 'rw' );
73  
74 =head2 $cmd->stderr
75  
76 Returns the STDERR buffer captured after running the command.
77  
78 =cut
79  
80 has 'stderr' => ( isa => 'ArrayRef', is => 'rw' );
81  
82 no Moose;
83  
84 =head1 METHODS
85  
86 =head2 $bin_name = $cmd->build_bin_name
87  
88 Builds the default string for the command name based on the class name.
89  
90 =cut
91  
92 # done this way to be overrideable
93 sub build_bin_name {
94 my ($self) = @_;
95 my $class = ref $self;
96 if ( !$class ) {
97 $class = $self;
98 }
99 return lc( ( split '::', $class )[-1] ); ## no critic
100 }
101  
102 =head2 @stdout = $cmd->run(@args);
103  
104 Builds the command string and runs it based on the objects current attribute
105 settings. This will treat all the attributes defined in your class as flags
106 to be passed to the command.
107  
108 B<NOTE:> All quoting issues are left to be solved by the user.
109  
110 =cut
111  
112 sub run {
113 my ( $self, @args ) = @_;
114  
115 my $cmd = $self->bin_name;
116 my $full_path;
117 if ( !( $full_path = IPC::Cmd::can_run($cmd) ) ) {
118 Carp::confess(qq{couldn't find command '$cmd'});
119 }
120  
121 # build full list of cmd args from attrs
122 @args = $self->cmd_args( @args );
123  
124 #warn "CMD: " . $full_path . " " . join (" ", map { "'$_'" } @args );
125 my ( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
126 IPC::Cmd::run( command => [ $full_path, @args ] );
127  
128 if ( !$success ) {
129 Carp::confess("error running '$full_path': " . $error_code);
130 }
131  
132 $self->stdout($stdout_buf);
133 $self->stderr($stderr_buf);
134 return 1;
135 }
136  
137 =head2 cmd_args
138  
139 Returns a list of the computed arguments that will be added to the command
140  
141 =cut
142  
143 sub cmd_args {
144 my ( $self, @extra_args ) = @_;
145  
146 # exclude this role's attributes from the flag list
147 # could use custom metaclasses and introspection, but this will do for now
148 my %non_flag = map { $_ => 1 } __PACKAGE__->meta->get_attribute_list;
149  
150 my @flag_attrs = grep { !$non_flag{$_->name} }
151 grep { substr($_->name, 0, 1) ne '_' }
152 map { $self->meta->get_attribute($_) }
153 $self->meta->get_attribute_list;
154  
155 #####
156 # IS: 2008/10/15
157 # Changed the following to make a start on the suggestion above...
158 #####
159 #my @flags = map { ( "-$_" => $self->$_ ) } @flag_attrs;
160 my @flags = map { ( $self->_attr_to_cmd_options( $_ ) ) } @flag_attrs;
161  
162 my @args = ( @flags, @extra_args );
163  
164 return wantarray ? @args : \@args;
165 }
166  
167 =head1 ADDITIONAL INFORMATION
168  
169 =head2 Setting the Executable
170  
171 By default the name of the binary executable is taken from the last part of the class name
172 (in lower case). The path is set during the L<run> method by scanning through your current
173 PATH for the given executable (see also the 'can_run' function from L<IPC::Cmd>)
174  
175 package MyApp::Commands::Scanner;
176 use Moose;
177 with 'MooseX::Role::Cmd';
178  
179 $cmd = MyApp::Commands::Scanner->new();
180 $cmd->bin_name
181 # /path/to/scanner
182  
183 If this default behaviour doesn't suit your application then you can override the L<build_bin_name>
184 subroutine to explicitly set the executable name
185  
186 sub build_bin_name { 'scanner.exe' }
187 # /path/to/scanner.exe
188  
189 Or you could explicitly set the path with
190  
191 sub build_bin_name { '/only/use/this/path/scanner.exe' }
192 # /only/use/this/path/scanner.exe
193  
194 =head2 How attributes are mapped to parameters
195  
196 The attributes of the consuming package map directly to the parameters passed
197 to the executable. There are a few things to note about the default behaviour
198 governing the way these attributes are mapped.
199  
200 Attribute Default Behaviour (@ARGV)
201 --------- -------------------------
202 single char prefix attr name with '-'
203 multiple char prefix attr name with '--'
204 boolean treat attr as flag (no value)
205 non-boolean treat attr as parameter (with value)
206 value=undef ignore attr
207 name=_name ignore attr
208  
209 These points are illustrated in the following example:
210  
211 package MyApp::Commands::Scanner;
212 use Moose;
213 with 'MooseX::Role::Cmd';
214  
215 has 'i' => ( is => 'rw', isa => 'Str', default => 'input.txt' );
216 has 'out' => ( is => 'rw', isa => 'Str' );
217 has 'verbose' => ( is => 'rw', isa => 'Bool', default => 1 );
218 has 'level' => ( is => 'rw', isa => 'Int' );
219 has 'option' => ( is => 'rw', isa => 'Str' );
220  
221 has '_internal' => ( is => 'ro', isa => Str, reader => internal, default => 'foo' );
222 # attribute names starting with '_' are not included
223  
224 $scanner = MyApp::Commands::Scanner->new( output => '/tmp/scanner.log', level => 5 );
225  
226 $scanner->run;
227 # /path/to/scanner -i input.txt --out /tmp/scanner.log --verbose --level 5
228  
229 =head2 Changing names of parameters
230  
231 It's possible that the parameters your system command expects do not adhere to this
232 naming scheme. In this case you can use the 'CmdOpt' trait which allows you to
233 specify exactly how you want the parameter to appear on the command line.
234  
235 has 'option' => ( isa => 'Bool' );
236 # --option
237  
238 =head3 cmdopt_prefix
239  
240 This lets you override the prefix used for the option (for example to use the short
241 form of multi-character options).
242  
243 has 'option' => ( traits => [ 'CmdOpt' ],
244 isa => 'Bool',
245 cmdopt_prefix => '-'
246 );
247 # -option
248  
249 =head3 cmdopt_name
250  
251 This lets you completely override the option name with whatever string you want
252  
253 has 'option' => ( traits => [ 'CmdOpt' ],
254 isa => 'Bool',
255 cmdopt_name => '+foo'
256 );
257 # +foo
258  
259 =head3 cmdopt_env
260  
261 This will set an environment variable with the attribute name/value rather than pass
262 it along as a command line param
263  
264 has 'home_dir' => ( traits => [ 'CmdOpt' ],
265 isa => 'Str',
266 cmdopt_env => 'APP_HOME'
267 default => '/my/app/home'
268 );
269  
270 # ENV{APP_HOME} = /my/app/home
271  
272 See L<MooseX::Role::Cmd::Meta::Attribute::Trait>
273  
274 =head1 PRIVATE METHODS
275  
276 =head2 _attr_to_cmd_options
277  
278 Returns an array (or array reference) of command options that correspond
279 to the given attribute name.
280  
281 =cut
282  
283 sub _attr_to_cmd_options {
284 my ( $self, $attr ) = @_;
285  
286 my $attr_name = $attr->name;
287  
288 # decide the default settings
289 my $opt_prefix = length( $attr_name ) == 1 ? '-' : '--';
290 my $opt_name = $attr_name;
291  
292 my $attr_value = $attr->get_value( $self );
293  
294 # override defaults with Traits
295 if ( $attr->does('MooseX::Role::Cmd::Meta::Attribute::Trait') ) {
296  
297 # deal with $ENV
298 if ($attr->has_cmdopt_env) {
299 my $env_key = $attr->cmdopt_env;
300 if ( defined $attr_value ) {
301 $ENV{$env_key} = $attr_value;
302 }
303 # environment vars not used as params
304 return;
305 }
306  
307 if ($attr->has_cmdopt_prefix) {
308 $opt_prefix = $attr->cmdopt_prefix;
309 }
310  
311 if ($attr->has_cmdopt_name) {
312 $opt_prefix = ''; # name overrides prefix
313 $opt_name = $attr->cmdopt_name;
314 }
315 }
316  
317 # create the full option name
318 my $opt_fullname = $opt_prefix . $opt_name;
319  
320 my @options = ();
321 if ( $attr->type_constraint->is_a_type_of( 'Bool' ) ) {
322 push @options, ( $opt_fullname )
323 if $attr_value; # only add if attr is true
324 }
325 else {
326 if ( defined $attr_value ) { # only add if attr value is defined
327 push @options, ( $opt_fullname, $attr_value )
328 }
329 }
330  
331 return wantarray ? @options : \@options;
332 }
333  
334 =head1 AUTHOR
335  
336 Eden Cardim <edencardim@gmail.com>
337  
338 =head1 LICENSE
339  
340 This library is free software, you can redistribute it and/or modify it under
341 the same terms as Perl itself.
342  
343 =cut
344  
345 1;