NAME

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

SYNOPSIS

Create your command wrapper:

    package Cmd::Perl;

    use Moose;

    with 'MooseX::Role::Cmd';

    has 'e' => (isa => 'Str', is => 'rw');

    # other perl switches here...

    1;

Use it somewhere else:

    use Cmd::Perl;

    my $perl = Cmd::Perl->new(e => q{'print join ", ", @ARGV'});

    print $perl->run(qw/foo bar baz/);

    # prints the STDOUT captured from running:
    # perl -e 'print join ", ", @ARGV' foo bar baz

DESCRIPTION

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

ATTRIBUTES

$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.

METHODS

$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

ADDITIONAL INFORMATION

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

PRIVATE METHODS

_attr_to_cmd_options

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

AUTHOR

Eden Cardim <edencardim@gmail.com>

LICENSE

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm MooseX::Role::Cmd

perl -MCPAN -e shell
install MooseX::Role::Cmd