long.html

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

<dd>
<p>Real number. For example <code>3.14</code>, <code>-6.23E24</code> and so on.</p>
</dd>
</li>
</dl>
<p>The <em>desttype</em> can be <code>@</code> or <code>%</code> to specify that the option is
list or a hash valued. This is only needed when the destination for
the option value is not otherwise specified. It should be omitted when
not needed.</p>
<p>The <em>repeat</em> specifies the number of values this option takes per
occurrence on the command line. It has the format <code>{</code> [ <em>min</em> ] [ <code>,</code> [ <em>max</em> ] ] <code>}</code>.</p>
<p><em>min</em> denotes the minimal number of arguments. It defaults to 1 for
options with <code>=</code> and to 0 for options with <code>:</code>, see below. Note that
<em>min</em> overrules the <code>=</code> / <code>:</code> semantics.</p>
<p><em>max</em> denotes the maximum number of arguments. It must be at least
<em>min</em>. If <em>max</em> is omitted, <em>but the comma is not</em>, there is no
upper bound to the number of argument values taken.</p>
<dt><strong><a name="item__3a_type__5b_desttype__5d">: <em>type</em> [ <em>desttype</em> ]</a></strong>

<dd>
<p>Like <code>=</code>, but designates the argument as optional.
If omitted, an empty string will be assigned to string values options,
and the value zero to numeric options.</p>
</dd>
<dd>
<p>Note that if a string argument starts with <code>-</code> or <code>--</code>, it will be
considered an option on itself.</p>
</dd>
</li>
<dt><strong><a name="item__3a_number__5b_desttype__5d">: <em>number</em> [ <em>desttype</em> ]</a></strong>

<dd>
<p>Like <code>:i</code>, but if the value is omitted, the <em>number</em> will be assigned.</p>
</dd>
</li>
<dt><strong><a name="item__3a__2b__5b_desttype__5d">: + [ <em>desttype</em> ]</a></strong>

<dd>
<p>Like <code>:i</code>, but if the value is omitted, the current value for the
option will be incremented.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="advanced_possibilities">Advanced Possibilities</a></h1>
<p>
</p>
<h2><a name="object_oriented_interface">Object oriented interface</a></h2>
<p>Getopt::Long can be used in an object oriented way as well:</p>
<pre>
    <span class="keyword">use</span> <span class="variable">Getopt::Long</span><span class="operator">;</span>
    <span class="variable">$p</span> <span class="operator">=</span> <span class="variable">new</span> <span class="variable">Getopt::Long::Parser</span><span class="operator">;</span>
    <span class="variable">$p</span><span class="operator">-&gt;</span><span class="variable">configure</span><span class="operator">(...</span><span class="variable">configuration</span> <span class="variable">options</span><span class="operator">...);</span>
    <span class="keyword">if</span> <span class="operator">(</span><span class="variable">$p</span><span class="operator">-&gt;</span><span class="variable">getoptions</span><span class="operator">(...</span><span class="variable">options</span> <span class="variable">descriptions</span><span class="operator">...))</span> <span class="operator">...</span>
</pre>
<p>Configuration options can be passed to the constructor:</p>
<pre>
    <span class="variable">$p</span> <span class="operator">=</span> <span class="variable">new</span> <span class="variable">Getopt::Long::Parser</span>
             <span class="string">config</span> <span class="operator">=&gt;</span> <span class="operator">[</span><span class="operator">...</span><span class="variable">configuration</span> <span class="variable">options</span><span class="operator">...</span><span class="operator">]</span><span class="operator">;</span>
</pre>
<p>
</p>
<h2><a name="thread_safety">Thread Safety</a></h2>
<p>Getopt::Long is thread safe when using ithreads as of Perl 5.8.  It is
<em>not</em> thread safe when using the older (experimental and now
obsolete) threads implementation that was added to Perl 5.005.</p>
<p>
</p>
<h2><a name="documentation_and_help_texts">Documentation and help texts</a></h2>
<p>Getopt::Long encourages the use of Pod::Usage to produce help
messages. For example:</p>
<pre>
    <span class="keyword">use</span> <span class="variable">Getopt::Long</span><span class="operator">;</span>
    <span class="keyword">use</span> <span class="variable">Pod::Usage</span><span class="operator">;</span>
</pre>
<pre>
    <span class="keyword">my</span> <span class="variable">$man</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>
    <span class="keyword">my</span> <span class="variable">$help</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>
