lib/MooseX/Getopt.pm

   1 package MooseX::Getopt;
   2 # ABSTRACT: A Moose role for processing command line options
   3
   4 use Moose::Role 0.56;
   5
   6 use constant _HAVE_GLD => not not eval { require Getopt::Long::Descriptive };
   7
   8 with _HAVE_GLD ? 'MooseX::Getopt::GLD' : 'MooseX::Getopt::Basic';
   9
  10 no Moose::Role;
  11
  12 1;
  13
  14 =head1 SYNOPSIS
  15
  16   ## In your class
  17   package My::App;
  18   use Moose;
  19
  20   with 'MooseX::Getopt';
  21
  22   has 'out' => (is => 'rw', isa => 'Str', required => 1);
  23   has 'in'  => (is => 'rw', isa => 'Str', required => 1);
  24
  25   # ... rest of the class here
  26
  27   ## in your script
  28   #!/usr/bin/perl
  29
  30   use My::App;
  31
  32   my $app = My::App->new_with_options();
  33   # ... rest of the script here
  34
  35   ## on the command line
  36   % perl my_app_script.pl -in file.input -out file.dump
  37
  38 =head1 DESCRIPTION
  39
  40 This is a role which provides an alternate constructor for creating
  41 objects using parameters passed in from the command line.
  42
  43 This module attempts to DWIM as much as possible with the command line
  44 params by introspecting your class's attributes. It will use the name
  45 of your attribute as the command line option, and if there is a type
  46 constraint defined, it will configure Getopt::Long to handle the option
  47 accordingly.
  48
  49 You can use the trait L<MooseX::Getopt::Meta::Attribute::Trait> or the
  50 attribute metaclass L<MooseX::Getopt::Meta::Attribute> to get non-default
  51 commandline option names and aliases.
  52
  53 You can use the trait L<MooseX::Getopt::Meta::Attribute::Trait::NoGetopt>
  54 or the attribute metaclass L<MooseX::Getopt::Meta::Attribute::NoGetopt>
  55 to have C<MooseX::Getopt> ignore your attribute in the commandline options.
  56
  57 By default, attributes which start with an underscore are not given
  58 commandline argument support, unless the attribute's metaclass is set
  59 to L<MooseX::Getopt::Meta::Attribute>. If you don't want your accessors
  60 to have the leading underscore in their name, you can do this:
  61
  62   # for read/write attributes
  63   has '_foo' => (accessor => 'foo', ...);
  64
  65   # or for read-only attributes
  66   has '_bar' => (reader => 'bar', ...);
  67
  68 This will mean that Getopt will not handle a --foo param, but your
  69 code can still call the C<foo> method.
  70
  71 If your class also uses a configfile-loading role based on
  72 L<MooseX::ConfigFromFile>, such as L<MooseX::SimpleConfig>,
  73 L<MooseX::Getopt>'s C<new_with_options> will load the configfile
  74 specified by the C<--configfile> option (or the default you've
  75 given for the configfile attribute) for you.
  76
  77 Options specified in multiple places follow the following
  78 precendence order: commandline overrides configfile, which
  79 overrides explicit new_with_options parameters.
  80
  81 =head2 Supported Type Constraints
  82
  83 =over 4
  84
  85 =item I<Bool>
  86
  87 A I<Bool> type constraint is set up as a boolean option with
  88 Getopt::Long. So that this attribute description:
  89
  90   has 'verbose' => (is => 'rw', isa => 'Bool');
  91
  92 would translate into C<verbose!> as a Getopt::Long option descriptor,
  93 which would enable the following command line options:
  94
  95   % my_script.pl --verbose
  96   % my_script.pl --noverbose
  97
  98 =item I<Int>, I<Float>, I<Str>
  99
 100 These type constraints are set up as properly typed options with
 101 Getopt::Long, using the C<=i>, C<=f> and C<=s> modifiers as appropriate.
 102
 103 =item I<ArrayRef>
 104
 105 An I<ArrayRef> type constraint is set up as a multiple value option
 106 in Getopt::Long. So that this attribute description:
 107
 108   has 'include' => (
 109       is      => 'rw',
 110       isa     => 'ArrayRef',
 111       default => sub { [] }
 112   );
 113
 114 would translate into C<includes=s@> as a Getopt::Long option descriptor,
 115 which would enable the following command line options:
 116
 117   % my_script.pl --include /usr/lib --include /usr/local/lib
 118
 119 =item I<HashRef>
 120
 121 A I<HashRef> type constraint is set up as a hash value option
 122 in Getopt::Long. So that this attribute description:
 123
 124   has 'define' => (
 125       is      => 'rw',
 126       isa     => 'HashRef',
 127       default => sub { {} }
 128   );
 129
 130 would translate into C<define=s%> as a Getopt::Long option descriptor,
 131 which would enable the following command line options:
 132
 133   % my_script.pl --define os=linux --define vendor=debian
 134
 135 =back
 136
 137 =head2 Custom Type Constraints
 138
 139 It is possible to create custom type constraint to option spec
 140 mappings if you need them. The process is fairly simple (but a
 141 little verbose maybe). First you create a custom subtype, like
 142 so:
 143
 144   subtype 'ArrayOfInts'
 145       => as 'ArrayRef'
 146       => where { scalar (grep { looks_like_number($_) } @$_)  };
 147
 148 Then you register the mapping, like so:
 149
 150   MooseX::Getopt::OptionTypeMap->add_option_type_to_map(
 151       'ArrayOfInts' => '=i@'
 152   );
 153
 154 Now any attribute declarations using this type constraint will
 155 get the custom option spec. So that, this:
 156
 157   has 'nums' => (
 158       is      => 'ro',
 159       isa     => 'ArrayOfInts',
 160       default => sub { [0] }
 161   );
 162
 163 Will translate to the following on the command line:
 164
 165   % my_script.pl --nums 5 --nums 88 --nums 199
 166
 167 This example is fairly trivial, but more complex validations are
 168 easily possible with a little creativity. The trick is balancing
 169 the type constraint validations with the Getopt::Long validations.
 170
 171 Better examples are certainly welcome :)
 172
 173 =head2 Inferred Type Constraints
 174
 175 If you define a custom subtype which is a subtype of one of the
 176 standard L</Supported Type Constraints> above, and do not explicitly
 177 provide custom support as in L</Custom Type Constraints> above,
 178 MooseX::Getopt will treat it like the parent type for Getopt
 179 purposes.
 180
 181 For example, if you had the same custom C<ArrayOfInts> subtype
 182 from the examples above, but did not add a new custom option
 183 type for it to the C<OptionTypeMap>, it would be treated just
 184 like a normal C<ArrayRef> type for Getopt purposes (that is,
 185 C<=s@>).
 186
 187 =method B<new_with_options (%params)>
 188
 189 This method will take a set of default C<%params> and then collect
 190 params from the command line (possibly overriding those in C<%params>)
 191 and then return a newly constructed object.
 192
 193 The special parameter C<argv>, if specified should point to an array
 194 reference with an array to use instead of C<@ARGV>.
 195
 196 If L<Getopt::Long/GetOptions> fails (due to invalid arguments),
 197 C<new_with_options> will throw an exception.
 198
 199 If L<Getopt::Long::Descriptive> is installed and any of the following
 200 command line params are passed, the program will exit with usage
 201 information. You can add descriptions for each option by including a
 202 B<documentation> option for each attribute to document.
 203
 204   --?
 205   --help
 206   --usage
 207
 208 If you have L<Getopt::Long::Descriptive> the C<usage> param is also passed to
 209 C<new>.
 210
 211 =method B<ARGV>
 212
 213 This accessor contains a reference to a copy of the C<@ARGV> array
 214 as it originally existed at the time of C<new_with_options>.
 215
 216 =method B<extra_argv>
 217
 218 This accessor contains an arrayref of leftover C<@ARGV> elements that
 219 L<Getopt::Long> did not parse.  Note that the real C<@ARGV> is left
 220 un-mangled.
 221
 222 =method B<meta>
 223
 224 This returns the role meta object.
 225
 226 =cut