| 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; |