local-lib5/man/man3/MooseX::Getopt.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "MooseX::Getopt 3"
 132 .TH MooseX::Getopt 3 "2009-11-26" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 MooseX::Getopt \- A Moose role for processing command line options
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 3
 138 \&  ## In your class
 139 \&  package My::App;
 140 \&  use Moose;
 141 .Ve
 142 .PP
 143 .Vb 1
 144 \&  with 'MooseX::Getopt';
 145 .Ve
 146 .PP
 147 .Vb 2
 148 \&  has 'out' => (is => 'rw', isa => 'Str', required => 1);
 149 \&  has 'in'  => (is => 'rw', isa => 'Str', required => 1);
 150 .Ve
 151 .PP
 152 .Vb 1
 153 \&  # ... rest of the class here
 154 .Ve
 155 .PP
 156 .Vb 2
 157 \&  ## in your script
 158 \&  #!/usr/bin/perl
 159 .Ve
 160 .PP
 161 .Vb 1
 162 \&  use My::App;
 163 .Ve
 164 .PP
 165 .Vb 2
 166 \&  my $app = My::App\->new_with_options();
 167 \&  # ... rest of the script here
 168 .Ve
 169 .PP
 170 .Vb 2
 171 \&  ## on the command line
 172 \&  % perl my_app_script.pl \-in file.input \-out file.dump
 173 .Ve
 174 .SH "DESCRIPTION"
 175 .IX Header "DESCRIPTION"
 176 This is a role which provides an alternate constructor for creating
 177 objects using parameters passed in from the command line.
 178 .PP
 179 This module attempts to \s-1DWIM\s0 as much as possible with the command line
 180 params by introspecting your class's attributes. It will use the name
 181 of your attribute as the command line option, and if there is a type
 182 constraint defined, it will configure Getopt::Long to handle the option
 183 accordingly.
 184 .PP
 185 You can use the trait MooseX::Getopt::Meta::Attribute::Trait or the
 186 attribute metaclass MooseX::Getopt::Meta::Attribute to get non-default
 187 commandline option names and aliases.
 188 .PP
 189 You can use the trait MooseX::Getopt::Meta::Attribute::Trait::NoGetopt
 190 or the attribute metaclass MooseX::Getopt::Meta::Attribute::NoGetopt
 191 to have \f(CW\*(C`MooseX::Getopt\*(C'\fR ignore your attribute in the commandline options.
 192 .PP
 193 By default, attributes which start with an underscore are not given
 194 commandline argument support, unless the attribute's metaclass is set
 195 to MooseX::Getopt::Meta::Attribute. If you don't want your accessors
 196 to have the leading underscore in their name, you can do this:
 197 .PP
 198 .Vb 2
 199 \&  # for read/write attributes
 200 \&  has '_foo' => (accessor => 'foo', ...);
 201 .Ve
 202 .PP
 203 .Vb 2
 204 \&  # or for read\-only attributes
 205 \&  has '_bar' => (reader => 'bar', ...);
 206 .Ve
 207 .PP
 208 This will mean that Getopt will not handle a \-\-foo param, but your
 209 code can still call the \f(CW\*(C`foo\*(C'\fR method.
 210 .PP
 211 If your class also uses a configfile-loading role based on
 212 MooseX::ConfigFromFile, such as MooseX::SimpleConfig,
 213 MooseX::Getopt's \f(CW\*(C`new_with_options\*(C'\fR will load the configfile
 214 specified by the \f(CW\*(C`\-\-configfile\*(C'\fR option (or the default you've
 215 given for the configfile attribute) for you.
 216 .PP
 217 Options specified in multiple places follow the following
 218 precendence order: commandline overrides configfile, which
 219 overrides explicit new_with_options parameters.
 220 .Sh "Supported Type Constraints"
 221 .IX Subsection "Supported Type Constraints"
 222 .IP "\fIBool\fR" 4
 223 .IX Item "Bool"
 224 A \fIBool\fR type constraint is set up as a boolean option with
 225 Getopt::Long. So that this attribute description:
 226 .Sp
 227 .Vb 1
 228 \&  has 'verbose' => (is => 'rw', isa => 'Bool');
 229 .Ve
 230 .Sp
 231 would translate into \f(CW\*(C`verbose!\*(C'\fR as a Getopt::Long option descriptor,
 232 which would enable the following command line options:
 233 .Sp
 234 .Vb 2
 235 \&  % my_script.pl \-\-verbose
 236 \&  % my_script.pl \-\-noverbose
 237 .Ve
 238 .IP "\fIInt\fR, \fIFloat\fR, \fIStr\fR" 4
 239 .IX Item "Int, Float, Str"
 240 These type constraints are set up as properly typed options with
 241 Getopt::Long, using the \f(CW\*(C`=i\*(C'\fR, \f(CW\*(C`=f\*(C'\fR and \f(CW\*(C`=s\*(C'\fR modifiers as appropriate.
 242 .IP "\fIArrayRef\fR" 4
 243 .IX Item "ArrayRef"
 244 An \fIArrayRef\fR type constraint is set up as a multiple value option
 245 in Getopt::Long. So that this attribute description:
 246 .Sp
 247 .Vb 5
 248 \&  has 'include' => (
 249 \&      is      => 'rw',
 250 \&      isa     => 'ArrayRef',
 251 \&      default => sub { [] }
 252 \&  );
 253 .Ve
 254 .Sp
 255 would translate into \f(CW\*(C`includes=s@\*(C'\fR as a Getopt::Long option descriptor,
 256 which would enable the following command line options:
 257 .Sp
 258 .Vb 1
 259 \&  % my_script.pl \-\-include /usr/lib \-\-include /usr/local/lib
 260 .Ve
 261 .IP "\fIHashRef\fR" 4
 262 .IX Item "HashRef"
 263 A \fIHashRef\fR type constraint is set up as a hash value option
 264 in Getopt::Long. So that this attribute description:
 265 .Sp
 266 .Vb 5
 267 \&  has 'define' => (
 268 \&      is      => 'rw',
 269 \&      isa     => 'HashRef',
 270 \&      default => sub { {} }
 271 \&  );
 272 .Ve
 273 .Sp
 274 would translate into \f(CW\*(C`define=s%\*(C'\fR as a Getopt::Long option descriptor,
 275 which would enable the following command line options:
 276 .Sp
 277 .Vb 1
 278 \&  % my_script.pl \-\-define os=linux \-\-define vendor=debian
 279 .Ve
 280 .Sh "Custom Type Constraints"
 281 .IX Subsection "Custom Type Constraints"
 282 It is possible to create custom type constraint to option spec
 283 mappings if you need them. The process is fairly simple (but a
 284 little verbose maybe). First you create a custom subtype, like
 285 so:
 286 .PP
 287 .Vb 3
 288 \&  subtype 'ArrayOfInts'
 289 \&      => as 'ArrayRef'
 290 \&      => where { scalar (grep { looks_like_number($_) } @$_)  };
 291 .Ve
 292 .PP
 293 Then you register the mapping, like so:
 294 .PP
 295 .Vb 3
 296 \&  MooseX::Getopt::OptionTypeMap\->add_option_type_to_map(
 297 \&      'ArrayOfInts' => '=i@'
 298 \&  );
 299 .Ve
 300 .PP
 301 Now any attribute declarations using this type constraint will
 302 get the custom option spec. So that, this:
 303 .PP
 304 .Vb 5
 305 \&  has 'nums' => (
 306 \&      is      => 'ro',
 307 \&      isa     => 'ArrayOfInts',
 308 \&      default => sub { [0] }
 309 \&  );
 310 .Ve
 311 .PP
 312 Will translate to the following on the command line:
 313 .PP
 314 .Vb 1
 315 \&  % my_script.pl \-\-nums 5 \-\-nums 88 \-\-nums 199
 316 .Ve
 317 .PP
 318 This example is fairly trivial, but more complex validations are
 319 easily possible with a little creativity. The trick is balancing
 320 the type constraint validations with the Getopt::Long validations.
 321 .PP
 322 Better examples are certainly welcome :)
 323 .Sh "Inferred Type Constraints"
 324 .IX Subsection "Inferred Type Constraints"
 325 If you define a custom subtype which is a subtype of one of the
 326 standard \*(L"Supported Type Constraints\*(R" above, and do not explicitly
 327 provide custom support as in \*(L"Custom Type Constraints\*(R" above,
 328 MooseX::Getopt will treat it like the parent type for Getopt
 329 purposes.
 330 .PP
 331 For example, if you had the same custom \f(CW\*(C`ArrayOfInts\*(C'\fR subtype
 332 from the examples above, but did not add a new custom option
 333 type for it to the \f(CW\*(C`OptionTypeMap\*(C'\fR, it would be treated just
 334 like a normal \f(CW\*(C`ArrayRef\*(C'\fR type for Getopt purposes (that is,
 335 \&\f(CW\*(C`=s@\*(C'\fR).
 336 .SH "METHODS"
 337 .IX Header "METHODS"
 338 .IP "\fBnew_with_options (%params)\fR" 4
 339 .IX Item "new_with_options (%params)"
 340 This method will take a set of default \f(CW%params\fR and then collect
 341 params from the command line (possibly overriding those in \f(CW%params\fR)
 342 and then return a newly constructed object.
 343 .Sp
 344 The special parameter \f(CW\*(C`argv\*(C'\fR, if specified should point to an array
 345 reference with an array to use instead of \f(CW@ARGV\fR.
 346 .Sp
 347 If \*(L"GetOptions\*(R" in Getopt::Long fails (due to invalid arguments),
 348 \&\f(CW\*(C`new_with_options\*(C'\fR will throw an exception.
 349 .Sp
 350 If Getopt::Long::Descriptive is installed and any of the following
 351 command line params are passed, the program will exit with usage
 352 information. You can add descriptions for each option by including a
 353 \&\fBdocumentation\fR option for each attribute to document.
 354 .Sp
 355 .Vb 3
 356 \&  \-\-?
 357 \&  \-\-help
 358 \&  \-\-usage
 359 .Ve
 360 .Sp
 361 If you have Getopt::Long::Descriptive the \f(CW\*(C`usage\*(C'\fR param is also passed to
 362 \&\f(CW\*(C`new\*(C'\fR.
 363 .IP "\fB\s-1ARGV\s0\fR" 4
 364 .IX Item "ARGV"
 365 This accessor contains a reference to a copy of the \f(CW@ARGV\fR array
 366 as it originally existed at the time of \f(CW\*(C`new_with_options\*(C'\fR.
 367 .IP "\fBextra_argv\fR" 4
 368 .IX Item "extra_argv"
 369 This accessor contains an arrayref of leftover \f(CW@ARGV\fR elements that
 370 Getopt::Long did not parse.  Note that the real \f(CW@ARGV\fR is left
 371 un\-mangled.
 372 .IP "\fBmeta\fR" 4
 373 .IX Item "meta"
 374 This returns the role meta object.
 375 .SH "BUGS"
 376 .IX Header "BUGS"
 377 All complex software has bugs lurking in it, and this module is no
 378 exception. If you find a bug please either email me, or add the bug
 379 to cpan\-RT.
 380 .SH "AUTHOR"
 381 .IX Header "AUTHOR"
 382 Stevan Little <stevan@iinteractive.com>
 383 .PP
 384 Brandon L. Black, <blblack@gmail.com>
 385 .PP
 386 Yuval Kogman, <nothingmuch@woobling.org>
 387 .SH "CONTRIBUTORS"
 388 .IX Header "CONTRIBUTORS"
 389 Ryan D Johnson, <ryan@innerfence.com>
 390 .PP
 391 Drew Taylor, <drew@drewtaylor.com>
 392 .PP
 393 Tomas Doran, (t0m) \f(CW\*(C`<bobtfish@bobtfish.net>\*(C'\fR
 394 .SH "COPYRIGHT AND LICENSE"
 395 .IX Header "COPYRIGHT AND LICENSE"
 396 Copyright 2007\-2008 by Infinity Interactive, Inc.
 397 .PP
 398 <http://www.iinteractive.com>
 399 .PP
 400 This library is free software; you can redistribute it and/or modify
 401 it under the same terms as Perl itself.