lib/MooseX/Getopt.pm

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