mingw/html/lib/Getopt/Long.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Getopt::Long - Extended processing of command line options</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Getopt::Long - Extended processing of command line options</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#command_line_options__an_introduction">Command Line Options, an Introduction</a></li>
  26         <li><a href="#getting_started_with_getopt__long">Getting Started with Getopt::Long</a></li>
  27         <ul>
  28
  29                 <li><a href="#simple_options">Simple options</a></li>
  30                 <li><a href="#a_little_bit_less_simple_options">A little bit less simple options</a></li>
  31                 <li><a href="#mixing_command_line_option_with_other_arguments">Mixing command line option with other arguments</a></li>
  32                 <li><a href="#options_with_values">Options with values</a></li>
  33                 <li><a href="#options_with_multiple_values">Options with multiple values</a></li>
  34                 <li><a href="#options_with_hash_values">Options with hash values</a></li>
  35                 <li><a href="#userdefined_subroutines_to_handle_options">User-defined subroutines to handle options</a></li>
  36                 <li><a href="#options_with_multiple_names">Options with multiple names</a></li>
  37                 <li><a href="#case_and_abbreviations">Case and abbreviations</a></li>
  38                 <li><a href="#summary_of_option_specifications">Summary of Option Specifications</a></li>
  39         </ul>
  40
  41         <li><a href="#advanced_possibilities">Advanced Possibilities</a></li>
  42         <ul>
  43
  44                 <li><a href="#object_oriented_interface">Object oriented interface</a></li>
  45                 <li><a href="#thread_safety">Thread Safety</a></li>
  46                 <li><a href="#documentation_and_help_texts">Documentation and help texts</a></li>
  47                 <li><a href="#storing_option_values_in_a_hash">Storing option values in a hash</a></li>
  48                 <li><a href="#bundling">Bundling</a></li>
  49                 <li><a href="#the_lonesome_dash">The lonesome dash</a></li>
  50                 <li><a href="#argument_callback">Argument callback</a></li>
  51         </ul>
  52
  53         <li><a href="#configuring_getopt__long">Configuring Getopt::Long</a></li>
  54         <li><a href="#exportable_methods">Exportable Methods</a></li>
  55         <li><a href="#return_values_and_errors">Return values and Errors</a></li>
  56         <li><a href="#legacy">Legacy</a></li>
  57         <ul>
  58
  59                 <li><a href="#default_destinations">Default destinations</a></li>
  60                 <li><a href="#alternative_option_starters">Alternative option starters</a></li>
  61                 <li><a href="#configuration_variables">Configuration variables</a></li>
  62         </ul>
  63
  64         <li><a href="#trouble_shooting">Trouble Shooting</a></li>
  65         <ul>
  66
  67                 <li><a href="#getoptions_does_not_return_a_false_result_when_an_option_is_not_supplied">GetOptions does not return a false result when an option is not supplied</a></li>
  68                 <li><a href="#getoptions_does_not_split_the_command_line_correctly">GetOptions does not split the command line correctly</a></li>
  69                 <li><a href="#undefined_subroutine__main__getoptions_called">Undefined subroutine &amp;main::GetOptions called</a></li>
  70                 <li><a href="#how_do_i_put_a__option_into_a_getopt__long">How do I put a ``-?'' option into a Getopt::Long?</a></li>
  71         </ul>
  72
  73         <li><a href="#author">AUTHOR</a></li>
  74         <li><a href="#copyright_and_disclaimer">COPYRIGHT AND DISCLAIMER</a></li>
  75 </ul>
  76 <!-- INDEX END -->
  77
  78 <hr />
  79 <p>
  80 </p>
  81 <h1><a name="name">NAME</a></h1>
  82 <p>Getopt::Long - Extended processing of command line options</p>
  83 <p>
  84 </p>
  85 <hr />
  86 <h1><a name="synopsis">SYNOPSIS</a></h1>
  87 <pre>
  88   use Getopt::Long;
  89   my $data   = &quot;file.dat&quot;;
  90   my $length = 24;
  91   my $verbose;
  92   $result = GetOptions (&quot;length=i&quot; =&gt; \$length,    # numeric
  93                         &quot;file=s&quot;   =&gt; \$data,      # string
  94                         &quot;verbose&quot;  =&gt; \$verbose);  # flag</pre>
  95 <p>
  96 </p>
  97 <hr />
  98 <h1><a name="description">DESCRIPTION</a></h1>
  99 <p>The Getopt::Long module implements an extended getopt function called
 100 GetOptions(). This function adheres to the POSIX syntax for command
 101 line options, with GNU extensions. In general, this means that options
 102 have long names instead of single letters, and are introduced with a
 103 double dash ``--''. Support for bundling of command line options, as was
 104 the case with the more traditional single-letter approach, is provided
 105 but not enabled by default.</p>
 106 <p>
 107 </p>
 108 <hr />
 109 <h1><a name="command_line_options__an_introduction">Command Line Options, an Introduction</a></h1>
 110 <p>Command line operated programs traditionally take their arguments from
 111 the command line, for example filenames or other information that the
 112 program needs to know. Besides arguments, these programs often take
 113 command line <em>options</em> as well. Options are not necessary for the
 114 program to work, hence the name 'option', but are used to modify its
 115 default behaviour. For example, a program could do its job quietly,
 116 but with a suitable option it could provide verbose information about
 117 what it did.</p>
 118 <p>Command line options come in several flavours. Historically, they are
 119 preceded by a single dash <code>-</code>, and consist of a single letter.</p>
 120 <pre>
 121     -l -a -c</pre>
 122 <p>Usually, these single-character options can be bundled:</p>
 123 <pre>
 124     -lac</pre>
 125 <p>Options can have values, the value is placed after the option
 126 character. Sometimes with whitespace in between, sometimes not:</p>
 127 <pre>
 128     -s 24 -s24</pre>
 129 <p>Due to the very cryptic nature of these options, another style was
 130 developed that used long names. So instead of a cryptic <code>-l</code> one
 131 could use the more descriptive <code>--long</code>. To distinguish between a
 132 bundle of single-character options and a long one, two dashes are used
 133 to precede the option name. Early implementations of long options used
 134 a plus <a href="#item__2b"><code>+</code></a> instead. Also, option values could be specified either
 135 like</p>
 136 <pre>
 137     --size=24</pre>
 138 <p>or</p>
 139 <pre>
 140     --size 24</pre>
 141 <p>The <a href="#item__2b"><code>+</code></a> form is now obsolete and strongly deprecated.</p>
 142 <p>
 143 </p>
 144 <hr />
 145 <h1><a name="getting_started_with_getopt__long">Getting Started with Getopt::Long</a></h1>
 146 <p>Getopt::Long is the Perl5 successor of <code>newgetopt.pl</code>. This was the
 147 first Perl module that provided support for handling the new style of
 148 command line options, hence the name Getopt::Long. This module also
 149 supports single-character options and bundling. Single character
 150 options may be any alphabetic character, a question mark, and a dash.
 151 Long options may consist of a series of letters, digits, and dashes.
 152 Although this is currently not enforced by Getopt::Long, multiple
 153 consecutive dashes are not allowed, and the option name must not end
 154 with a dash.</p>
 155 <p>To use Getopt::Long from a Perl program, you must include the
 156 following line in your Perl program:</p>
 157 <pre>
 158     use Getopt::Long;</pre>
 159 <p>This will load the core of the Getopt::Long module and prepare your
 160 program for using it. Most of the actual Getopt::Long code is not
 161 loaded until you really call one of its functions.</p>
 162 <p>In the default configuration, options names may be abbreviated to
 163 uniqueness, case does not matter, and a single dash is sufficient,
 164 even for long option names. Also, options may be placed between
 165 non-option arguments. See <a href="#configuring_getopt__long">Configuring Getopt::Long</a> for more
 166 details on how to configure Getopt::Long.</p>
 167 <p>
 168 </p>
 169 <h2><a name="simple_options">Simple options</a></h2>
 170 <p>The most simple options are the ones that take no values. Their mere
 171 presence on the command line enables the option. Popular examples are:</p>
 172 <pre>
 173     --all --verbose --quiet --debug</pre>
 174 <p>Handling simple options is straightforward:</p>
 175 <pre>
 176     my $verbose = '';   # option variable with default value (false)
 177     my $all = '';       # option variable with default value (false)
 178     GetOptions ('verbose' =&gt; \$verbose, 'all' =&gt; \$all);</pre>
 179 <p>The call to <code>GetOptions()</code> parses the command line arguments that are
 180 present in <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__argv"><code>@ARGV</code></a> and sets the option variable to the value <code>1</code> if
 181 the option did occur on the command line. Otherwise, the option
 182 variable is not touched. Setting the option value to true is often
 183 called <em>enabling</em> the option.</p>
 184 <p>The option name as specified to the <code>GetOptions()</code> function is called
 185 the option <em>specification</em>. Later we'll see that this specification
 186 can contain more than just the option name. The reference to the
 187 variable is called the option <em>destination</em>.</p>
 188 <p><code>GetOptions()</code> will return a true value if the command line could be
 189 processed successfully. Otherwise, it will write error messages to
 190 STDERR, and return a false result.</p>
 191 <p>
 192 </p>
 193 <h2><a name="a_little_bit_less_simple_options">A little bit less simple options</a></h2>
 194 <p>Getopt::Long supports two useful variants of simple options:
 195 <em>negatable</em> options and <em>incremental</em> options.</p>
 196 <p>A negatable option is specified with an exclamation mark <a href="#item__21"><code>!</code></a> after the
 197 option name:</p>
 198 <pre>
 199     my $verbose = '';   # option variable with default value (false)
 200     GetOptions ('verbose!' =&gt; \$verbose);</pre>
 201 <p>Now, using <code>--verbose</code> on the command line will enable <code>$verbose</code>,
 202 as expected. But it is also allowed to use <code>--noverbose</code>, which will
 203 disable <code>$verbose</code> by setting its value to <code>0</code>. Using a suitable
 204 default value, the program can find out whether <code>$verbose</code> is false
 205 by default, or disabled by using <code>--noverbose</code>.</p>
 206 <p>An incremental option is specified with a plus <a href="#item__2b"><code>+</code></a> after the
 207 option name:</p>
 208 <pre>
 209     my $verbose = '';   # option variable with default value (false)
 210     GetOptions ('verbose+' =&gt; \$verbose);</pre>
 211 <p>Using <code>--verbose</code> on the command line will increment the value of
 212 <code>$verbose</code>. This way the program can keep track of how many times the
 213 option occurred on the command line. For example, each occurrence of
 214 <code>--verbose</code> could increase the verbosity level of the program.</p>
 215 <p>
 216 </p>
 217 <h2><a name="mixing_command_line_option_with_other_arguments">Mixing command line option with other arguments</a></h2>
 218 <p>Usually programs take command line options as well as other arguments,
 219 for example, file names. It is good practice to always specify the
 220 options first, and the other arguments last. Getopt::Long will,
 221 however, allow the options and arguments to be mixed and 'filter out'
 222 all the options before passing the rest of the arguments to the
 223 program. To stop Getopt::Long from processing further arguments,
 224 insert a double dash <code>--</code> on the command line:</p>
 225 <pre>
 226     --size 24 -- --all</pre>
 227 <p>In this example, <code>--all</code> will <em>not</em> be treated as an option, but
 228 passed to the program unharmed, in <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__argv"><code>@ARGV</code></a>.</p>
 229 <p>
 230 </p>
 231 <h2><a name="options_with_values">Options with values</a></h2>
 232 <p>For options that take values it must be specified whether the option
 233 value is required or not, and what kind of value the option expects.</p>
 234 <p>Three kinds of values are supported: integer numbers, floating point
 235 numbers, and strings.</p>
 236 <p>If the option value is required, Getopt::Long will take the
 237 command line argument that follows the option and assign this to the
 238 option variable. If, however, the option value is specified as
 239 optional, this will only be done if that value does not look like a
 240 valid command line option itself.</p>
 241 <pre>
 242     my $tag = '';       # option variable with default value
 243     GetOptions ('tag=s' =&gt; \$tag);</pre>
 244 <p>In the option specification, the option name is followed by an equals
 245 sign <code>=</code> and the letter <a href="#item_s"><code>s</code></a>. The equals sign indicates that this
 246 option requires a value. The letter <a href="#item_s"><code>s</code></a> indicates that this value is
 247 an arbitrary string. Other possible value types are <a href="#item_i"><code>i</code></a> for integer
 248 values, and <a href="#item_f"><code>f</code></a> for floating point values. Using a colon <code>:</code> instead
 249 of the equals sign indicates that the option value is optional. In
 250 this case, if no suitable value is supplied, string valued options get
 251 an empty string <code>''</code> assigned, while numeric options are set to <code>0</code>.</p>
 252 <p>
 253 </p>
 254 <h2><a name="options_with_multiple_values">Options with multiple values</a></h2>
 255 <p>Options sometimes take several values. For example, a program could
 256 use multiple directories to search for library files:</p>
 257 <pre>
 258     --library lib/stdlib --library lib/extlib</pre>
 259 <p>To accomplish this behaviour, simply specify an array reference as the
 260 destination for the option:</p>
 261 <pre>
 262     GetOptions (&quot;library=s&quot; =&gt; \@libfiles);</pre>
 263 <p>Alternatively, you can specify that the option can have multiple
 264 values by adding a ``@'', and pass a scalar reference as the
 265 destination:</p>
 266 <pre>
 267     GetOptions (&quot;library=s@&quot; =&gt; \$libfiles);</pre>
 268 <p>Used with the example above, <code>@libfiles</code> (or <code>@$libfiles</code>) would
 269 contain two strings upon completion: <code>&quot;lib/srdlib&quot;</code> and
 270 <code>&quot;lib/extlib&quot;</code>, in that order. It is also possible to specify that
 271 only integer or floating point numbers are acceptable values.</p>
 272 <p>Often it is useful to allow comma-separated lists of values as well as
 273 multiple occurrences of the options. This is easy using Perl's <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_split"><code>split()</code></a>
 274 and <code>join()</code> operators:</p>
 275 <pre>
 276     GetOptions (&quot;library=s&quot; =&gt; \@libfiles);
 277     @libfiles = split(/,/,join(',',@libfiles));</pre>
 278 <p>Of course, it is important to choose the right separator string for
 279 each purpose.</p>
 280 <p>Warning: What follows is an experimental feature.</p>
 281 <p>Options can take multiple values at once, for example</p>
 282 <pre>
 283     --coordinates 52.2 16.4 --rgbcolor 255 255 149</pre>
 284 <p>This can be accomplished by adding a repeat specifier to the option
 285 specification. Repeat specifiers are very similar to the <code>{...}</code>
 286 repeat specifiers that can be used with regular expression patterns.
 287 For example, the above command line would be handled as follows:</p>
 288 <pre>
 289     GetOptions('coordinates=f{2}' =&gt; \@coor, 'rgbcolor=i{3}' =&gt; \@color);</pre>
 290 <p>The destination for the option must be an array or array reference.</p>
 291 <p>It is also possible to specify the minimal and maximal number of
 292 arguments an option takes. <code>foo=s{2,4}</code> indicates an option that
 293 takes at least two and at most 4 arguments. <code>foo=s{,}</code> indicates one
 294 or more values; <code>foo:s{,}</code> indicates zero or more option values.</p>
 295 <p>
 296 </p>
 297 <h2><a name="options_with_hash_values">Options with hash values</a></h2>
 298 <p>If the option destination is a reference to a hash, the option will
 299 take, as value, strings of the form <em>key</em><code>=</code><em>value</em>. The value will
 300 be stored with the specified key in the hash.</p>
 301 <pre>
 302     GetOptions (&quot;define=s&quot; =&gt; \%defines);</pre>
 303 <p>Alternatively you can use:</p>
 304 <pre>
 305     GetOptions (&quot;define=s%&quot; =&gt; \$defines);</pre>
 306 <p>When used with command line options:</p>
 307 <pre>
 308     --define os=linux --define vendor=redhat</pre>
 309 <p>the hash <code>%defines</code> (or <code>%$defines</code>) will contain two keys, <code>&quot;os&quot;</code>
 310 with value <code>&quot;linux</code> and <code>&quot;vendor&quot;</code> with value <code>&quot;redhat&quot;</code>. It is
 311 also possible to specify that only integer or floating point numbers
 312 are acceptable values. The keys are always taken to be strings.</p>
 313 <p>
 314 </p>
 315 <h2><a name="userdefined_subroutines_to_handle_options">User-defined subroutines to handle options</a></h2>
 316 <p>Ultimate control over what should be done when (actually: each time)
 317 an option is encountered on the command line can be achieved by
 318 designating a reference to a subroutine (or an anonymous subroutine)
 319 as the option destination. When <code>GetOptions()</code> encounters the option, it
 320 will call the subroutine with two or three arguments. The first
 321 argument is the name of the option. For a scalar or array destination,
 322 the second argument is the value to be stored. For a hash destination,
 323 the second arguments is the key to the hash, and the third argument
 324 the value to be stored. It is up to the subroutine to store the value,
 325 or do whatever it thinks is appropriate.</p>
 326 <p>A trivial application of this mechanism is to implement options that
 327 are related to each other. For example:</p>
 328 <pre>
 329     my $verbose = '';   # option variable with default value (false)
 330     GetOptions ('verbose' =&gt; \$verbose,
 331                 'quiet'   =&gt; sub { $verbose = 0 });</pre>
 332 <p>Here <code>--verbose</code> and <code>--quiet</code> control the same variable
 333 <code>$verbose</code>, but with opposite values.</p>
 334 <p>If the subroutine needs to signal an error, it should call <code>die()</code> with
 335 the desired error message as its argument. <code>GetOptions()</code> will catch the
 336 die(), issue the error message, and record that an error result must
 337 be returned upon completion.</p>
 338 <p>If the text of the error message starts with an exclamation mark <a href="#item__21"><code>!</code></a>
 339 it is interpreted specially by GetOptions(). There is currently one
 340 special command implemented: <code>die(&quot;!FINISH&quot;)</code> will cause <code>GetOptions()</code>
 341 to stop processing options, as if it encountered a double dash <code>--</code>.</p>
 342 <p>
 343 </p>
 344 <h2><a name="options_with_multiple_names">Options with multiple names</a></h2>
 345 <p>Often it is user friendly to supply alternate mnemonic names for
 346 options. For example <code>--height</code> could be an alternate name for
 347 <code>--length</code>. Alternate names can be included in the option
 348 specification, separated by vertical bar <code>|</code> characters. To implement
 349 the above example:</p>
 350 <pre>
 351     GetOptions ('length|height=f' =&gt; \$length);</pre>
 352 <p>The first name is called the <em>primary</em> name, the other names are
 353 called <em>aliases</em>. When using a hash to store options, the key will
 354 always be the primary name.</p>
 355 <p>Multiple alternate names are possible.</p>
 356 <p>
 357 </p>
 358 <h2><a name="case_and_abbreviations">Case and abbreviations</a></h2>
 359 <p>Without additional configuration, <code>GetOptions()</code> will ignore the case of
 360 option names, and allow the options to be abbreviated to uniqueness.</p>
 361 <pre>
 362     GetOptions ('length|height=f' =&gt; \$length, &quot;head&quot; =&gt; \$head);</pre>
 363 <p>This call will allow <code>--l</code> and <code>--L</code> for the length option, but
 364 requires a least <code>--hea</code> and <code>--hei</code> for the head and height options.</p>
 365 <p>
 366 </p>
 367 <h2><a name="summary_of_option_specifications">Summary of Option Specifications</a></h2>
 368 <p>Each option specifier consists of two parts: the name specification
 369 and the argument specification.</p>
 370 <p>The name specification contains the name of the option, optionally
 371 followed by a list of alternative names separated by vertical bar
 372 characters.</p>
 373 <pre>
 374     length            option name is &quot;length&quot;
 375     length|size|l     name is &quot;length&quot;, aliases are &quot;size&quot; and &quot;l&quot;</pre>
 376 <p>The argument specification is optional. If omitted, the option is
 377 considered boolean, a value of 1 will be assigned when the option is
 378 used on the command line.</p>
 379 <p>The argument specification can be</p>
 380 <dl>
 381 <dt><strong><a name="item__21">!</a></strong>
 382
 383 <dd>
 384 <p>The option does not take an argument and may be negated by prefixing
 385 it with ``no'' or ``no-''. E.g. <code>&quot;foo!&quot;</code> will allow <code>--foo</code> (a value of
 386 1 will be assigned) as well as <code>--nofoo</code> and <code>--no-foo</code> (a value of
 387 0 will be assigned). If the option has aliases, this applies to the
 388 aliases as well.</p>
 389 </dd>
 390 <dd>
 391 <p>Using negation on a single letter option when bundling is in effect is
 392 pointless and will result in a warning.</p>
 393 </dd>
 394 </li>
 395 <dt><strong><a name="item__2b">+</a></strong>
 396
 397 <dd>
 398 <p>The option does not take an argument and will be incremented by 1
 399 every time it appears on the command line. E.g. <code>&quot;more+&quot;</code>, when used
 400 with <code>--more --more --more</code>, will increment the value three times,
 401 resulting in a value of 3 (provided it was 0 or undefined at first).</p>
 402 </dd>
 403 <dd>
 404 <p>The <a href="#item__2b"><code>+</code></a> specifier is ignored if the option destination is not a scalar.</p>
 405 </dd>
 406 </li>
 407 <dt><strong><a name="item__3d_type__5b_desttype__5d__5b_repeat__5d">= <em>type</em> [ <em>desttype</em> ] [ <em>repeat</em> ]</a></strong>
 408
 409 <dd>
 410 <p>The option requires an argument of the given type. Supported types
 411 are:</p>
 412 </dd>
 413 <dl>
 414 <dt><strong><a name="item_s">s</a></strong>
 415
 416 <dd>
 417 <p>String. An arbitrary sequence of characters. It is valid for the
 418 argument to start with <code>-</code> or <code>--</code>.</p>
 419 </dd>
 420 </li>
 421 <dt><strong><a name="item_i">i</a></strong>
 422
 423 <dd>
 424 <p>Integer. An optional leading plus or minus sign, followed by a
 425 sequence of digits.</p>
 426 </dd>
 427 </li>
 428 <dt><strong><a name="item_o">o</a></strong>
 429
 430 <dd>
 431 <p>Extended integer, Perl style. This can be either an optional leading
 432 plus or minus sign, followed by a sequence of digits, or an octal
 433 string (a zero, optionally followed by '0', '1', .. '7'), or a
 434 hexadecimal string (<code>0x</code> followed by '0' .. '9', 'a' .. 'f', case
 435 insensitive), or a binary string (<code>0b</code> followed by a series of '0'
 436 and '1').</p>
 437 </dd>
 438 </li>
 439 <dt><strong><a name="item_f">f</a></strong>
 440
 441 <dd>
 442 <p>Real number. For example <code>3.14</code>, <code>-6.23E24</code> and so on.</p>
 443 </dd>
 444 </li>
 445 </dl>
 446 <p>The <em>desttype</em> can be <code>@</code> or <code>%</code> to specify that the option is
 447 list or a hash valued. This is only needed when the destination for
 448 the option value is not otherwise specified. It should be omitted when
 449 not needed.</p>
 450 <p>The <em>repeat</em> specifies the number of values this option takes per
 451 occurrence on the command line. It has the format <code>{</code> [ <em>min</em> ] [ <code>,</code> [ <em>max</em> ] ] <code>}</code>.</p>
 452 <p><em>min</em> denotes the minimal number of arguments. It defaults to 1 for
 453 options with <code>=</code> and to 0 for options with <code>:</code>, see below. Note that
 454 <em>min</em> overrules the <code>=</code> / <code>:</code> semantics.</p>
 455 <p><em>max</em> denotes the maximum number of arguments. It must be at least
 456 <em>min</em>. If <em>max</em> is omitted, <em>but the comma is not</em>, there is no
 457 upper bound to the number of argument values taken.</p>
 458 <dt><strong><a name="item__3a_type__5b_desttype__5d">: <em>type</em> [ <em>desttype</em> ]</a></strong>
 459
 460 <dd>
 461 <p>Like <code>=</code>, but designates the argument as optional.
 462 If omitted, an empty string will be assigned to string values options,
 463 and the value zero to numeric options.</p>
 464 </dd>
 465 <dd>
 466 <p>Note that if a string argument starts with <code>-</code> or <code>--</code>, it will be
 467 considered an option on itself.</p>
 468 </dd>
 469 </li>
 470 <dt><strong><a name="item__3a_number__5b_desttype__5d">: <em>number</em> [ <em>desttype</em> ]</a></strong>
 471
 472 <dd>
 473 <p>Like <code>:i</code>, but if the value is omitted, the <em>number</em> will be assigned.</p>
 474 </dd>
 475 </li>
 476 <dt><strong><a name="item__3a__2b__5b_desttype__5d">: + [ <em>desttype</em> ]</a></strong>
 477
 478 <dd>
 479 <p>Like <code>:i</code>, but if the value is omitted, the current value for the
 480 option will be incremented.</p>
 481 </dd>
 482 </li>
 483 </dl>
 484 <p>
 485 </p>
 486 <hr />
 487 <h1><a name="advanced_possibilities">Advanced Possibilities</a></h1>
 488 <p>
 489 </p>
 490 <h2><a name="object_oriented_interface">Object oriented interface</a></h2>
 491 <p>Getopt::Long can be used in an object oriented way as well:</p>
 492 <pre>
 493     use Getopt::Long;
 494     $p = new Getopt::Long::Parser;
 495     $p-&gt;configure(...configuration options...);
 496     if ($p-&gt;getoptions(...options descriptions...)) ...</pre>
 497 <p>Configuration options can be passed to the constructor:</p>
 498 <pre>
 499     $p = new Getopt::Long::Parser
 500              config =&gt; [...configuration options...];</pre>
 501 <p>
 502 </p>
 503 <h2><a name="thread_safety">Thread Safety</a></h2>
 504 <p>Getopt::Long is thread safe when using ithreads as of Perl 5.8.  It is
 505 <em>not</em> thread safe when using the older (experimental and now
 506 obsolete) threads implementation that was added to Perl 5.005.</p>
 507 <p>
 508 </p>
 509 <h2><a name="documentation_and_help_texts">Documentation and help texts</a></h2>
 510 <p>Getopt::Long encourages the use of Pod::Usage to produce help
 511 messages. For example:</p>
 512 <pre>
 513     use Getopt::Long;
 514     use Pod::Usage;</pre>
 515 <pre>
 516     my $man = 0;
 517     my $help = 0;</pre>
 518 <pre>
 519     GetOptions('help|?' =&gt; \$help, man =&gt; \$man) or pod2usage(2);
 520     pod2usage(1) if $help;
 521     pod2usage(-exitstatus =&gt; 0, -verbose =&gt; 2) if $man;</pre>
 522 <pre>
 523     __END__</pre>
 524 <pre>
 525     =head1 NAME</pre>
 526 <pre>
 527     sample - Using Getopt::Long and Pod::Usage</pre>
 528 <pre>
 529     =head1 SYNOPSIS</pre>
 530 <pre>
 531     sample [options] [file ...]</pre>
 532 <pre>
 533      Options:
 534        -help            brief help message
 535        -man             full documentation</pre>
 536 <pre>
 537     =head1 OPTIONS</pre>
 538 <pre>
 539     =over 8</pre>
 540 <pre>
 541     =item B&lt;-help&gt;</pre>
 542 <pre>
 543     Print a brief help message and exits.</pre>
 544 <pre>
 545     =item B&lt;-man&gt;</pre>
 546 <pre>
 547     Prints the manual page and exits.</pre>
 548 <pre>
 549     =back</pre>
 550 <pre>
 551     =head1 DESCRIPTION</pre>
 552 <pre>
 553     B&lt;This program&gt; will read the given input file(s) and do something
 554     useful with the contents thereof.</pre>
 555 <pre>
 556     =cut</pre>
 557 <p>See <a href="file://C|\msysgit\mingw\html/lib/Pod/Usage.html">the Pod::Usage manpage</a> for details.</p>
 558 <p>
 559 </p>
 560 <h2><a name="storing_option_values_in_a_hash">Storing option values in a hash</a></h2>
 561 <p>Sometimes, for example when there are a lot of options, having a
 562 separate variable for each of them can be cumbersome. <code>GetOptions()</code>
 563 supports, as an alternative mechanism, storing options in a hash.</p>
 564 <p>To obtain this, a reference to a hash must be passed <em>as the first
 565 argument</em> to GetOptions(). For each option that is specified on the
 566 command line, the option value will be stored in the hash with the
 567 option name as key. Options that are not actually used on the command
 568 line will not be put in the hash, on other words,
 569 <code>exists($h{option})</code> (or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_defined"><code>defined())</code></a> can be used to test if an option
 570 was used. The drawback is that warnings will be issued if the program
 571 runs under <code>use strict</code> and uses <code>$h{option}</code> without testing with
 572 <code>exists()</code> or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_defined"><code>defined()</code></a> first.</p>
 573 <pre>
 574     my %h = ();
 575     GetOptions (\%h, 'length=i');       # will store in $h{length}</pre>
 576 <p>For options that take list or hash values, it is necessary to indicate
 577 this by appending an <code>@</code> or <code>%</code> sign after the type:</p>
 578 <pre>
 579     GetOptions (\%h, 'colours=s@');     # will push to @{$h{colours}}</pre>
 580 <p>To make things more complicated, the hash may contain references to
 581 the actual destinations, for example:</p>
 582 <pre>
 583     my $len = 0;
 584     my %h = ('length' =&gt; \$len);
 585     GetOptions (\%h, 'length=i');       # will store in $len</pre>
 586 <p>This example is fully equivalent with:</p>
 587 <pre>
 588     my $len = 0;
 589     GetOptions ('length=i' =&gt; \$len);   # will store in $len</pre>
 590 <p>Any mixture is possible. For example, the most frequently used options
 591 could be stored in variables while all other options get stored in the
 592 hash:</p>
 593 <pre>
 594     my $verbose = 0;                    # frequently referred
 595     my $debug = 0;                      # frequently referred
 596     my %h = ('verbose' =&gt; \$verbose, 'debug' =&gt; \$debug);
 597     GetOptions (\%h, 'verbose', 'debug', 'filter', 'size=i');
 598     if ( $verbose ) { ... }
 599     if ( exists $h{filter} ) { ... option 'filter' was specified ... }</pre>
 600 <p>
 601 </p>
 602 <h2><a name="bundling">Bundling</a></h2>
 603 <p>With bundling it is possible to set several single-character options
 604 at once. For example if <code>a</code>, <code>v</code> and <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_x"><code>x</code></a> are all valid options,</p>
 605 <pre>
 606     -vax</pre>
 607 <p>would set all three.</p>
 608 <p>Getopt::Long supports two levels of bundling. To enable bundling, a
 609 call to Getopt::Long::Configure is required.</p>
 610 <p>The first level of bundling can be enabled with:</p>
 611 <pre>
 612     Getopt::Long::Configure (&quot;bundling&quot;);</pre>
 613 <p>Configured this way, single-character options can be bundled but long
 614 options <strong>must</strong> always start with a double dash <code>--</code> to avoid
 615 ambiguity. For example, when <code>vax</code>, <code>a</code>, <code>v</code> and <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_x"><code>x</code></a> are all valid
 616 options,</p>
 617 <pre>
 618     -vax</pre>
 619 <p>would set <code>a</code>, <code>v</code> and <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#item_x"><code>x</code></a>, but</p>
 620 <pre>
 621     --vax</pre>
 622 <p>would set <code>vax</code>.</p>
 623 <p>The second level of bundling lifts this restriction. It can be enabled
 624 with:</p>
 625 <pre>
 626     Getopt::Long::Configure (&quot;bundling_override&quot;);</pre>
 627 <p>Now, <code>-vax</code> would set the option <code>vax</code>.</p>
 628 <p>When any level of bundling is enabled, option values may be inserted
 629 in the bundle. For example:</p>
 630 <pre>
 631     -h24w80</pre>
 632 <p>is equivalent to</p>
 633 <pre>
 634     -h 24 -w 80</pre>
 635 <p>When configured for bundling, single-character options are matched
 636 case sensitive while long options are matched case insensitive. To
 637 have the single-character options matched case insensitive as well,
 638 use:</p>
 639 <pre>
 640     Getopt::Long::Configure (&quot;bundling&quot;, &quot;ignorecase_always&quot;);</pre>
 641 <p>It goes without saying that bundling can be quite confusing.</p>
 642 <p>
 643 </p>
 644 <h2><a name="the_lonesome_dash">The lonesome dash</a></h2>
 645 <p>Normally, a lone dash <code>-</code> on the command line will not be considered
 646 an option. Option processing will terminate (unless ``permute'' is
 647 configured) and the dash will be left in <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__argv"><code>@ARGV</code></a>.</p>
 648 <p>It is possible to get special treatment for a lone dash. This can be
 649 achieved by adding an option specification with an empty name, for
 650 example:</p>
 651 <pre>
 652     GetOptions ('' =&gt; \$stdio);</pre>
 653 <p>A lone dash on the command line will now be a legal option, and using
 654 it will set variable <code>$stdio</code>.</p>
 655 <p>
 656 </p>
 657 <h2><a name="argument_callback">Argument callback</a></h2>
 658 <p>A special option 'name' <code>&lt;&gt;</code> can be used to designate a subroutine
 659 to handle non-option arguments. When <code>GetOptions()</code> encounters an
 660 argument that does not look like an option, it will immediately call this
 661 subroutine and passes it one parameter: the argument name.</p>
 662 <p>For example:</p>
 663 <pre>
 664     my $width = 80;
 665     sub process { ... }
 666     GetOptions ('width=i' =&gt; \$width, '&lt;&gt;' =&gt; \&amp;process);</pre>
 667 <p>When applied to the following command line:</p>
 668 <pre>
 669     arg1 --width=72 arg2 --width=60 arg3</pre>
 670 <p>This will call
 671 <code>process(&quot;arg1&quot;)</code> while <code>$width</code> is <code>80</code>,
 672 <code>process(&quot;arg2&quot;)</code> while <code>$width</code> is <code>72</code>, and
 673 <code>process(&quot;arg3&quot;)</code> while <code>$width</code> is <code>60</code>.</p>
 674 <p>This feature requires configuration option <strong>permute</strong>, see section
 675 <a href="#configuring_getopt__long">Configuring Getopt::Long</a>.</p>
 676 <p>
 677 </p>
 678 <hr />
 679 <h1><a name="configuring_getopt__long">Configuring Getopt::Long</a></h1>
 680 <p>Getopt::Long can be configured by calling subroutine
 681 Getopt::Long::Configure(). This subroutine takes a list of quoted
 682 strings, each specifying a configuration option to be enabled, e.g.
 683 <a href="#item_ignore_case"><code>ignore_case</code></a>, or disabled, e.g. <code>no_ignore_case</code>. Case does not
 684 matter. Multiple calls to <code>Configure()</code> are possible.</p>
 685 <p>Alternatively, as of version 2.24, the configuration options may be
 686 passed together with the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a> statement:</p>
 687 <pre>
 688     use Getopt::Long qw(:config no_ignore_case bundling);</pre>
 689 <p>The following options are available:</p>
 690 <dl>
 691 <dt><strong><a name="item_default">default</a></strong>
 692
 693 <dd>
 694 <p>This option causes all configuration options to be reset to their
 695 default values.</p>
 696 </dd>
 697 </li>
 698 <dt><strong><a name="item_posix_default">posix_default</a></strong>
 699
 700 <dd>
 701 <p>This option causes all configuration options to be reset to their
 702 default values as if the environment variable POSIXLY_CORRECT had
 703 been set.</p>
 704 </dd>
 705 </li>
 706 <dt><strong><a name="item_auto_abbrev">auto_abbrev</a></strong>
 707
 708 <dd>
 709 <p>Allow option names to be abbreviated to uniqueness.
 710 Default is enabled unless environment variable
 711 POSIXLY_CORRECT has been set, in which case <a href="#item_auto_abbrev"><code>auto_abbrev</code></a> is disabled.</p>
 712 </dd>
 713 </li>
 714 <dt><strong><a name="item_getopt_compat">getopt_compat</a></strong>
 715
 716 <dd>
 717 <p>Allow <a href="#item__2b"><code>+</code></a> to start options.
 718 Default is enabled unless environment variable
 719 POSIXLY_CORRECT has been set, in which case <a href="#item_getopt_compat"><code>getopt_compat</code></a> is disabled.</p>
 720 </dd>
 721 </li>
 722 <dt><strong><a name="item_gnu_compat">gnu_compat</a></strong>
 723
 724 <dd>
 725 <p><a href="#item_gnu_compat"><code>gnu_compat</code></a> controls whether <code>--opt=</code> is allowed, and what it should
 726 do. Without <a href="#item_gnu_compat"><code>gnu_compat</code></a>, <code>--opt=</code> gives an error. With <a href="#item_gnu_compat"><code>gnu_compat</code></a>,
 727 <code>--opt=</code> will give option <code>opt</code> and empty value.
 728 This is the way GNU <code>getopt_long()</code> does it.</p>
 729 </dd>
 730 </li>
 731 <dt><strong><a name="item_gnu_getopt">gnu_getopt</a></strong>
 732
 733 <dd>
 734 <p>This is a short way of setting <a href="#item_gnu_compat"><code>gnu_compat</code></a> <a href="#item_bundling"><code>bundling</code></a> <a href="#item_permute"><code>permute</code></a>
 735 <code>no_getopt_compat</code>. With <a href="#item_gnu_getopt"><code>gnu_getopt</code></a>, command line handling should be
 736 fully compatible with GNU getopt_long().</p>
 737 </dd>
 738 </li>
 739 <dt><strong><a name="item_require_order">require_order</a></strong>
 740
 741 <dd>
 742 <p>Whether command line arguments are allowed to be mixed with options.
 743 Default is disabled unless environment variable
 744 POSIXLY_CORRECT has been set, in which case <a href="#item_require_order"><code>require_order</code></a> is enabled.</p>
 745 </dd>
 746 <dd>
 747 <p>See also <a href="#item_permute"><code>permute</code></a>, which is the opposite of <a href="#item_require_order"><code>require_order</code></a>.</p>
 748 </dd>
 749 </li>
 750 <dt><strong><a name="item_permute">permute</a></strong>
 751
 752 <dd>
 753 <p>Whether command line arguments are allowed to be mixed with options.
 754 Default is enabled unless environment variable
 755 POSIXLY_CORRECT has been set, in which case <a href="#item_permute"><code>permute</code></a> is disabled.
 756 Note that <a href="#item_permute"><code>permute</code></a> is the opposite of <a href="#item_require_order"><code>require_order</code></a>.</p>
 757 </dd>
 758 <dd>
 759 <p>If <a href="#item_permute"><code>permute</code></a> is enabled, this means that</p>
 760 </dd>
 761 <dd>
 762 <pre>
 763     --foo arg1 --bar arg2 arg3</pre>
 764 </dd>
 765 <dd>
 766 <p>is equivalent to</p>
 767 </dd>
 768 <dd>
 769 <pre>
 770     --foo --bar arg1 arg2 arg3</pre>
 771 </dd>
 772 <dd>
 773 <p>If an argument callback routine is specified, <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__argv"><code>@ARGV</code></a> will always be
 774 empty upon successful return of <code>GetOptions()</code> since all options have been
 775 processed. The only exception is when <code>--</code> is used:</p>
 776 </dd>
 777 <dd>
 778 <pre>
 779     --foo arg1 --bar arg2 -- arg3</pre>
 780 </dd>
 781 <dd>
 782 <p>This will call the callback routine for arg1 and arg2, and then
 783 terminate <code>GetOptions()</code> leaving <code>&quot;arg2&quot;</code> in <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__argv"><code>@ARGV</code></a>.</p>
 784 </dd>
 785 <dd>
 786 <p>If <a href="#item_require_order"><code>require_order</code></a> is enabled, options processing
 787 terminates when the first non-option is encountered.</p>
 788 </dd>
 789 <dd>
 790 <pre>
 791     --foo arg1 --bar arg2 arg3</pre>
 792 </dd>
 793 <dd>
 794 <p>is equivalent to</p>
 795 </dd>
 796 <dd>
 797 <pre>
 798     --foo -- arg1 --bar arg2 arg3</pre>
 799 </dd>
 800 <dd>
 801 <p>If <a href="#item_pass_through"><code>pass_through</code></a> is also enabled, options processing will terminate
 802 at the first unrecognized option, or non-option, whichever comes
 803 first.</p>
 804 </dd>
 805 </li>
 806 <dt><strong><a name="item_bundling">bundling (default: disabled)</a></strong>
 807
 808 <dd>
 809 <p>Enabling this option will allow single-character options to be
 810 bundled. To distinguish bundles from long option names, long options
 811 <em>must</em> be introduced with <code>--</code> and bundles with <code>-</code>.</p>
 812 </dd>
 813 <dd>
 814 <p>Note that, if you have options <code>a</code>, <code>l</code> and <code>all</code>, and
 815 auto_abbrev enabled, possible arguments and option settings are:</p>
 816 </dd>
 817 <dd>
 818 <pre>
 819     using argument               sets option(s)
 820     ------------------------------------------
 821     -a, --a                      a
 822     -l, --l                      l
 823     -al, -la, -ala, -all,...     a, l
 824     --al, --all                  all</pre>
 825 </dd>
 826 <dd>
 827 <p>The surprising part is that <code>--a</code> sets option <code>a</code> (due to auto
 828 completion), not <code>all</code>.</p>
 829 </dd>
 830 <dd>
 831 <p>Note: disabling <a href="#item_bundling"><code>bundling</code></a> also disables <a href="#item_bundling_override"><code>bundling_override</code></a>.</p>
 832 </dd>
 833 </li>
 834 <dt><strong><a name="item_bundling_override">bundling_override (default: disabled)</a></strong>
 835
 836 <dd>
 837 <p>If <a href="#item_bundling_override"><code>bundling_override</code></a> is enabled, bundling is enabled as with
 838 <a href="#item_bundling"><code>bundling</code></a> but now long option names override option bundles.</p>
 839 </dd>
 840 <dd>
 841 <p>Note: disabling <a href="#item_bundling_override"><code>bundling_override</code></a> also disables <a href="#item_bundling"><code>bundling</code></a>.</p>
 842 </dd>
 843 <dd>
 844 <p><strong>Note:</strong> Using option bundling can easily lead to unexpected results,
 845 especially when mixing long options and bundles. Caveat emptor.</p>
 846 </dd>
 847 </li>
 848 <dt><strong><a name="item_ignore_case">ignore_case  (default: enabled)</a></strong>
 849
 850 <dd>
 851 <p>If enabled, case is ignored when matching long option names. If,
 852 however, bundling is enabled as well, single character options will be
 853 treated case-sensitive.</p>
 854 </dd>
 855 <dd>
 856 <p>With <a href="#item_ignore_case"><code>ignore_case</code></a>, option specifications for options that only
 857 differ in case, e.g., <code>&quot;foo&quot;</code> and <code>&quot;Foo&quot;</code>, will be flagged as
 858 duplicates.</p>
 859 </dd>
 860 <dd>
 861 <p>Note: disabling <a href="#item_ignore_case"><code>ignore_case</code></a> also disables <a href="#item_ignore_case_always"><code>ignore_case_always</code></a>.</p>
 862 </dd>
 863 </li>
 864 <dt><strong><a name="item_ignore_case_always">ignore_case_always (default: disabled)</a></strong>
 865
 866 <dd>
 867 <p>When bundling is in effect, case is ignored on single-character
 868 options also.</p>
 869 </dd>
 870 <dd>
 871 <p>Note: disabling <a href="#item_ignore_case_always"><code>ignore_case_always</code></a> also disables <a href="#item_ignore_case"><code>ignore_case</code></a>.</p>
 872 </dd>
 873 </li>
 874 <dt><strong><a name="item_auto_version">auto_version (default:disabled)</a></strong>
 875
 876 <dd>
 877 <p>Automatically provide support for the <strong>--version</strong> option if
 878 the application did not specify a handler for this option itself.</p>
 879 </dd>
 880 <dd>
 881 <p>Getopt::Long will provide a standard version message that includes the
 882 program name, its version (if $main::VERSION is defined), and the
 883 versions of Getopt::Long and Perl. The message will be written to
 884 standard output and processing will terminate.</p>
 885 </dd>
 886 <dd>
 887 <p><a href="#item_auto_version"><code>auto_version</code></a> will be enabled if the calling program explicitly
 888 specified a version number higher than 2.32 in the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a> or
 889 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_require"><code>require</code></a> statement.</p>
 890 </dd>
 891 </li>
 892 <dt><strong><a name="item_auto_help">auto_help (default:disabled)</a></strong>
 893
 894 <dd>
 895 <p>Automatically provide support for the <strong>--help</strong> and <strong>-?</strong> options if
 896 the application did not specify a handler for this option itself.</p>
 897 </dd>
 898 <dd>
 899 <p>Getopt::Long will provide a help message using module <a href="file://C|\msysgit\mingw\html/lib/Pod/Usage.html">the Pod::Usage manpage</a>. The
 900 message, derived from the SYNOPSIS POD section, will be written to
 901 standard output and processing will terminate.</p>
 902 </dd>
 903 <dd>
 904 <p><a href="#item_auto_help"><code>auto_help</code></a> will be enabled if the calling program explicitly
 905 specified a version number higher than 2.32 in the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a> or
 906 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_require"><code>require</code></a> statement.</p>
 907 </dd>
 908 </li>
 909 <dt><strong><a name="item_pass_through">pass_through (default: disabled)</a></strong>
 910
 911 <dd>
 912 <p>Options that are unknown, ambiguous or supplied with an invalid option
 913 value are passed through in <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__argv"><code>@ARGV</code></a> instead of being flagged as
 914 errors. This makes it possible to write wrapper scripts that process
 915 only part of the user supplied command line arguments, and pass the
 916 remaining options to some other program.</p>
 917 </dd>
 918 <dd>
 919 <p>If <a href="#item_require_order"><code>require_order</code></a> is enabled, options processing will terminate at
 920 the first unrecognized option, or non-option, whichever comes first.
 921 However, if <a href="#item_permute"><code>permute</code></a> is enabled instead, results can become confusing.</p>
 922 </dd>
 923 <dd>
 924 <p>Note that the options terminator (default <code>--</code>), if present, will
 925 also be passed through in <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__argv"><code>@ARGV</code></a>.</p>
 926 </dd>
 927 </li>
 928 <dt><strong><a name="item_prefix">prefix</a></strong>
 929
 930 <dd>
 931 <p>The string that starts options. If a constant string is not
 932 sufficient, see <a href="#item_prefix_pattern"><code>prefix_pattern</code></a>.</p>
 933 </dd>
 934 </li>
 935 <dt><strong><a name="item_prefix_pattern">prefix_pattern</a></strong>
 936
 937 <dd>
 938 <p>A Perl pattern that identifies the strings that introduce options.
 939 Default is <code>--|-|\+</code> unless environment variable
 940 POSIXLY_CORRECT has been set, in which case it is <code>--|-</code>.</p>
 941 </dd>
 942 </li>
 943 <dt><strong><a name="item_long_prefix_pattern">long_prefix_pattern</a></strong>
 944
 945 <dd>
 946 <p>A Perl pattern that allows the disambiguation of long and short
 947 prefixes. Default is <code>--</code>.</p>
 948 </dd>
 949 <dd>
 950 <p>Typically you only need to set this if you are using nonstandard
 951 prefixes and want some or all of them to have the same semantics as
 952 '--' does under normal circumstances.</p>
 953 </dd>
 954 <dd>
 955 <p>For example, setting prefix_pattern to <code>--|-|\+|\/</code> and
 956 long_prefix_pattern to <code>--|\/</code> would add Win32 style argument
 957 handling.</p>
 958 </dd>
 959 </li>
 960 <dt><strong><a name="item_debug">debug (default: disabled)</a></strong>
 961
 962 <dd>
 963 <p>Enable debugging output.</p>
 964 </dd>
 965 </li>
 966 </dl>
 967 <p>
 968 </p>
 969 <hr />
 970 <h1><a name="exportable_methods">Exportable Methods</a></h1>
 971 <dl>
 972 <dt><strong><a name="item_versionmessage">VersionMessage</a></strong>
 973
 974 <dd>
 975 <p>This subroutine provides a standard version message. Its argument can be:</p>
 976 </dd>
 977 <ul>
 978 <li>
 979 <p>A string containing the text of a message to print <em>before</em> printing
 980 the standard message.</p>
 981 </li>
 982 <li>
 983 <p>A numeric value corresponding to the desired exit status.</p>
 984 </li>
 985 <li>
 986 <p>A reference to a hash.</p>
 987 </li>
 988 </ul>
 989 <p>If more than one argument is given then the entire argument list is
 990 assumed to be a hash.  If a hash is supplied (either as a reference or
 991 as a list) it should contain one or more elements with the following
 992 keys:</p>
 993 <dl>
 994 <dt><strong><a name="item__2dmessage"><code>-message</code></a></strong>
 995
 996 <dt><strong><a name="item__2dmsg"><code>-msg</code></a></strong>
 997
 998 <dd>
 999 <p>The text of a message to print immediately prior to printing the
1000 program's usage message.</p>
1001 </dd>
1002 </li>
1003 <dt><strong><a name="item__2dexitval"><code>-exitval</code></a></strong>
1004
1005 <dd>
1006 <p>The desired exit status to pass to the <strong>exit()</strong> function.
1007 This should be an integer, or else the string ``NOEXIT'' to
1008 indicate that control should simply be returned without
1009 terminating the invoking process.</p>
1010 </dd>
1011 </li>
1012 <dt><strong><a name="item__2doutput"><code>-output</code></a></strong>
1013
1014 <dd>
1015 <p>A reference to a filehandle, or the pathname of a file to which the
1016 usage message should be written. The default is <code>\*STDERR</code> unless the
1017 exit value is less than 2 (in which case the default is <code>\*STDOUT</code>).</p>
1018 </dd>
1019 </li>
1020 </dl>
1021 <p>You cannot tie this routine directly to an option, e.g.:</p>
1022 <pre>
1023     GetOptions(&quot;version&quot; =&gt; \&amp;VersionMessage);</pre>
1024 <p>Use this instead:</p>
1025 <pre>
1026     GetOptions(&quot;version&quot; =&gt; sub { VersionMessage() });</pre>
1027 <dt><strong><a name="item_helpmessage">HelpMessage</a></strong>
1028
1029 <dd>
1030 <p>This subroutine produces a standard help message, derived from the
1031 program's POD section SYNOPSIS using <a href="file://C|\msysgit\mingw\html/lib/Pod/Usage.html">the Pod::Usage manpage</a>. It takes the same
1032 arguments as VersionMessage(). In particular, you cannot tie it
1033 directly to an option, e.g.:</p>
1034 </dd>
1035 <dd>
1036 <pre>
1037     GetOptions(&quot;help&quot; =&gt; \&amp;HelpMessage);</pre>
1038 </dd>
1039 <dd>
1040 <p>Use this instead:</p>
1041 </dd>
1042 <dd>
1043 <pre>
1044     GetOptions(&quot;help&quot; =&gt; sub { HelpMessage() });</pre>
1045 </dd>
1046 </li>
1047 </dl>
1048 <p>
1049 </p>
1050 <hr />
1051 <h1><a name="return_values_and_errors">Return values and Errors</a></h1>
1052 <p>Configuration errors and errors in the option definitions are
1053 signalled using <code>die()</code> and will terminate the calling program unless
1054 the call to Getopt::Long::GetOptions() was embedded in <code>eval { ...
1055 }</code>, or <code>die()</code> was trapped using <code>$SIG{__DIE__}</code>.</p>
1056 <p>GetOptions returns true to indicate success.
1057 It returns false when the function detected one or more errors during
1058 option parsing. These errors are signalled using <code>warn()</code> and can be
1059 trapped with <code>$SIG{__WARN__}</code>.</p>
1060 <p>
1061 </p>
1062 <hr />
1063 <h1><a name="legacy">Legacy</a></h1>
1064 <p>The earliest development of <code>newgetopt.pl</code> started in 1990, with Perl
1065 version 4. As a result, its development, and the development of
1066 Getopt::Long, has gone through several stages. Since backward
1067 compatibility has always been extremely important, the current version
1068 of Getopt::Long still supports a lot of constructs that nowadays are
1069 no longer necessary or otherwise unwanted. This section describes
1070 briefly some of these 'features'.</p>
1071 <p>
1072 </p>
1073 <h2><a name="default_destinations">Default destinations</a></h2>
1074 <p>When no destination is specified for an option, GetOptions will store
1075 the resultant value in a global variable named <code>opt_</code><em>XXX</em>, where
1076 <em>XXX</em> is the primary name of this option. When a progam executes
1077 under <code>use strict</code> (recommended), these variables must be
1078 pre-declared with <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_our"><code>our()</code></a> or <code>use vars</code>.</p>
1079 <pre>
1080     our $opt_length = 0;
1081     GetOptions ('length=i');    # will store in $opt_length</pre>
1082 <p>To yield a usable Perl variable, characters that are not part of the
1083 syntax for variables are translated to underscores. For example,
1084 <code>--fpp-struct-return</code> will set the variable
1085 <code>$opt_fpp_struct_return</code>. Note that this variable resides in the
1086 namespace of the calling program, not necessarily <code>main</code>. For
1087 example:</p>
1088 <pre>
1089     GetOptions (&quot;size=i&quot;, &quot;sizes=i@&quot;);</pre>
1090 <p>with command line ``-size 10 -sizes 24 -sizes 48'' will perform the
1091 equivalent of the assignments</p>
1092 <pre>
1093     $opt_size = 10;
1094     @opt_sizes = (24, 48);</pre>
1095 <p>
1096 </p>
1097 <h2><a name="alternative_option_starters">Alternative option starters</a></h2>
1098 <p>A string of alternative option starter characters may be passed as the
1099 first argument (or the first argument after a leading hash reference
1100 argument).</p>
1101 <pre>
1102     my $len = 0;
1103     GetOptions ('/', 'length=i' =&gt; $len);</pre>
1104 <p>Now the command line may look like:</p>
1105 <pre>
1106     /length 24 -- arg</pre>
1107 <p>Note that to terminate options processing still requires a double dash
1108 <code>--</code>.</p>
1109 <p><code>GetOptions()</code> will not interpret a leading <code>&quot;&lt;&gt;&quot;</code> as option starters
1110 if the next argument is a reference. To force <code>&quot;&lt;&quot;</code> and <code>&quot;&gt;&quot;</code> as
1111 option starters, use <code>&quot;&gt;&lt;&quot;</code>. Confusing? Well, <strong>using a starter
1112 argument is strongly deprecated</strong> anyway.</p>
1113 <p>
1114 </p>
1115 <h2><a name="configuration_variables">Configuration variables</a></h2>
1116 <p>Previous versions of Getopt::Long used variables for the purpose of
1117 configuring. Although manipulating these variables still work, it is
1118 strongly encouraged to use the <code>Configure</code> routine that was introduced
1119 in version 2.17. Besides, it is much easier.</p>
1120 <p>
1121 </p>
1122 <hr />
1123 <h1><a name="trouble_shooting">Trouble Shooting</a></h1>
1124 <p>
1125 </p>
1126 <h2><a name="getoptions_does_not_return_a_false_result_when_an_option_is_not_supplied">GetOptions does not return a false result when an option is not supplied</a></h2>
1127 <p>That's why they're called 'options'.</p>
1128 <p>
1129 </p>
1130 <h2><a name="getoptions_does_not_split_the_command_line_correctly">GetOptions does not split the command line correctly</a></h2>
1131 <p>The command line is not split by GetOptions, but by the command line
1132 interpreter (CLI). On Unix, this is the shell. On Windows, it is
1133 COMMAND.COM or CMD.EXE. Other operating systems have other CLIs.</p>
1134 <p>It is important to know that these CLIs may behave different when the
1135 command line contains special characters, in particular quotes or
1136 backslashes. For example, with Unix shells you can use single quotes
1137 (<code>'</code>) and double quotes (<code>&quot;</code>) to group words together. The following
1138 alternatives are equivalent on Unix:</p>
1139 <pre>
1140     &quot;two words&quot;
1141     'two words'
1142     two\ words</pre>
1143 <p>In case of doubt, insert the following statement in front of your Perl
1144 program:</p>
1145 <pre>
1146     print STDERR (join(&quot;|&quot;,@ARGV),&quot;\n&quot;);</pre>
1147 <p>to verify how your CLI passes the arguments to the program.</p>
1148 <p>
1149 </p>
1150 <h2><a name="undefined_subroutine__main__getoptions_called">Undefined subroutine &amp;main::GetOptions called</a></h2>
1151 <p>Are you running Windows, and did you write</p>
1152 <pre>
1153     use GetOpt::Long;</pre>
1154 <p>(note the capital 'O')?</p>
1155 <p>
1156 </p>
1157 <h2><a name="how_do_i_put_a__option_into_a_getopt__long">How do I put a ``-?'' option into a Getopt::Long?</a></h2>
1158 <p>You can only obtain this using an alias, and Getopt::Long of at least
1159 version 2.13.</p>
1160 <pre>
1161     use Getopt::Long;
1162     GetOptions (&quot;help|?&quot;);    # -help and -? will both set $opt_help</pre>
1163 <p>
1164 </p>
1165 <hr />
1166 <h1><a name="author">AUTHOR</a></h1>
1167 <p>Johan Vromans &lt;<a href="mailto:jvromans@squirrel.nl">jvromans@squirrel.nl</a>&gt;</p>
1168 <p>
1169 </p>
1170 <hr />
1171 <h1><a name="copyright_and_disclaimer">COPYRIGHT AND DISCLAIMER</a></h1>
1172 <p>This program is Copyright 1990,2005 by Johan Vromans.
1173 This program is free software; you can redistribute it and/or
1174 modify it under the terms of the Perl Artistic License or the
1175 GNU General Public License as published by the Free Software
1176 Foundation; either version 2 of the License, or (at your option) any
1177 later version.</p>
1178 <p>This program is distributed in the hope that it will be useful,
1179 but WITHOUT ANY WARRANTY; without even the implied warranty of
1180 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
1181 GNU General Public License for more details.</p>
1182 <p>If you do not have a copy of the GNU General Public License write to
1183 the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
1184 MA 02139, USA.</p>
1185 <table border="0" width="100%" cellspacing="0" cellpadding="3">
1186 <tr><td class="block" style="background-color: #cccccc" valign="middle">
1187 <big><strong><span class="block">&nbsp;Getopt::Long - Extended processing of command line options</span></strong></big>
1188 </td></tr>
1189 </table>
1190
1191 </body>
1192
1193 </html>