[Moose-commits] r7945 - MooseX-Role-Cmd/lib/MooseX/Role
isillitoe at code2.0beta.co.uk
isillitoe at code2.0beta.co.uk
Tue Jun 2 13:24:59 GMT 2009
Author: isillitoe
Date: 2009-06-02 06:24:59 -0700 (Tue, 02 Jun 2009)
New Revision: 7945
Modified:
MooseX-Role-Cmd/lib/MooseX/Role/Cmd.pm
Log:
Improved readability of the documentation
Modified: MooseX-Role-Cmd/lib/MooseX/Role/Cmd.pm
===================================================================
--- MooseX-Role-Cmd/lib/MooseX/Role/Cmd.pm 2009-05-29 02:51:37 UTC (rev 7944)
+++ MooseX-Role-Cmd/lib/MooseX/Role/Cmd.pm 2009-06-02 13:24:59 UTC (rev 7945)
@@ -46,111 +46,6 @@
command-line wrapper modules. It automatically maps L<Moose> objects into
command strings which are passed to L<IPC::Cmd>.
-=head2 Setting the executable
-
-By default the name of the binary executable is taken from the last part of the class name
-(in lower case). The path is set during the L<run> method by scanning through your current
-PATH for the given executable (see also the 'can_run' function from L<IPC::Cmd>)
-
- package MyApp::Commands::Scanner;
- use Moose;
- with 'MooseX::Role::Cmd';
-
- $cmd = MyApp::Commands::Scanner->new();
- $cmd->bin_name
- # /path/to/scanner
-
-If this default behaviour doesn't suit your application then you can override the L<build_bin_name>
-subroutine to explicitly set the executable name
-
- sub build_bin_name { 'scanner.exe' }
- # /path/to/scanner.exe
-
-Or you could explicitly set the path with
-
- sub build_bin_name { '/only/use/this/path/scanner.exe' }
- # /only/use/this/path/scanner.exe
-
-=head2 How attributes are mapped to parameters
-
-The attributes of the module consuming this role map directly to the parameters passed
-to the executable. There are a couple of things to note about the default behaviour
-governing the way these attributes are mapped.
-
-=over 8
-
-=item Single character attributes are prefixed with '-'
-
-=item Multiple character attributes are prefixed with '--'
-
-=item Boolean attributes are treated as flags (no values)
-
-=item Non-boolean attributes are treated as parameters (with values)
-
-=item Attributes with undefined values will be ignored
-
-=back
-
-These points are illustrated by the following attributes (in the same order as list above)
-
- package MyApp::Commands::Scanner;
- use Moose;
- with 'MooseX::Role::Cmd';
-
- has 'i' => ( is => 'rw', isa => 'Str', default => 'input.txt' );
- has 'out' => ( is => 'rw', isa => 'Str', default => 'output.txt' );
- has 'verbose' => ( is => 'rw', isa => 'Bool', default => 1 );
- has 'level' => ( is => 'rw', isa => 'Int', default => 5 );
- has 'option' => ( is => 'rw', isa => 'Str' );
-
- # results in:
- # /path/to/scanner -i input.txt --out output.txt --verbose --level 5
-
-=head2 Changing names of parameters
-
-It's possible that the parameters your system command expects do not adhere to this
-naming scheme. In this case you can use the 'CmdOpt' trait which allows you to
-specify exactly how you want the parameter to appear on the command line.
-
- has 'option' => ( isa => 'Bool' );
- # --option
-
-=head3 cmdopt_prefix
-
-This lets you override the prefix used for the option (for example to use the short
-form of multi-character options).
-
- has 'option' => ( traits => [ 'CmdOpt' ],
- isa => 'Bool',
- cmdopt_prefix => '-'
- );
- # -option
-
-=head3 cmdopt_name
-
-This lets you completely override the option name with whatever string you want
-
- has 'option' => ( traits => [ 'CmdOpt' ],
- isa => 'Bool',
- cmdopt_name => '+foo'
- );
- # +foo
-
-=head3 cmdopt_env
-
-This will set an environment variable with the attribute name/value rather than pass
-it along as a command line param
-
- has 'home_dir' => ( traits => [ 'CmdOpt' ],
- isa => 'Str',
- cmdopt_env => 'APP_HOME'
- default => '/my/app/home'
- );
-
- # ENV{APP_HOME} = /my/app/home
-
-See L<MooseX::Role::Cmd::Meta::Attribute::Trait>
-
=head1 ATTRIBUTES
=head2 $cmd->bin_name
@@ -183,7 +78,6 @@
has 'stderr' => ( isa => 'ArrayRef', is => 'rw' );
-
no Moose;
=head1 METHODS
@@ -265,51 +159,116 @@
return wantarray ? @args : \@args;
}
+=head1 ADDITIONAL INFORMATION
-=head1 PRIVATE METHODS
+=head2 Setting the Executable
-=head2 _attr_to_cmd_options
+By default the name of the binary executable is taken from the last part of the class name
+(in lower case). The path is set during the L<run> method by scanning through your current
+PATH for the given executable (see also the 'can_run' function from L<IPC::Cmd>)
-Returns an array (or array reference) of command options that correspond
-to the given attribute name. This essentially provides the following
-functionality:
+ package MyApp::Commands::Scanner;
+ use Moose;
+ with 'MooseX::Role::Cmd';
+
+ $cmd = MyApp::Commands::Scanner->new();
+ $cmd->bin_name
+ # /path/to/scanner
-Bool as flags, everything else as key => value params
+If this default behaviour doesn't suit your application then you can override the L<build_bin_name>
+subroutine to explicitly set the executable name
- has 'v' => ( isa => 'Bool' ); # -v
- has 'i' => ( isa => 'Str' ); # -i input.data
+ sub build_bin_name { 'scanner.exe' }
+ # /path/to/scanner.exe
-Use Getopt::Long conventions with hyphenations:
+Or you could explicitly set the path with
- has 'v' => ( isa => 'Bool' ); # -v
- has 'verbose' => ( isa => 'Bool' ); # --verbose
+ sub build_bin_name { '/only/use/this/path/scanner.exe' }
+ # /only/use/this/path/scanner.exe
-Use optional info from CmdOpt trait:
+=head2 How attributes are mapped to parameters
- has 'v' => ( isa => 'Bool' ); # -v
+The attributes of the consuming package map directly to the parameters passed
+to the executable. There are a few things to note about the default behaviour
+governing the way these attributes are mapped.
+
+ Attribute Default Behaviour (@ARGV)
+ --------- -------------------------
+ single char prefix attr name with '-'
+ multiple char prefix attr name with '--'
+ boolean treat attr as flag (no value)
+ non-boolean treat attr as parameter (with value)
+ value=undef ignore attr
+
+These points are illustrated in the following example:
+
+ package MyApp::Commands::Scanner;
+ use Moose;
+ with 'MooseX::Role::Cmd';
- has 'short' => ( traits => [ 'CmdOpt' ],
- isa => 'Bool',
- cmdopt_prefix => '-'
- ); # -short
+ has 'i' => ( is => 'rw', isa => 'Str', default => 'input.txt' );
+ has 'out' => ( is => 'rw', isa => 'Str' );
+ has 'verbose' => ( is => 'rw', isa => 'Bool', default => 1 );
+ has 'level' => ( is => 'rw', isa => 'Int' );
+ has 'option' => ( is => 'rw', isa => 'Str' );
- has 'rename' => ( traits => [ 'CmdOpt' ],
- isa => 'Bool',
- cmdopt_name => '+foo'
- ); # +foo
+ $scanner = MyApp::Commands::Scanner->new( output => '/tmp/scanner.log', level => 5 );
+
+ $scanner->run;
+ # /path/to/scanner -i input.txt --out /tmp/scanner.log --verbose --level 5
-Use attribute to set an environment variable rather than command line param
+=head2 Changing names of parameters
+It's possible that the parameters your system command expects do not adhere to this
+naming scheme. In this case you can use the 'CmdOpt' trait which allows you to
+specify exactly how you want the parameter to appear on the command line.
+
+ has 'option' => ( isa => 'Bool' );
+ # --option
+
+=head3 cmdopt_prefix
+
+This lets you override the prefix used for the option (for example to use the short
+form of multi-character options).
+
+ has 'option' => ( traits => [ 'CmdOpt' ],
+ isa => 'Bool',
+ cmdopt_prefix => '-'
+ );
+ # -option
+
+=head3 cmdopt_name
+
+This lets you completely override the option name with whatever string you want
+
+ has 'option' => ( traits => [ 'CmdOpt' ],
+ isa => 'Bool',
+ cmdopt_name => '+foo'
+ );
+ # +foo
+
+=head3 cmdopt_env
+
+This will set an environment variable with the attribute name/value rather than pass
+it along as a command line param
+
has 'home_dir' => ( traits => [ 'CmdOpt' ],
- isa => 'Str',
- cmdopt_env => 'APP_HOME'
- default => '/my/app/home'
- );
+ isa => 'Str',
+ cmdopt_env => 'APP_HOME'
+ default => '/my/app/home'
+ );
+
+ # ENV{APP_HOME} = /my/app/home
- # $ENV{APP_HOME} = /my/app/home
+See L<MooseX::Role::Cmd::Meta::Attribute::Trait>
-Don't consider attributes with undef values
+=head1 PRIVATE METHODS
+=head2 _attr_to_cmd_options
+
+Returns an array (or array reference) of command options that correspond
+to the given attribute name.
+
=cut
sub _attr_to_cmd_options {
More information about the Moose-commits
mailing list