1MooseX::Role::Cmd(3)  User Contributed Perl Documentation MooseX::Role::Cmd(3)
2
3
4

NAME

6       MooseX::Role::Cmd - Wrap system command binaries the Moose way
7

SYNOPSIS

9       Create your command wrapper:
10
11           package Cmd::Perl;
12
13           use Moose;
14
15           with 'MooseX::Role::Cmd';
16
17           has 'e' => (isa => 'Str', is => 'rw');
18
19           # other perl switches here...
20
21           1;
22
23       Use it somewhere else:
24
25           use Cmd::Perl;
26
27           my $perl = Cmd::Perl->new(e => q{'print join ", ", @ARGV'});
28
29           print $perl->run(qw/foo bar baz/);
30
31           # prints the STDOUT captured from running:
32           # perl -e 'print join ", ", @ARGV' foo bar baz
33

DESCRIPTION

35       MooseX::Role::Cmd is a Moose role intended to ease the task of building
36       command-line wrapper modules. It automatically maps Moose objects into
37       command strings which are passed to IPC::Cmd.
38

ATTRIBUTES

40   $cmd->bin_name
41       Sets the binary executable name for the command you want to run.
42       Defaults the to last part of the class name.
43
44   $cmd->stdout
45       Returns the STDOUT buffer captured after running the command.
46
47   $cmd->stderr
48       Returns the STDERR buffer captured after running the command.
49

METHODS

51   $bin_name = $cmd->build_bin_name
52       Builds the default string for the command name based on the class name.
53
54   @stdout = $cmd->run(@args);
55       Builds the command string and runs it based on the objects current
56       attribute settings. This will treat all the attributes defined in your
57       class as flags to be passed to the command.
58
59       NOTE: All quoting issues are left to be solved by the user.
60
61   cmd_args
62       Returns a list of the computed arguments that will be added to the
63       command
64

ADDITIONAL INFORMATION

66   Setting the Executable
67       By default the name of the binary executable is taken from the last
68       part of the class name (in lower case). The path is set during the run
69       method by scanning through your current PATH for the given executable
70       (see also the 'can_run' function from IPC::Cmd)
71
72           package MyApp::Commands::Scanner;
73           use Moose;
74           with 'MooseX::Role::Cmd';
75
76           $cmd = MyApp::Commands::Scanner->new();
77           $cmd->bin_name
78           # /path/to/scanner
79
80       If this default behaviour doesn't suit your application then you can
81       override the build_bin_name subroutine to explicitly set the executable
82       name
83
84           sub build_bin_name { 'scanner.exe' }
85           # /path/to/scanner.exe
86
87       Or you could explicitly set the path with
88
89           sub build_bin_name { '/only/use/this/path/scanner.exe' }
90           # /only/use/this/path/scanner.exe
91
92   How attributes are mapped to parameters
93       The attributes of the consuming package map directly to the parameters
94       passed to the executable. There are a few things to note about the
95       default behaviour governing the way these attributes are mapped.
96
97           Attribute           Default Behaviour (@ARGV)
98           ---------           -------------------------
99           single char         prefix attr name with '-'
100           multiple char       prefix attr name with '--'
101           boolean             treat attr as flag (no value)
102           non-boolean         treat attr as parameter (with value)
103           value=undef         ignore attr
104           name=_name          ignore attr
105
106       These points are illustrated in the following example:
107
108           package MyApp::Commands::Scanner;
109           use Moose;
110           with 'MooseX::Role::Cmd';
111
112           has 'i'       => ( is => 'rw', isa => 'Str',  default => 'input.txt' );
113           has 'out'     => ( is => 'rw', isa => 'Str' );
114           has 'verbose' => ( is => 'rw', isa => 'Bool', default => 1 );
115           has 'level'   => ( is => 'rw', isa => 'Int' );
116           has 'option'  => ( is => 'rw', isa => 'Str' );
117
118           has '_internal' => ( is => 'ro', isa => Str, reader => internal, default => 'foo' );
119           # attribute names starting with '_' are not included
120
121           $scanner = MyApp::Commands::Scanner->new( output => '/tmp/scanner.log', level => 5 );
122
123           $scanner->run;
124           # /path/to/scanner -i input.txt --out /tmp/scanner.log --verbose --level 5
125
126   Changing names of parameters
127       It's possible that the parameters your system command expects do not
128       adhere to this naming scheme. In this case you can use the 'CmdOpt'
129       trait which allows you to specify exactly how you want the parameter to
130       appear on the command line.
131
132           has 'option' => ( isa           => 'Bool' );
133           # --option
134
135       cmdopt_prefix
136
137       This lets you override the prefix used for the option (for example to
138       use the short form of multi-character options).
139
140           has 'option' => ( traits        => [ 'CmdOpt' ],
141                             isa           => 'Bool',
142                             cmdopt_prefix => '-'
143                           );
144           # -option
145
146       cmdopt_name
147
148       This lets you completely override the option name with whatever string
149       you want
150
151           has 'option' => ( traits        => [ 'CmdOpt' ],
152                             isa           => 'Bool',
153                             cmdopt_name   => '+foo'
154                           );
155           # +foo
156
157       cmdopt_env
158
159       This will set an environment variable with the attribute name/value
160       rather than pass it along as a command line param
161
162           has 'home_dir' => ( traits      => [ 'CmdOpt' ],
163                               isa         => 'Str',
164                               cmdopt_env  => 'APP_HOME'
165                               default     => '/my/app/home'
166                           );
167
168           # ENV{APP_HOME} = /my/app/home
169
170       See MooseX::Role::Cmd::Meta::Attribute::Trait
171

PRIVATE METHODS

173   _attr_to_cmd_options
174       Returns an array (or array reference) of command options that
175       correspond to the given attribute name.
176

AUTHOR

178       Eden Cardim <edencardim@gmail.com>
179

LICENSE

181       This library is free software, you can redistribute it and/or modify it
182       under the same terms as Perl itself.
183
184
185
186perl v5.30.1                      2020-01-30              MooseX::Role::Cmd(3)
Impressum