MooseX::Role::Cmd(3)

💖 MooseX::Role::Cmd 💖

okay bestie, so this is MooseX::Role::Cmd — a page from the User Contributed Perl Documentation collection. And literally what it does is wrap system command binaries the Moose way. no cap. let's get into it 🦋

---

✨ NAME ✨

MooseX::Role::Cmd — Wrap system command binaries the Moose way 👑

---

🌸 SYNOPSIS 🌸

First you gotta create your command wrapper, periodt:

package Cmd::Perl;

use Moose;

with 'MooseX::Role::Cmd';

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

# other perl switches here...

1;

Then use it somewhere else, slay:

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, and its whole vibe is making it easier to build command-line wrapper modules. The way it works is it automatically maps your Moose objects into command strings, and then those strings get passed to IPC::Cmd. iconic behaviour fr fr ✨

---

🎀 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. (yes, that "the to" is in the original, we keep it 💀)

$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. that's on you bestie 😭

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.

---

and that's the whole page bestie!! 🎀 this one shipped as perl v5.42.0 and got dated 2025-07-25, so if you're citing it, that's the version + date to remember. mwah 💋✨