</pre>
<pre>
    <span class="variable">GetOptions</span><span class="operator">(</span><span class="string">'help|?'</span> <span class="operator">=&gt;</span> <span class="operator">\</span><span class="variable">$help</span><span class="operator">,</span> <span class="string">man</span> <span class="operator">=&gt;</span> <span class="operator">\</span><span class="variable">$man</span><span class="operator">)</span> <span class="keyword">or</span> <span class="variable">pod2usage</span><span class="operator">(</span><span class="number">2</span><span class="operator">);</span>
    <span class="variable">pod2usage</span><span class="operator">(</span><span class="number">1</span><span class="operator">)</span> <span class="keyword">if</span> <span class="variable">$help</span><span class="operator">;</span>
    <span class="variable">pod2usage</span><span class="operator">(</span><span class="string">-exitstatus</span> <span class="operator">=&gt;</span> <span class="number">0</span><span class="operator">,</span> <span class="string">-verbose</span> <span class="operator">=&gt;</span> <span class="number">2</span><span class="operator">)</span> <span class="keyword">if</span> <span class="variable">$man</span><span class="operator">;</span>
</pre>
<pre>
    __END__</pre>
<pre>
    =head1 NAME</pre>
<pre>
    sample - Using Getopt::Long and Pod::Usage</pre>
<pre>
    =head1 SYNOPSIS</pre>
<pre>
    sample [options] [file ...]</pre>
<pre>
     Options:
       -help            brief help message
       -man             full documentation</pre>
<pre>
    =head1 OPTIONS</pre>
<pre>
    =over 8</pre>
<pre>
    =item B&lt;-help&gt;</pre>
<pre>
    Print a brief help message and exits.</pre>
<pre>
    =item B&lt;-man&gt;</pre>
<pre>
    Prints the manual page and exits.</pre>
<pre>
    =back</pre>
<pre>
    =head1 DESCRIPTION</pre>
<pre>
    B&lt;This program&gt; will read the given input file(s) and do something
    useful with the contents thereof.</pre>
<pre>
    =cut</pre>
<p>See <a href="../../lib/Pod/Usage.html">the Pod::Usage manpage</a> for details.</p>
<p>
</p>
<h2><a name="storing_option_values_in_a_hash">Storing option values in a hash</a></h2>
<p>Sometimes, for example when there are a lot of options, having a
separate variable for each of them can be cumbersome. <code>GetOptions()</code>
supports, as an alternative mechanism, storing options in a hash.</p>
<p>To obtain this, a reference to a hash must be passed <em>as the first
argument</em> to GetOptions(). For each option that is specified on the
command line, the option value will be stored in the hash with the
option name as key. Options that are not actually used on the command
line will not be put in the hash, on other words,
<a href="../../lib/Pod/perlfunc.html#item_exists"><code>exists($h{option})</code></a> (or <a href="../../lib/Pod/perlfunc.html#item_defined"><code>defined())</code></a> can be used to test if an option
was used. The drawback is that warnings will be issued if the program
runs under <code>use strict</code> and uses <code>$h{option}</code> without testing with
<a href="../../lib/Pod/perlfunc.html#item_exists"><code>exists()</code></a> or <a href="../../lib/Pod/perlfunc.html#item_defined"><code>defined()</code></a> first.</p>
<pre>
    <span class="keyword">my</span> <span class="variable">%h</span> <span class="operator">=</span> <span class="operator">();</span>
    <span class="variable">GetOptions</span> <span class="operator">(\</span><span class="variable">%h</span><span class="operator">,</span> <span class="string">'length=i'</span><span class="operator">);</span>       <span class="comment"># will store in $h{length}</span>
</pre>
<p>For options that take list or hash values, it is necessary to indicate
this by appending an <code>@</code> or <code>%</code> sign after the type:</p>
<pre>
    <span class="variable">GetOptions</span> <span class="operator">(\</span><span class="variable">%h</span><span class="operator">,</span> <span class="string">'colours=s@'</span><span class="operator">);</span>     <span class="comment"># will push to @{$h{colours}}</span>
</pre>
<p>To make things more complicated, the hash may contain references to
the actual destinations, for example:</p>
<pre>
    <span class="keyword">my</span> <span class="variable">$len</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>
    <span class="keyword">my</span> <span class="variable">%h</span> <span class="operator">=</span> <span class="operator">(</span><span class="string">'length'</span> <span class="operator">=&gt;</span> <span class="operator">\</span><span class="variable">$len</span><span class="operator">);</span>
    <span class="variable">GetOptions</span> <span class="operator">(\</span><span class="variable">%h</span><span class="operator">,</span> <span class="string">'length=i'</span><span class="operator">);</span>       <span class="comment"># will store in $len</span>
</pre>
<p>This example is fully equivalent with:</p>
<pre>
    <span class="keyword">my</span> <span class="variable">$len</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">=&gt;</span> <span class="operator">\</span><span class="variable">$len</span><span class="operator">);</span>   <span class="comment"># will store in $len</span>
