$cmd->bin_name¶

Sets the binary executable name for the command you want to run. Defaults the to last part of the class name.

$cmd->stdout¶

Returns the STDOUT buffer captured after running the command.

$cmd->stderr¶

Returns the STDERR buffer captured after running the command.

$bin_name = $cmd->build_bin_name¶

Builds the default string for the command name based on the class name.

@stdout = $cmd->run(@args);¶

Builds the command string and runs it based on the objects current attribute settings. This will treat all the attributes defined in your class as flags to be passed to the command.

NOTE: All quoting issues are left to be solved by the user.

cmd_args¶

Returns a list of the computed arguments that will be added to the command

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 run method by scanning through your current PATH for the given executable (see also the 'can_run' function from 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 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

How attributes are mapped to parameters¶

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
    name=_name          ignore attr

These points are illustrated in the following example:

    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' );
    has 'verbose' => ( is => 'rw', isa => 'Bool', default => 1 );
    has 'level'   => ( is => 'rw', isa => 'Int' );
    has 'option'  => ( is => 'rw', isa => 'Str' );
    has '_internal' => ( is => 'ro', isa => Str, reader => internal, default => 'foo' );
    # attribute names starting with '_' are not included
    $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

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

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

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

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 MooseX::Role::Cmd::Meta::Attribute::Trait

_attr_to_cmd_options¶

Returns an array (or array reference) of command options that correspond to the given attribute name.