getopt::long.3

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

.Sp
\&\fBNote:\fR Using option bundling can easily lead to unexpected results,
especially when mixing long options and bundles. Caveat emptor.
.IP "ignore_case  (default: enabled)" 12
.IX Item "ignore_case  (default: enabled)"
If enabled, case is ignored when matching long option names. If,
however, bundling is enabled as well, single character options will be
treated case-sensitive.
.Sp
With \f(CW\*(C`ignore_case\*(C'\fR, option specifications for options that only
differ in case, e.g., \f(CW"foo"\fR and \f(CW"Foo"\fR, will be flagged as
duplicates.
.Sp
Note: disabling \f(CW\*(C`ignore_case\*(C'\fR also disables \f(CW\*(C`ignore_case_always\*(C'\fR.
.IP "ignore_case_always (default: disabled)" 12
.IX Item "ignore_case_always (default: disabled)"
When bundling is in effect, case is ignored on single-character
options also.
.Sp
Note: disabling \f(CW\*(C`ignore_case_always\*(C'\fR also disables \f(CW\*(C`ignore_case\*(C'\fR.
.IP "auto_version (default:disabled)" 12
.IX Item "auto_version (default:disabled)"
Automatically provide support for the \fB\-\-version\fR option if
the application did not specify a handler for this option itself.
.Sp
Getopt::Long will provide a standard version message that includes the
program name, its version (if \f(CW$main::VERSION\fR is defined), and the
versions of Getopt::Long and Perl. The message will be written to
standard output and processing will terminate.
.Sp
\&\f(CW\*(C`auto_version\*(C'\fR will be enabled if the calling program explicitly
specified a version number higher than 2.32 in the \f(CW\*(C`use\*(C'\fR or
\&\f(CW\*(C`require\*(C'\fR statement.
.IP "auto_help (default:disabled)" 12
.IX Item "auto_help (default:disabled)"
Automatically provide support for the \fB\-\-help\fR and \fB\-?\fR options if
the application did not specify a handler for this option itself.
.Sp
Getopt::Long will provide a help message using module Pod::Usage. The
message, derived from the \s-1SYNOPSIS\s0 \s-1POD\s0 section, will be written to
standard output and processing will terminate.
.Sp
\&\f(CW\*(C`auto_help\*(C'\fR will be enabled if the calling program explicitly
specified a version number higher than 2.32 in the \f(CW\*(C`use\*(C'\fR or
\&\f(CW\*(C`require\*(C'\fR statement.
.IP "pass_through (default: disabled)" 12
.IX Item "pass_through (default: disabled)"
Options that are unknown, ambiguous or supplied with an invalid option
value are passed through in \f(CW@ARGV\fR 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.
.Sp
If \f(CW\*(C`require_order\*(C'\fR is enabled, options processing will terminate at
the first unrecognized option, or non-option, whichever comes first.
However, if \f(CW\*(C`permute\*(C'\fR is enabled instead, results can become confusing.
.Sp
Note that the options terminator (default \f(CW\*(C`\-\-\*(C'\fR), if present, will
also be passed through in \f(CW@ARGV\fR.
.IP "prefix" 12
.IX Item "prefix"
The string that starts options. If a constant string is not
sufficient, see \f(CW\*(C`prefix_pattern\*(C'\fR.
.IP "prefix_pattern" 12
.IX Item "prefix_pattern"
A Perl pattern that identifies the strings that introduce options.
Default is \f(CW\*(C`\-\-|\-|\e+\*(C'\fR unless environment variable
\&\s-1POSIXLY_CORRECT\s0 has been set, in which case it is \f(CW\*(C`\-\-|\-\*(C'\fR.
.IP "long_prefix_pattern" 12
.IX Item "long_prefix_pattern"
A Perl pattern that allows the disambiguation of long and short
prefixes. Default is \f(CW\*(C`\-\-\*(C'\fR.
.Sp
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.
.Sp
For example, setting prefix_pattern to \f(CW\*(C`\-\-|\-|\e+|\e/\*(C'\fR and
long_prefix_pattern to \f(CW\*(C`\-\-|\e/\*(C'\fR would add Win32 style argument
handling.
.IP "debug (default: disabled)" 12
.IX Item "debug (default: disabled)"
Enable debugging output.
.SH "Exportable Methods"
.IX Header "Exportable Methods"
.IP "VersionMessage" 4
.IX Item "VersionMessage"
This subroutine provides a standard version message. Its argument can be:
.RS 4
.IP "\(bu" 4
A string containing the text of a message to print \fIbefore\fR printing
the standard message.
.IP "\(bu" 4
A numeric value corresponding to the desired exit status.
.IP "\(bu" 4
A reference to a hash.
.RE
.RS 4
.Sp
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:
.ie n .IP """\-message""" 4
.el .IP "\f(CW\-message\fR" 4
.IX Item "-message"
.PD 0
.ie n .IP """\-msg""" 4
.el .IP "\f(CW\-msg\fR" 4
.IX Item "-msg"
.PD
The text of a message to print immediately prior to printing the
program's usage message.
.ie n .IP """\-exitval""" 4
.el .IP "\f(CW\-exitval\fR" 4
.IX Item "-exitval"
The desired exit status to pass to the \fB\f(BIexit()\fB\fR function.
This should be an integer, or else the string \*(L"\s-1NOEXIT\s0\*(R" to
indicate that control should simply be returned without
terminating the invoking process.
.ie n .IP """\-output""" 4
.el .IP "\f(CW\-output\fR" 4
.IX Item "-output"
A reference to a filehandle, or the pathname of a file to which the
usage message should be written. The default is \f(CW\*(C`\e*STDERR\*(C'\fR unless the
exit value is less than 2 (in which case the default is \f(CW\*(C`\e*STDOUT\*(C'\fR).
.RE
.RS 4
.Sp
You cannot tie this routine directly to an option, e.g.:
.Sp
.Vb 1
\&    GetOptions("version" => \e&VersionMessage);
.Ve
.Sp
Use this instead:
.Sp
.Vb 1
\&    GetOptions("version" => sub { VersionMessage() });
.Ve
.RE
.IP "HelpMessage" 4
.IX Item "HelpMessage"
This subroutine produces a standard help message, derived from the
program's \s-1POD\s0 section \s-1SYNOPSIS\s0 using Pod::Usage. It takes the same
arguments as \fIVersionMessage()\fR. In particular, you cannot tie it
directly to an option, e.g.:
.Sp
.Vb 1
\&    GetOptions("help" => \e&HelpMessage);
.Ve
.Sp
Use this instead:
.Sp
.Vb 1
\&    GetOptions("help" => sub { HelpMessage() });
.Ve
.SH "Return values and Errors"
.IX Header "Return values and Errors"
Configuration errors and errors in the option definitions are
signalled using \fIdie()\fR and will terminate the calling program unless
the call to \fIGetopt::Long::GetOptions()\fR was embedded in \f(CW\*(C`eval { ...
}\*(C'\fR, or \fIdie()\fR was trapped using \f(CW$SIG{_\|_DIE_\|_}\fR.
.PP
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 \fIwarn()\fR and can be
trapped with \f(CW$SIG{_\|_WARN_\|_}\fR.
.SH "Legacy"
.IX Header "Legacy"
The earliest development of \f(CW\*(C`newgetopt.pl\*(C'\fR 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'.
.Sh "Default destinations"
.IX Subsection "Default destinations"
When no destination is specified for an option, GetOptions will store
the resultant value in a global variable named \f(CW\*(C`opt_\*(C'\fR\fI\s-1XXX\s0\fR, where
\&\fI\s-1XXX\s0\fR is the primary name of this option. When a progam executes
under \f(CW\*(C`use strict\*(C'\fR (recommended), these variables must be
pre-declared with \fIour()\fR or \f(CW\*(C`use vars\*(C'\fR.
.PP
.Vb 2
\&    our $opt_length = 0;
\&    GetOptions (\*(Aqlength=i\*(Aq);    # will store in $opt_length
.Ve
.PP
To yield a usable Perl variable, characters that are not part of the
syntax for variables are translated to underscores. For example,
\&\f(CW\*(C`\-\-fpp\-struct\-return\*(C'\fR will set the variable
\&\f(CW$opt_fpp_struct_return\fR. Note that this variable resides in the
namespace of the calling program, not necessarily \f(CW\*(C`main\*(C'\fR. For
example:
.PP
.Vb 1
\&    GetOptions ("size=i", "sizes=i@");
.Ve
.PP
with command line \*(L"\-size 10 \-sizes 24 \-sizes 48\*(R" will perform the
equivalent of the assignments
.PP
.Vb 2
\&    $opt_size = 10;
\&    @opt_sizes = (24, 48);
.Ve
.Sh "Alternative option starters"
.IX Subsection "Alternative option starters"
A string of alternative option starter characters may be passed as the
first argument (or the first argument after a leading hash reference
argument).
.PP
.Vb 2
\&    my $len = 0;
\&    GetOptions (\*(Aq/\*(Aq, \*(Aqlength=i\*(Aq => $len);
.Ve
.PP
Now the command line may look like:
.PP
.Vb 1
\&    /length 24 \-\- arg
.Ve
.PP
Note that to terminate options processing still requires a double dash
\&\f(CW\*(C`\-\-\*(C'\fR.
.PP
\&\fIGetOptions()\fR will not interpret a leading \f(CW"<>"\fR as option starters
if the next argument is a reference. To force \f(CW"<"\fR and \f(CW">"\fR as
option starters, use \f(CW"><"\fR. Confusing? Well, \fBusing a starter
argument is strongly deprecated\fR anyway.
.Sh "Configuration variables"
.IX Subsection "Configuration variables"
Previous versions of Getopt::Long used variables for the purpose of
configuring. Although manipulating these variables still work, it is
strongly encouraged to use the \f(CW\*(C`Configure\*(C'\fR routine that was introduced
in version 2.17. Besides, it is much easier.
.SH "Tips and Techniques"
.IX Header "Tips and Techniques"
.Sh "Pushing multiple values in a hash option"
.IX Subsection "Pushing multiple values in a hash option"
Sometimes you want to combine the best of hashes and arrays. For
example, the command line:
.PP
.Vb 1
\&  \-\-list add=first \-\-list add=second \-\-list add=third
.Ve
.PP
where each successive 'list add' option will push the value of add
into array ref \f(CW$list\fR\->{'add'}. The result would be like
.PP
.Vb 1
\&  $list\->{add} = [qw(first second third)];
.Ve
.PP
This can be accomplished with a destination routine:
.PP
.Vb 2
\&  GetOptions(\*(Aqlist=s%\*(Aq =>
\&               sub { push(@{$list{$_[1]}}, $_[2]) });
.Ve
.SH "Trouble Shooting"
.IX Header "Trouble Shooting"
.Sh "GetOptions does not return a false result when an option is not supplied"
.IX Subsection "GetOptions does not return a false result when an option is not supplied"
That's why they're called 'options'.
.Sh "GetOptions does not split the command line correctly"
.IX Subsection "GetOptions does not split the command line correctly"
The command line is not split by GetOptions, but by the command line
interpreter (\s-1CLI\s0). On Unix, this is the shell. On Windows, it is
\&\s-1COMMAND\s0.COM or \s-1CMD\s0.EXE. Other operating systems have other CLIs.
.PP
It is important to know that these CLIs may behave different when the
command line contains special characters, in particular quotes or
backslashes. For example, with Unix shells you can use single quotes
(\f(CW\*(C`\*(Aq\*(C'\fR) and double quotes (\f(CW\*(C`"\*(C'\fR) to group words together. The following
alternatives are equivalent on Unix:
.PP
.Vb 3
\&    "two words"
\&    \*(Aqtwo words\*(Aq
\&    two\e words
.Ve
.PP
In case of doubt, insert the following statement in front of your Perl
program:
.PP
.Vb 1
\&    print STDERR (join("|",@ARGV),"\en");
.Ve
.PP
to verify how your \s-1CLI\s0 passes the arguments to the program.
.Sh "Undefined subroutine &main::GetOptions called"
.IX Subsection "Undefined subroutine &main::GetOptions called"
Are you running Windows, and did you write
.PP
.Vb 1
\&    use GetOpt::Long;
.Ve
.PP
(note the capital 'O')?
.ie n .Sh "How do I put a ""\-?"" option into a Getopt::Long?"
.el .Sh "How do I put a ``\-?'' option into a Getopt::Long?"
.IX Subsection "How do I put a -? option into a Getopt::Long?"
You can only obtain this using an alias, and Getopt::Long of at least
version 2.13.
.PP
.Vb 2
\&    use Getopt::Long;
\&    GetOptions ("help|?");    # \-help and \-? will both set $opt_help
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Johan Vromans <[e-mail]>
.SH "COPYRIGHT AND DISCLAIMER"
.IX Header "COPYRIGHT AND DISCLAIMER"
This program is Copyright 1990,2007 by Johan Vromans.
This program is free software; you can redistribute it and/or
modify it under the terms of the Perl Artistic License or the
\&\s-1GNU\s0 General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any
later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
If you do not have a copy of the \s-1GNU\s0 General Public License write to
the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
\&\s-1MA\s0 02139, \s-1USA\s0.