getopt::long.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.Vb 2
\&    use Getopt::Long qw(GetOptionsFromArray);
\&    $ret = GetOptionsFromArray(\e@myopts, ...);
.Ve
.PP
When used like this, the global \f(CW@ARGV\fR is not touched at all.
.PP
The following two calls behave identically:
.PP
.Vb 2
\&    $ret = GetOptions( ... );
\&    $ret = GetOptionsFromArray(\e@ARGV, ... );
.Ve
.Sh "Parsing options from an arbitrary string"
.IX Subsection "Parsing options from an arbitrary string"
A special entry \f(CW\*(C`GetOptionsFromString\*(C'\fR can be used to parse options
from an arbitrary string.
.PP
.Vb 2
\&    use Getopt::Long qw(GetOptionsFromString);
\&    $ret = GetOptionsFromString($string, ...);
.Ve
.PP
The contents of the string are split into arguments using a call to
\&\f(CW\*(C`Text::ParseWords::shellwords\*(C'\fR. As with \f(CW\*(C`GetOptionsFromArray\*(C'\fR, the
global \f(CW@ARGV\fR is not touched.
.PP
It is possible that, upon completion, not all arguments in the string
have been processed. \f(CW\*(C`GetOptionsFromString\*(C'\fR will, when called in list
context, return both the return status and an array reference to any
remaining arguments:
.PP
.Vb 1
\&    ($ret, $args) = GetOptionsFromString($string, ... );
.Ve
.PP
If any arguments remain, and \f(CW\*(C`GetOptionsFromString\*(C'\fR was not called in
list context, a message will be given and \f(CW\*(C`GetOptionsFromString\*(C'\fR will
return failure.
.Sh "Storing options values in a hash"
.IX Subsection "Storing options values in a hash"
Sometimes, for example when there are a lot of options, having a
separate variable for each of them can be cumbersome. \fIGetOptions()\fR
supports, as an alternative mechanism, storing options values in a
hash.
.PP
To obtain this, a reference to a hash must be passed \fIas the first
argument\fR to \fIGetOptions()\fR. 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,
\&\f(CW\*(C`exists($h{option})\*(C'\fR (or \fIdefined()\fR) can be used to test if an option
was used. The drawback is that warnings will be issued if the program
runs under \f(CW\*(C`use strict\*(C'\fR and uses \f(CW$h{option}\fR without testing with
\&\fIexists()\fR or \fIdefined()\fR first.
.PP
.Vb 2
\&    my %h = ();
\&    GetOptions (\e%h, \*(Aqlength=i\*(Aq);       # will store in $h{length}
.Ve
.PP
For options that take list or hash values, it is necessary to indicate
this by appending an \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR sign after the type:
.PP
.Vb 1
\&    GetOptions (\e%h, \*(Aqcolours=s@\*(Aq);     # will push to @{$h{colours}}
.Ve
.PP
To make things more complicated, the hash may contain references to
the actual destinations, for example:
.PP
.Vb 3
\&    my $len = 0;
\&    my %h = (\*(Aqlength\*(Aq => \e$len);
\&    GetOptions (\e%h, \*(Aqlength=i\*(Aq);       # will store in $len
.Ve
.PP
This example is fully equivalent with:
.PP
.Vb 2
\&    my $len = 0;
\&    GetOptions (\*(Aqlength=i\*(Aq => \e$len);   # will store in $len
.Ve
.PP
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:
.PP
.Vb 6
\&    my $verbose = 0;                    # frequently referred
\&    my $debug = 0;                      # frequently referred
\&    my %h = (\*(Aqverbose\*(Aq => \e$verbose, \*(Aqdebug\*(Aq => \e$debug);
\&    GetOptions (\e%h, \*(Aqverbose\*(Aq, \*(Aqdebug\*(Aq, \*(Aqfilter\*(Aq, \*(Aqsize=i\*(Aq);
\&    if ( $verbose ) { ... }
\&    if ( exists $h{filter} ) { ... option \*(Aqfilter\*(Aq was specified ... }
.Ve
.Sh "Bundling"
.IX Subsection "Bundling"
With bundling it is possible to set several single-character options
at once. For example if \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR are all valid options,
.PP
.Vb 1
\&    \-vax
.Ve
.PP
would set all three.
.PP
Getopt::Long supports two levels of bundling. To enable bundling, a
call to Getopt::Long::Configure is required.
.PP
The first level of bundling can be enabled with:
.PP
.Vb 1
\&    Getopt::Long::Configure ("bundling");
.Ve
.PP
Configured this way, single-character options can be bundled but long
options \fBmust\fR always start with a double dash \f(CW\*(C`\-\-\*(C'\fR to avoid
ambiguity. For example, when \f(CW\*(C`vax\*(C'\fR, \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR are all valid
options,
.PP
.Vb 1
\&    \-vax
.Ve
.PP
would set \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`v\*(C'\fR and \f(CW\*(C`x\*(C'\fR, but
.PP
.Vb 1
\&    \-\-vax
.Ve
.PP
would set \f(CW\*(C`vax\*(C'\fR.
.PP
The second level of bundling lifts this restriction. It can be enabled
with:
.PP
.Vb 1
\&    Getopt::Long::Configure ("bundling_override");
.Ve
.PP
Now, \f(CW\*(C`\-vax\*(C'\fR would set the option \f(CW\*(C`vax\*(C'\fR.
.PP
When any level of bundling is enabled, option values may be inserted
in the bundle. For example:
.PP
.Vb 1
\&    \-h24w80
.Ve
.PP
is equivalent to
.PP
.Vb 1
\&    \-h 24 \-w 80
.Ve
.PP
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:
.PP
.Vb 1
\&    Getopt::Long::Configure ("bundling", "ignorecase_always");
.Ve
.PP
It goes without saying that bundling can be quite confusing.
.Sh "The lonesome dash"
.IX Subsection "The lonesome dash"
Normally, a lone dash \f(CW\*(C`\-\*(C'\fR on the command line will not be considered
an option. Option processing will terminate (unless \*(L"permute\*(R" is
configured) and the dash will be left in \f(CW@ARGV\fR.
.PP
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:
.PP
.Vb 1
\&    GetOptions (\*(Aq\*(Aq => \e$stdio);
.Ve
.PP
A lone dash on the command line will now be a legal option, and using
it will set variable \f(CW$stdio\fR.
.Sh "Argument callback"
.IX Subsection "Argument callback"
A special option 'name' \f(CW\*(C`<>\*(C'\fR can be used to designate a subroutine
to handle non-option arguments. When \fIGetOptions()\fR encounters an
argument that does not look like an option, it will immediately call this
subroutine and passes it one parameter: the argument name.
.PP
For example:
.PP
.Vb 3
\&    my $width = 80;
\&    sub process { ... }
\&    GetOptions (\*(Aqwidth=i\*(Aq => \e$width, \*(Aq<>\*(Aq => \e&process);
.Ve
.PP
When applied to the following command line:
.PP
.Vb 1
\&    arg1 \-\-width=72 arg2 \-\-width=60 arg3
.Ve
.PP
This will call
\&\f(CW\*(C`process("arg1")\*(C'\fR while \f(CW$width\fR is \f(CW80\fR,
\&\f(CW\*(C`process("arg2")\*(C'\fR while \f(CW$width\fR is \f(CW72\fR, and
\&\f(CW\*(C`process("arg3")\*(C'\fR while \f(CW$width\fR is \f(CW60\fR.
.PP
This feature requires configuration option \fBpermute\fR, see section
\&\*(L"Configuring Getopt::Long\*(R".
.SH "Configuring Getopt::Long"
.IX Header "Configuring Getopt::Long"
Getopt::Long can be configured by calling subroutine
\&\fIGetopt::Long::Configure()\fR. This subroutine takes a list of quoted
strings, each specifying a configuration option to be enabled, e.g.
\&\f(CW\*(C`ignore_case\*(C'\fR, or disabled, e.g. \f(CW\*(C`no_ignore_case\*(C'\fR. Case does not
matter. Multiple calls to \fIConfigure()\fR are possible.
.PP
Alternatively, as of version 2.24, the configuration options may be
passed together with the \f(CW\*(C`use\*(C'\fR statement:
.PP
.Vb 1
\&    use Getopt::Long qw(:config no_ignore_case bundling);
.Ve
.PP
The following options are available:
.IP "default" 12
.IX Item "default"
This option causes all configuration options to be reset to their
default values.
.IP "posix_default" 12
.IX Item "posix_default"
This option causes all configuration options to be reset to their
default values as if the environment variable \s-1POSIXLY_CORRECT\s0 had
been set.
.IP "auto_abbrev" 12
.IX Item "auto_abbrev"
Allow option names to be abbreviated to uniqueness.
Default is enabled unless environment variable
\&\s-1POSIXLY_CORRECT\s0 has been set, in which case \f(CW\*(C`auto_abbrev\*(C'\fR is disabled.
.IP "getopt_compat" 12
.IX Item "getopt_compat"
Allow \f(CW\*(C`+\*(C'\fR to start options.
Default is enabled unless environment variable
\&\s-1POSIXLY_CORRECT\s0 has been set, in which case \f(CW\*(C`getopt_compat\*(C'\fR is disabled.
.IP "gnu_compat" 12
.IX Item "gnu_compat"
\&\f(CW\*(C`gnu_compat\*(C'\fR controls whether \f(CW\*(C`\-\-opt=\*(C'\fR is allowed, and what it should
do. Without \f(CW\*(C`gnu_compat\*(C'\fR, \f(CW\*(C`\-\-opt=\*(C'\fR gives an error. With \f(CW\*(C`gnu_compat\*(C'\fR,
\&\f(CW\*(C`\-\-opt=\*(C'\fR will give option \f(CW\*(C`opt\*(C'\fR and empty value.
This is the way \s-1GNU\s0 \fIgetopt_long()\fR does it.
.IP "gnu_getopt" 12
.IX Item "gnu_getopt"
This is a short way of setting \f(CW\*(C`gnu_compat\*(C'\fR \f(CW\*(C`bundling\*(C'\fR \f(CW\*(C`permute\*(C'\fR
\&\f(CW\*(C`no_getopt_compat\*(C'\fR. With \f(CW\*(C`gnu_getopt\*(C'\fR, command line handling should be
fully compatible with \s-1GNU\s0 \fIgetopt_long()\fR.
.IP "require_order" 12
.IX Item "require_order"
Whether command line arguments are allowed to be mixed with options.
Default is disabled unless environment variable
\&\s-1POSIXLY_CORRECT\s0 has been set, in which case \f(CW\*(C`require_order\*(C'\fR is enabled.
.Sp
See also \f(CW\*(C`permute\*(C'\fR, which is the opposite of \f(CW\*(C`require_order\*(C'\fR.
.IP "permute" 12
.IX Item "permute"
Whether command line arguments are allowed to be mixed with options.
Default is enabled unless environment variable
\&\s-1POSIXLY_CORRECT\s0 has been set, in which case \f(CW\*(C`permute\*(C'\fR is disabled.
Note that \f(CW\*(C`permute\*(C'\fR is the opposite of \f(CW\*(C`require_order\*(C'\fR.
.Sp
If \f(CW\*(C`permute\*(C'\fR is enabled, this means that
.Sp
.Vb 1
\&    \-\-foo arg1 \-\-bar arg2 arg3
.Ve
.Sp
is equivalent to
.Sp
.Vb 1
\&    \-\-foo \-\-bar arg1 arg2 arg3
.Ve
.Sp
If an argument callback routine is specified, \f(CW@ARGV\fR will always be
empty upon successful return of \fIGetOptions()\fR since all options have been
processed. The only exception is when \f(CW\*(C`\-\-\*(C'\fR is used:
.Sp
.Vb 1
\&    \-\-foo arg1 \-\-bar arg2 \-\- arg3
.Ve
.Sp
This will call the callback routine for arg1 and arg2, and then
terminate \fIGetOptions()\fR leaving \f(CW"arg3"\fR in \f(CW@ARGV\fR.
.Sp
If \f(CW\*(C`require_order\*(C'\fR is enabled, options processing
terminates when the first non-option is encountered.
.Sp
.Vb 1
\&    \-\-foo arg1 \-\-bar arg2 arg3
.Ve
.Sp
is equivalent to
.Sp
.Vb 1
\&    \-\-foo \-\- arg1 \-\-bar arg2 arg3
.Ve
.Sp
If \f(CW\*(C`pass_through\*(C'\fR is also enabled, options processing will terminate
at the first unrecognized option, or non-option, whichever comes
first.
.IP "bundling (default: disabled)" 12
.IX Item "bundling (default: disabled)"
Enabling this option will allow single-character options to be
bundled. To distinguish bundles from long option names, long options
\&\fImust\fR be introduced with \f(CW\*(C`\-\-\*(C'\fR and bundles with \f(CW\*(C`\-\*(C'\fR.
.Sp
Note that, if you have options \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`l\*(C'\fR and \f(CW\*(C`all\*(C'\fR, and
auto_abbrev enabled, possible arguments and option settings are:
.Sp
.Vb 6
\&    using argument               sets option(s)
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    \-a, \-\-a                      a
\&    \-l, \-\-l                      l
\&    \-al, \-la, \-ala, \-all,...     a, l
\&    \-\-al, \-\-all                  all
.Ve
.Sp
The surprising part is that \f(CW\*(C`\-\-a\*(C'\fR sets option \f(CW\*(C`a\*(C'\fR (due to auto
completion), not \f(CW\*(C`all\*(C'\fR.
.Sp
Note: disabling \f(CW\*(C`bundling\*(C'\fR also disables \f(CW\*(C`bundling_override\*(C'\fR.
.IP "bundling_override (default: disabled)" 12
.IX Item "bundling_override (default: disabled)"
If \f(CW\*(C`bundling_override\*(C'\fR is enabled, bundling is enabled as with
\&\f(CW\*(C`bundling\*(C'\fR but now long option names override option bundles.
.Sp
Note: disabling \f(CW\*(C`bundling_override\*(C'\fR also disables \f(CW\*(C`bundling\*(C'\fR.