</pre>
<p>Any mixture is possible. For example, the most frequently used options
could be stored in variables while all other options get stored in the
hash:</p>
<pre>
    <span class="keyword">my</span> <span class="variable">$verbose</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>                    <span class="comment"># frequently referred</span>
    <span class="keyword">my</span> <span class="variable">$debug</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>                      <span class="comment"># frequently referred</span>
    <span class="keyword">my</span> <span class="variable">%h</span> <span class="operator">=</span> <span class="operator">(</span><span class="string">'verbose'</span> <span class="operator">=&gt;</span> <span class="operator">\</span><span class="variable">$verbose</span><span class="operator">,</span> <span class="string">'debug'</span> <span class="operator">=&gt;</span> <span class="operator">\</span><span class="variable">$debug</span><span class="operator">);</span>
    <span class="variable">GetOptions</span> <span class="operator">(\</span><span class="variable">%h</span><span class="operator">,</span> <span class="string">'verbose'</span><span class="operator">,</span> <span class="string">'debug'</span><span class="operator">,</span> <span class="string">'filter'</span><span class="operator">,</span> <span class="string">'size=i'</span><span class="operator">);</span>
    <span class="keyword">if</span> <span class="operator">(</span> <span class="variable">$verbose</span> <span class="operator">)</span> <span class="operator">{</span> <span class="operator">...</span> <span class="operator">}</span>
    <span class="keyword">if</span> <span class="operator">(</span> <span class="keyword">exists</span> <span class="variable">$h</span><span class="operator">{</span><span class="string">filter</span><span class="operator">}</span> <span class="operator">)</span> <span class="operator">{</span> <span class="operator">...</span> <span class="variable">option</span> <span class="string">'filter'</span> <span class="variable">was</span> <span class="variable">specified</span> <span class="operator">...</span> <span class="operator">}</span>
</pre>
<p>
</p>
<h2><a name="bundling">Bundling</a></h2>
<p>With bundling it is possible to set several single-character options
at once. For example if <code>a</code>, <code>v</code> and <a href="../../lib/Pod/perlguts.html#item_x"><code>x</code></a> are all valid options,</p>
<pre>
    -vax</pre>
<p>would set all three.</p>
<p>Getopt::Long supports two levels of bundling. To enable bundling, a
call to Getopt::Long::Configure is required.</p>
<p>The first level of bundling can be enabled with:</p>
<pre>
    <span class="variable">Getopt::Long::Configure</span> <span class="operator">(</span><span class="string">"bundling"</span><span class="operator">);</span>
</pre>
<p>Configured this way, single-character options can be bundled but long
options <strong>must</strong> always start with a double dash <code>--</code> to avoid
ambiguity. For example, when <code>vax</code>, <code>a</code>, <code>v</code> and <a href="../../lib/Pod/perlguts.html#item_x"><code>x</code></a> are all valid
options,</p>
<pre>
    -vax</pre>
<p>would set <code>a</code>, <code>v</code> and <a href="../../lib/Pod/perlguts.html#item_x"><code>x</code></a>, but</p>
<pre>
    --vax</pre>
<p>would set <code>vax</code>.</p>
<p>The second level of bundling lifts this restriction. It can be enabled
with:</p>
<pre>
    <span class="variable">Getopt::Long::Configure</span> <span class="operator">(</span><span class="string">"bundling_override"</span><span class="operator">);</span>
</pre>
<p>Now, <code>-vax</code> would set the option <code>vax</code>.</p>
<p>When any level of bundling is enabled, option values may be inserted
in the bundle. For example:</p>
<pre>
    -h24w80</pre>
<p>is equivalent to</p>
<pre>
    -h 24 -w 80</pre>
<p>When configured for bundling, single-character options are matched
case sensitive while long options are matched case insensitive. To
have the single-character options matched case insensitive as well,
use:</p>
<pre>
    <span class="variable">Getopt::Long::Configure</span> <span class="operator">(</span><span class="string">"bundling"</span><span class="operator">,</span> <span class="string">"ignorecase_always"</span><span class="operator">);</span>
</pre>
<p>It goes without saying that bundling can be quite confusing.</p>
<p>
</p>
<h2><a name="the_lonesome_dash">The lonesome dash</a></h2>
<p>Normally, a lone dash <code>-</code> on the command line will not be considered
an option. Option processing will terminate (unless &quot;permute&quot; is
configured) and the dash will be left in <a href="../../lib/Pod/perlvar.html#item__argv"><code>@ARGV</code></a>.</p>
<p>It is possible to get special treatment for a lone dash. This can be
achieved by adding an option specification with an empty name, for
example:</p>
<pre>
    <span class="variable">GetOptions</span> <span class="operator">(</span><span class="string">''</span> <span class="operator">=&gt;</span> <span class="operator">\</span><span class="variable">$stdio</span><span class="operator">);</span>
</pre>
<p>A lone dash on the command line will now be a legal option, and using
it will set variable <code>$stdio</code>.</p>