The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

Long (3)
  • >> Long (3) ( Solaris man: Библиотечные вызовы )
  • 
    
    

    NAME

         GetOptions - extended processing of command line options
    
    
    

    SYNOPSIS

           use Getopt::Long;
           $result = GetOptions (...option-descriptions...);
    
    
    
    

    DESCRIPTION

         The Getopt::Long module implements an extended getopt
         function called GetOptions(). This function adheres to the
         POSIX syntax for command line options, with GNU extensions.
         In general, this means that options have long names instead
         of single letters, and are introduced with a double dash "-
         -". Support for bundling of command line options, as was the
         case with the more traditional single-letter approach, is
         provided but not enabled by default. For example, the UNIX
         "ps" command can be given the command line "option"
    
           -vax
    
         which means the combination of -v, -a and -x. With the new
         syntax --vax would be a single option, probably indicating a
         computer architecture.
    
         Command line options can be used to set values. These values
         can be specified in one of two ways:
    
           --size 24
           --size=24
    
         GetOptions is called with a list of option-descriptions,
         each of which consists of two elements: the option specifier
         and the option linkage.  The option specifier defines the
         name of the option and, optionally, the value it can take.
         The option linkage is usually a reference to a variable that
         will be set when the option is used. For example, the
         following call to GetOptions:
    
           GetOptions("size=i" => \$offset);
    
         will accept a command line option "size" that must have an
         integer value. With a command line of "--size 24" this will
         cause the variable $offset to get the value 24.
    
         Alternatively, the first argument to GetOptions may be a
         reference to a HASH describing the linkage for the options,
         or an object whose class is based on a HASH. The following
         call is equivalent to the example above:
    
           %optctl = ("size" => \$offset);
           GetOptions(\%optctl, "size=i");
    
         Linkage may be specified using either of the above methods,
         or both.  Linkage specified in the argument list takes
         precedence over the linkage specified in the HASH.
    
         The command line options are taken from array @ARGV. Upon
         completion of GetOptions, @ARGV will contain the rest (i.e.
         the non-options) of the command line.
    
         Each option specifier designates the name of the option,
         optionally followed by an argument specifier.
    
         Options that do not take arguments will have no argument
         specifier. The option variable will be set to 1 if the
         option is used.
    
         For the other options, the values for argument specifiers
         are:
    
         !       Option does not take an argument and may be negated,
                 i.e. prefixed by "no". E.g. "foo!" will allow --foo
                 (with value 1) and -nofoo (with value 0).  The
                 option variable will be set to 1, or 0 if negated.
    
         +       Option does not take an argument and will be
                 incremented by 1 every time it appears on the
                 command line. E.g. "more+", when used with --more
                 --more --more, will set the option variable to 3
                 (provided it was 0 or undefined at first).
    
                 The + specifier is ignored if the option destination
                 is not a SCALAR.
    
         =s      Option takes a mandatory string argument.  This
                 string will be assigned to the option variable.
                 Note that even if the string argument starts with -
                 or --, it will not be considered an option on
                 itself.
    
         :s      Option takes an optional string argument.  This
                 string will be assigned to the option variable.  If
                 omitted, it will be assigned "" (an empty string).
                 If the string argument starts with - or --, it will
                 be considered an option on itself.
    
         =i      Option takes a mandatory integer argument.  This
                 value will be assigned to the option variable.  Note
                 that the value may start with - to indicate a
                 negative value.
    
         :i      Option takes an optional integer argument.  This
                 value will be assigned to the option variable.  If
                 omitted, the value 0 will be assigned.  Note that
                 the value may start with - to indicate a negative
                 value.
    
         =f      Option takes a mandatory real number argument.  This
                 value will be assigned to the option variable.  Note
                 that the value may start with - to indicate a
                 negative value.
    
         :f      Option takes an optional real number argument.  This
                 value will be assigned to the option variable.  If
                 omitted, the value 0 will be assigned.
    
         A lone dash - is considered an option, the corresponding
         option name is the empty string.
    
         A double dash on itself -- signals end of the options list.
    
         Linkage specification
    
         The linkage specifier is optional. If no linkage is
         explicitly specified but a ref HASH is passed, GetOptions
         will place the value in the HASH. For example:
    
           %optctl = ();
           GetOptions (\%optctl, "size=i");
    
         will perform the equivalent of the assignment
    
           $optctl{"size"} = 24;
    
         For array options, a reference to an array is used, e.g.:
    
           %optctl = ();
           GetOptions (\%optctl, "sizes=i@");
    
         with command line "-sizes 24 -sizes 48" will perform the
         equivalent of the assignment
    
           $optctl{"sizes"} = [24, 48];
    
         For hash options (an option whose argument looks like
         "name=value"), a reference to a hash is used, e.g.:
    
           %optctl = ();
           GetOptions (\%optctl, "define=s%");
    
         with command line "--define foo=hello --define bar=world"
         will perform the equivalent of the assignment
    
           $optctl{"define"} = {foo=>'hello', bar=>'world')
    
         If no linkage is explicitly specified and no ref HASH is
         passed, GetOptions will put the value in a global variable
         named after the option, prefixed by "opt_". To yield a
         usable Perl variable, characters that are not part of the
         syntax for variables are translated to underscores. For
         example, "--fpp-struct-return" will set the variable
         $opt_fpp_struct_return. Note that this variable resides in
         the namespace of the calling program, not necessarily main.
         For example:
    
           GetOptions ("size=i", "sizes=i@");
    
         with command line "-size 10 -sizes 24 -sizes 48" will
         perform the equivalent of the assignments
    
           $opt_size = 10;
           @opt_sizes = (24, 48);
    
         A lone dash - is considered an option, the corresponding
         Perl identifier is $opt_ .
    
         The linkage specifier can be a reference to a scalar, a
         reference to an array, a reference to a hash or a reference
         to a subroutine.
    
         Note that, if your code is running under the recommended use
         strict 'vars' pragma, it may be helpful to declare these
         package variables via use vars perhaps something like this:
    
           use vars qw/ $opt_size @opt_sizes $opt_bar /;
    
         If a REF SCALAR is supplied, the new value is stored in the
         referenced variable. If the option occurs more than once,
         the previous value is overwritten.
    
         If a REF ARRAY is supplied, the new value is appended
         (pushed) to the referenced array.
    
         If a REF HASH is supplied, the option value should look like
         "key" or "key=value" (if the "=value" is omitted then a
         value of 1 is implied).  In this case, the element of the
         referenced hash with the key "key" is assigned "value".
    
         If a REF CODE is supplied, the referenced subroutine is
         called with two arguments: the option name and the option
         value.  The option name is always the true name, not an
         abbreviation or alias.
    
         Aliases and abbreviations
    
         The option name may actually be a list of option names,
         separated by "|"s, e.g. "foo|bar|blech=s". In this example,
         "foo" is the true name of this option. If no linkage is
         specified, options "foo", "bar" and "blech" all will set
         $opt_foo. For convenience, the single character "?" is
         allowed as an alias, e.g. "help|?".
    
         Option names may be abbreviated to uniqueness, depending on
         configuration option auto_abbrev.
    
         Non-option call-back routine
    
         A special option specifier, <>, can be used to designate a
         subroutine to handle non-option arguments. GetOptions will
         immediately call this subroutine for every non-option it
         encounters in the options list.  This subroutine gets the
         name of the non-option passed.  This feature requires
         configuration option permute, see section CONFIGURATION
         OPTIONS.
    
         See also the examples.
    
         Option starters
    
         On the command line, options can start with - (traditional),
         -- (POSIX) and + (GNU, now being phased out). The latter is
         not allowed if the environment variable POSIXLY_CORRECT has
         been defined.
    
         Options that start with "--" may have an argument appended,
         separated with an "=", e.g. "--foo=bar".
    
         Return values and Errors
    
         Configuration errors and errors in the option definitions
         are signalled using die() and will terminate the calling
         program unless the call to Getopt::Long::GetOptions() was
         embedded in eval { ... } or die() was trapped using
         $SIG{__DIE__}.
    
         A return value of 1 (true) indicates success.
    
         A return status of 0 (false) indicates that the function
         detected one or more errors during option parsing. These
         errors are signalled using warn() and can be trapped with
         $SIG{__WARN__}.
    
         Errors that can't happen are signalled using Carp::croak().
    
    
    

    COMPATIBILITY

         Getopt::Long::GetOptions() is the successor of newgetopt.pl
         that came with Perl 4. It is fully upward compatible.  In
         fact, the Perl 5 version of newgetopt.pl is just a wrapper
         around the module.
    
         If an "@" sign is appended to the argument specifier, the
         option is treated as an array. Value(s) are not set, but
         pushed into array @opt_name. If explicit linkage is
         supplied, this must be a reference to an ARRAY.
    
         If an "%" sign is appended to the argument specifier, the
         option is treated as a hash. Value(s) of the form
         "name=value" are set by setting the element of the hash
         %opt_name with key "name" to "value" (if the "=value"
         portion is omitted it defaults to 1). If explicit linkage is
         supplied, this must be a reference to a HASH.
    
         If configuration option getopt_compat is set (see section
         CONFIGURATION OPTIONS), options that start with "+" or "-"
         may also include their arguments, e.g. "+foo=bar". This is
         for compatiblity with older implementations of the GNU
         "getopt" routine.
    
         If the first argument to GetOptions is a string consisting
         of only non-alphanumeric characters, it is taken to specify
         the option starter characters. Everything starting with one
         of these characters from the starter will be considered an
         option. Using a starter argument is strongly deprecated.
    
         For convenience, option specifiers may have a leading - or
         --, so it is possible to write:
    
            GetOptions qw(-foo=s --bar=i --ar=s);
    
    
    
    

    EXAMPLES

         If the option specifier is "one:i" (i.e. takes an optional
         integer argument), then the following situations are
         handled:
    
            -one -two            -> $opt_one = '', -two is next option
            -one -2              -> $opt_one = -2
    
         Also, assume specifiers "foo=s" and "bar:s" :
    
            -bar -xxx            -> $opt_bar = '', '-xxx' is next option
            -foo -bar            -> $opt_foo = '-bar'
            -foo --              -> $opt_foo = '--'
    
         In GNU or POSIX format, option names and values can be
         combined:
    
            +foo=blech           -> $opt_foo = 'blech'
            --bar=               -> $opt_bar = ''
            --bar=--             -> $opt_bar = '--'
    
         Example of using variable references:
            $ret = GetOptions ('foo=s', \$foo, 'bar=i', 'ar=s', \@ar);
    
         With command line options "-foo blech -bar 24 -ar xx -ar yy"
         this will result in:
    
            $foo = 'blech'
            $opt_bar = 24
            @ar = ('xx','yy')
    
         Example of using the <> option specifier:
    
            @ARGV = qw(-foo 1 bar -foo 2 blech);
            GetOptions("foo=i", \$myfoo, "<>", \&mysub);
    
         Results:
    
            mysub("bar") will be called (with $myfoo being 1)
            mysub("blech") will be called (with $myfoo being 2)
    
         Compare this with:
    
            @ARGV = qw(-foo 1 bar -foo 2 blech);
            GetOptions("foo=i", \$myfoo);
    
         This will leave the non-options in @ARGV:
    
            $myfoo -> 2
            @ARGV -> qw(bar blech)
    
    
    
    

    CONFIGURATION OPTIONS

         GetOptions can be configured by calling subroutine
         Getopt::Long::Configure. This subroutine takes a list of
         quoted strings, each specifying a configuration option to be
         set, e.g.  ignore_case. Options can be reset by prefixing
         with no_, e.g.  no_ignore_case. Case does not matter.
         Multiple calls to config are possible.
    
         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
         new config routine. Besides, it is much easier.
    
         The following options are available:
    
         default     This option causes all configuration options to
                     be reset to their default values.
    
         auto_abbrev Allow option names to be abbreviated to
                     uniqueness.  Default is set unless environment
                     variable POSIXLY_CORRECT has been set, in which
                     case auto_abbrev is reset.
    
         getopt_compat
                     Allow '+' to start options.  Default is set
                     unless environment variable POSIXLY_CORRECT has
                     been set, in which case getopt_compat is reset.
    
         require_order
                     Whether non-options are allowed to be mixed with
                     options.  Default is set unless environment
                     variable POSIXLY_CORRECT has been set, in which
                     case b<require_order> is reset.
    
                     See also permute, which is the opposite of
                     require_order.
    
         permute     Whether non-options are allowed to be mixed with
                     options.  Default is set unless environment
                     variable POSIXLY_CORRECT has been set, in which
                     case permute is reset.  Note that permute is the
                     opposite of require_order.
    
                     If permute is set, this means that
    
                         -foo arg1 -bar arg2 arg3
    
                     is equivalent to
    
                         -foo -bar arg1 arg2 arg3
    
                     If a non-option call-back routine is specified,
                     @ARGV will always be empty upon succesful return
                     of GetOptions since all options have been
                     processed, except when -- is used:
    
                         -foo arg1 -bar arg2 -- arg3
    
                     will call the call-back routine for arg1 and
                     arg2, and terminate leaving arg2 in @ARGV.
    
                     If require_order is set, options processing
                     terminates when the first non-option is
                     encountered.
    
                         -foo arg1 -bar arg2 arg3
    
                     is equivalent to
    
                         -foo -- arg1 -bar arg2 arg3
    
    
         bundling (default: reset)
                     Setting this variable to a non-zero value will
                     allow single-character options to be bundled. To
                     distinguish bundles from long option names, long
                     options must be introduced with -- and single-
                     character options (and bundles) with -. For
                     example,
    
                         ps -vax --vax
    
                     would be equivalent to
    
                         ps -v -a -x --vax
    
                     provided "vax", "v", "a" and "x" have been
                     defined to be valid options.
    
                     Bundled options can also include a value in the
                     bundle; for strings this value is the rest of
                     the bundle, but integer and floating values may
                     be combined in the bundle, e.g.
    
                         scale -h24w80
    
                     is equivalent to
    
                         scale -h 24 -w 80
    
                     Note: resetting bundling also resets
                     bundling_override.
    
         bundling_override (default: reset)
                     If bundling_override is set, bundling is enabled
                     as with bundling but now long option names
                     override option bundles. In the above example,
                     -vax would be interpreted as the option "vax",
                     not the bundle "v", "a", "x".
    
                     Note: resetting bundling_override also resets
                     bundling.
    
                     Note: Using option bundling can easily lead to
                     unexpected results, especially when mixing long
                     options and bundles. Caveat emptor.
    
         ignore_case  (default: set)
                     If set, case is ignored when matching options.
    
                     Note: resetting ignore_case also resets
                     ignore_case_always.
    
         ignore_case_always (default: reset)
                     When bundling is in effect, case is ignored on
                     single-character options also.
    
                     Note: resetting ignore_case_always also resets
                     ignore_case.
    
         pass_through (default: reset)
                     Unknown options are passed through in @ARGV
                     instead of being flagged as errors. This makes
                     it possible to write wrapper scripts that
                     process only part of the user supplied options,
                     and passes the remaining options to some other
                     program.
    
                     This can be very confusing, especially when
                     permute is also set.
    
         prefix      The string that starts options. See also
                     prefix_pattern.
    
         prefix_pattern
                     A Perl pattern that identifies the strings that
                     introduce options.  Default is (--|-|\+) unless
                     environment variable POSIXLY_CORRECT has been
                     set, in which case it is (--|-).
    
         debug (default: reset)
                     Enable copious debugging output.
    
    
    

    OTHER USEFUL VARIABLES

         $Getopt::Long::VERSION
                     The version number of this Getopt::Long
                     implementation in the format major.minor. This
                     can be used to have Exporter check the version,
                     e.g.
    
                         use Getopt::Long 3.00;
    
                     You can inspect $Getopt::Long::major_version and
                     $Getopt::Long::minor_version for the individual
                     components.
    
         $Getopt::Long::error
                     Internal error flag. May be incremented from a
                     call-back routine to cause options parsing to
                     fail.
    
    
    

    AUTHOR

         Johan Vromans <[email protected]>
    
    
    

    COPYRIGHT AND DISCLAIMER

         This program is Copyright 1990,1999 by Johan Vromans.  This
         program is free software; you can redistribute it and/or
         modify it under the terms of the GNU General Public License
         as published by the Free Software Foundation; either version
         2 of the License, or (at your option) any later version.
    
         This program is distributed in the hope that it will be
         useful, but WITHOUT ANY WARRANTY; without even the implied
         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
         PURPOSE.  See the GNU General Public License for more
         details.
    
         If you do not have a copy of the GNU General Public License
         write to the Free Software Foundation, Inc., 675 Mass Ave,
         Cambridge, MA 02139, USA.
    
    
    
    


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру