Supported Type Constraints

Bool

A Bool type constraint is set up as a boolean option with Getopt::Long. So that this attribute description:

  has 'verbose' => (is => 'rw', isa => 'Bool');
    

would translate into "verbose!" as a Getopt::Long option descriptor, which would enable the following command line options:

  % my_script.pl --verbose
  % my_script.pl --noverbose
    

Int, Float, Str

These type constraints are set up as properly typed options with Getopt::Long, using the "=i", "=f" and "=s" modifiers as appropriate.

ArrayRef

An ArrayRef type constraint is set up as a multiple value option in Getopt::Long. So that this attribute description:

  has 'include' => (
      is      => 'rw',
      isa     => 'ArrayRef',
      default => sub { [] }
  );
    

would translate into "includes=s@" as a Getopt::Long option descriptor, which would enable the following command line options:

  % my_script.pl --include /usr/lib --include /usr/local/lib
    

HashRef

A HashRef type constraint is set up as a hash value option in Getopt::Long. So that this attribute description:

  has 'define' => (
      is      => 'rw',
      isa     => 'HashRef',
      default => sub { {} }
  );
    

would translate into "define=s%" as a Getopt::Long option descriptor, which would enable the following command line options:

  % my_script.pl --define os=linux --define vendor=debian
    

Custom Type Constraints

  subtype 'ArrayOfInts'
      => as 'ArrayRef'
      => where { scalar (grep { looks_like_number($_) } @$_)  };

Then you register the mapping, like so:

  MouseX::Getopt::OptionTypeMap->add_option_type_to_map(
      'ArrayOfInts' => '=i@'
  );

Now any attribute declarations using this type constraint will get the custom option spec. So that, this:

  has 'nums' => (
      is      => 'ro',
      isa     => 'ArrayOfInts',
      default => sub { [0] }
  );

Will translate to the following on the command line:

  % my_script.pl --nums 5 --nums 88 --nums 199

This example is fairly trivial, but more complex validations are easily possible with a little creativity. The trick is balancing the type constraint validations with the Getopt::Long validations.

Better examples are certainly welcome :)

Inferred Type Constraints

For example, if you had the same custom "ArrayOfInts" subtype from the examples above, but did not add a new custom option type for it to the "OptionTypeMap", it would be treated just like a normal "ArrayRef" type for Getopt purposes (that is, "=s@").

new_with_options (%params)

This method will take a set of default %params and then collect params from the command line (possibly overriding those in %params) and then return a newly constructed object.

The special parameter "argv", if specified should point to an array reference with an array to use instead of @ARGV.

If "GetOptions" in Getopt::Long fails (due to invalid arguments), "new_with_options" will throw an exception.

If Getopt::Long::Descriptive is installed and any of the following command line params are passed, the program will exit with usage information (and the option's state will be stored in the help_flag attribute). You can add descriptions for each option by including a documentation option for each attribute to document.

  --?
  --help
  --usage
    

If you have Getopt::Long::Descriptive the "usage" param is also passed to "new" as the usage option.

ARGV

This accessor contains a reference to a copy of the @ARGV array as it originally existed at the time of "new_with_options".

extra_argv

This accessor contains an arrayref of leftover @ARGV elements that Getopt::Long did not parse. Note that the real @ARGV is left un-mangled.

usage

This accessor contains the Getopt::Long::Descriptive::Usage object (if Getopt::Long::Descriptive is used).

help_flag

This accessor contains the boolean state of the --help, --usage and --? options (true if any of these options were passed on the command line).

meta

This returns the role meta object.