long.html

来自「perl教程」· HTML 代码 · 共 1,141 行 · 第 1/5 页

program name, its version (if $main::VERSION is defined), and the
versions of Getopt::Long and Perl. The message will be written to
standard output and processing will terminate.</p>
</dd>
<dd>
<p><a href="#item_auto_version"><code>auto_version</code></a> will be enabled if the calling program explicitly
specified a version number higher than 2.32 in the <a href="../../lib/Pod/perlfunc.html#item_use"><code>use</code></a> or
<a href="../../lib/Pod/perlfunc.html#item_require"><code>require</code></a> statement.</p>
</dd>
</li>
<dt><strong><a name="item_auto_help">auto_help (default:disabled)</a></strong>

<dd>
<p>Automatically provide support for the <strong>--help</strong> and <strong>-?</strong> options if
the application did not specify a handler for this option itself.</p>
</dd>
<dd>
<p>Getopt::Long will provide a help message using module <a href="../../lib/Pod/Usage.html">the Pod::Usage manpage</a>. The
message, derived from the SYNOPSIS POD section, will be written to
standard output and processing will terminate.</p>
</dd>
<dd>
<p><a href="#item_auto_help"><code>auto_help</code></a> will be enabled if the calling program explicitly
specified a version number higher than 2.32 in the <a href="../../lib/Pod/perlfunc.html#item_use"><code>use</code></a> or
<a href="../../lib/Pod/perlfunc.html#item_require"><code>require</code></a> statement.</p>
</dd>
</li>
<dt><strong><a name="item_pass_through">pass_through (default: disabled)</a></strong>

<dd>
<p>Options that are unknown, ambiguous or supplied with an invalid option
value are passed through in <a href="../../lib/Pod/perlvar.html#item__argv"><code>@ARGV</code></a> instead of being flagged as
errors. This makes it possible to write wrapper scripts that process
only part of the user supplied command line arguments, and pass the
remaining options to some other program.</p>
</dd>
<dd>
<p>If <a href="#item_require_order"><code>require_order</code></a> is enabled, options processing will terminate at
the first unrecognized option, or non-option, whichever comes first.
However, if <a href="#item_permute"><code>permute</code></a> is enabled instead, results can become confusing.</p>
</dd>
<dd>
<p>Note that the options terminator (default <code>--</code>), if present, will
also be passed through in <a href="../../lib/Pod/perlvar.html#item__argv"><code>@ARGV</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_prefix">prefix</a></strong>

<dd>
<p>The string that starts options. If a constant string is not
sufficient, see <a href="#item_prefix_pattern"><code>prefix_pattern</code></a>.</p>
</dd>
</li>
<dt><strong><a name="item_prefix_pattern">prefix_pattern</a></strong>

<dd>
<p>A Perl pattern that identifies the strings that introduce options.
Default is <code>--|-|\+</code> unless environment variable
POSIXLY_CORRECT has been set, in which case it is <code>--|-</code>.</p>
</dd>
</li>
<dt><strong><a name="item_long_prefix_pattern">long_prefix_pattern</a></strong>

<dd>
<p>A Perl pattern that allows the disambiguation of long and short
prefixes. Default is <code>--</code>.</p>
</dd>
<dd>
<p>Typically you only need to set this if you are using nonstandard
prefixes and want some or all of them to have the same semantics as
'--' does under normal circumstances.</p>
</dd>
<dd>
<p>For example, setting prefix_pattern to <code>--|-|\+|\/</code> and
long_prefix_pattern to <code>--|\/</code> would add Win32 style argument
handling.</p>
</dd>
</li>
<dt><strong><a name="item_debug">debug (default: disabled)</a></strong>

<dd>
<p>Enable debugging output.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="exportable_methods">Exportable Methods</a></h1>
<dl>
<dt><strong><a name="item_versionmessage">VersionMessage</a></strong>

<dd>
<p>This subroutine provides a standard version message. Its argument can be:</p>
</dd>
<ul>
<li>
<p>A string containing the text of a message to print <em>before</em> printing
the standard message.</p>
</li>
<li>
<p>A numeric value corresponding to the desired exit status.</p>
</li>
<li>
<p>A reference to a hash.</p>
</li>
</ul>
<p>If more than one argument is given then the entire argument list is
assumed to be a hash.  If a hash is supplied (either as a reference or
as a list) it should contain one or more elements with the following
keys:</p>
<dl>
<dt><strong><a name="item__2dmessage"><code>-message</code></a></strong>

<dt><strong><a name="item__2dmsg"><code>-msg</code></a></strong>

<dd>
<p>The text of a message to print immediately prior to printing the
program's usage message.</p>
</dd>
</li>
<dt><strong><a name="item__2dexitval"><code>-exitval</code></a></strong>

<dd>
<p>The desired exit status to pass to the <strong>exit()</strong> function.
This should be an integer, or else the string &quot;NOEXIT&quot; to
indicate that control should simply be returned without
terminating the invoking process.</p>
</dd>
</li>
<dt><strong><a name="item__2doutput"><code>-output</code></a></strong>

