NAME

MouseX::Getopt - A Mouse role for processing command line options

SYNOPSIS

  # In your class
  package MyApp;
  use Mouse;

  with 'MouseX::Getopt';

  has 'out' => (is => 'rw', isa => 'Str', required => 1);
  has 'in'  => (is => 'rw', isa => 'Str', required => 1);

  # In your script
  #!/usr/bin/perl

  use MyApp;

  my $app = MyApp->new_with_options;

  # On the command line
  % perl myapp_script.pl -in file.input -out file.dump

DESCRIPTION

This is a role which provides an alternate constructor for creating objects using parameters passed in from the command line.

This module attempts to DWIM as much as possible with the command line params by introspecting your class's attributes. It will use the name of your attribute as the command line option, and if there is a type constraint defined, it will configure Getopt::Long to handle the option accordingly.

If your class also uses MouseX::ConfigFromFile, this role's new_with_options will load the configfile specified by the --configfile option or the default you've given for the configfile attribute.

Example:

  package MyApp;
  use Mouse;
  with 'MouseX::Getopt';
  with 'MouseX::ConfigFromFile';

  has '+configfile' => ( default => '/path/to/file' );

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:

  % perl myapp_script.pl --verbose
  % perl myapp_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 include=s@ as a Getopt::Long option descriptor, which would enable the following command line options:

  % perl myapp_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:

  % perl myapp_script.pl --define os=linux --define vendor=debian

Custom Type Constraints

It is possible to create custom type constraint to option spec mappings if you need them. The process is fairly simple (but a little verbose maybe). First you create a custom subtype, like so:

  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:

  % perl myapp_script.pl --nums 5 --nums 88 --nums 199

METHODS

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.

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

PROPERTIES

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

CAVEATS

traits and metaclass (Getopt, NoGetopt) are not supported.

Getopt::Long::Descriptive is not supported.

AUTHOR

NAKAGAWA Masaki <masaki@cpan.org>

LICENSE

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

SEE ALSO

Mouse, Getopt::Long, MooseX::Getopt

cpanm MouseX::Getopt

perl -MCPAN -e shell
install MouseX::Getopt