The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

MooseX::Getopt - A Moose role for processing command line options

SYNOPSIS

  ## In your class 
  package My::App;
  use Moose;
  
  with 'MooseX::Getopt';
  
  has 'out' => (is => 'rw', isa => 'Str', required => 1);
  has 'in'  => (is => 'rw', isa => 'Str', required => 1);
  
  # ... rest of the class here
  
  ## in your script
  #!/usr/bin/perl
  
  use My::App;
  
  my $app = My::App->new_with_options();
  # ... rest of the script here
  
  ## on the command line
  % perl my_app_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.

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

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:

  MooseX::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 :)

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.

meta

This returns the role meta object.

BUGS

All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.

AUTHOR

Stevan Little <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright 2007 by Infinity Interactive, Inc.

http://www.iinteractive.com

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