<dd>
<p>A reference to a filehandle, or the pathname of a file to which the
usage message should be written. The default is <code>\*STDERR</code> unless the
exit value is less than 2 (in which case the default is <code>\*STDOUT</code>).</p>
</dd>
</li>
</dl>
<p>You cannot tie this routine directly to an option, e.g.:</p>
<pre>
    <span class="variable">GetOptions</span><span class="operator">(</span><span class="string">"version"</span> <span class="operator">=&gt;</span> <span class="operator">\&amp;</span><span class="variable">VersionMessage</span><span class="operator">);</span>
</pre>
<p>Use this instead:</p>
<pre>
    <span class="variable">GetOptions</span><span class="operator">(</span><span class="string">"version"</span> <span class="operator">=&gt;</span> <span class="keyword">sub</span><span class="variable"> </span><span class="operator">{</span> <span class="variable">VersionMessage</span><span class="operator">()</span> <span class="operator">});</span>
</pre>
<dt><strong><a name="item_helpmessage">HelpMessage</a></strong>

<dd>
<p>This subroutine produces a standard help message, derived from the
program's POD section SYNOPSIS using <a href="../../lib/Pod/Usage.html">the Pod::Usage manpage</a>. It takes the same
arguments as VersionMessage(). In particular, you cannot tie it
directly to an option, e.g.:</p>
</dd>
<dd>
<pre>
    <span class="variable">GetOptions</span><span class="operator">(</span><span class="string">"help"</span> <span class="operator">=&gt;</span> <span class="operator">\&amp;</span><span class="variable">HelpMessage</span><span class="operator">);</span>
</pre>
</dd>
<dd>
<p>Use this instead:</p>
</dd>
<dd>
<pre>
    <span class="variable">GetOptions</span><span class="operator">(</span><span class="string">"help"</span> <span class="operator">=&gt;</span> <span class="keyword">sub</span><span class="variable"> </span><span class="operator">{</span> <span class="variable">HelpMessage</span><span class="operator">()</span> <span class="operator">});</span>
</pre>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="return_values_and_errors">Return values and Errors</a></h1>
<p>Configuration errors and errors in the option definitions are
signalled using <a href="../../lib/Pod/perlfunc.html#item_die"><code>die()</code></a> and will terminate the calling program unless
the call to Getopt::Long::GetOptions() was embedded in <code>eval { ...
}</code>, or <a href="../../lib/Pod/perlfunc.html#item_die"><code>die()</code></a> was trapped using <code>$SIG{__DIE__}</code>.</p>
<p>GetOptions returns true to indicate success.
It returns false when the function detected one or more errors during
option parsing. These errors are signalled using <a href="../../lib/Pod/perlfunc.html#item_warn"><code>warn()</code></a> and can be
trapped with <code>$SIG{__WARN__}</code>.</p>
<p>
</p>
<hr />
<h1><a name="legacy">Legacy</a></h1>
<p>The earliest development of <code>newgetopt.pl</code> started in 1990, with Perl
version 4. As a result, its development, and the development of
Getopt::Long, has gone through several stages. Since backward
compatibility has always been extremely important, the current version
of Getopt::Long still supports a lot of constructs that nowadays are
no longer necessary or otherwise unwanted. This section describes
briefly some of these 'features'.</p>
<p>
</p>
<h2><a name="default_destinations">Default destinations</a></h2>
<p>When no destination is specified for an option, GetOptions will store
the resultant value in a global variable named <code>opt_</code><em>XXX</em>, where
<em>XXX</em> is the primary name of this option. When a progam executes
under <code>use strict</code> (recommended), these variables must be
pre-declared with <a href="../../lib/Pod/perlfunc.html#item_our"><code>our()</code></a> or <code>use vars</code>.</p>
<pre>
    <span class="keyword">our</span> <span class="variable">$opt_length</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>
    <span class="variable">GetOptions</span> <span class="operator">(</span><span class="string">'length=i'</span><span class="operator">);</span>    <span class="comment"># will store in $opt_length</span>
</pre>
<p>To yield a usable Perl variable, characters that are not part of the
syntax for variables are translated to underscores. For example,
<code>--fpp-struct-return</code> will set the variable
<code>$opt_fpp_struct_return</code>. Note that this variable resides in the
namespace of the calling program, not necessarily <code>main</code>. For
example:</p>
<pre>
    <span class="variable">GetOptions</span> <span class="operator">(</span><span class="string">"size=i"</span><span class="operator">,</span> <span class="string">"sizes=i@"</span><span class="operator">);</span>
</pre>
<p>with command line &quot;-size 10 -sizes 24 -sizes 48&quot; will perform the
equivalent of the assignments</p>
<pre>
    <span class="variable">$opt_size</span> <span class="operator">=</span> <span class="number">10</span><span class="operator">;</span>
    <span class="variable">@opt_sizes</span> <span class="operator">=</span> <span class="operator">(</span><span class="number">24</span><span class="operator">,</span> <span class="number">48</span><span class="operator">);</span>
</pre>
<p>
</p>
<h2><a name="alternative_option_starters">Alternative option starters</a></h2>
<p>A string of alternative option starter characters may be passed as the
first argument (or the first argument afte