Getopt::Long man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

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");

16/Sep/1999	       perl 5.005, patch 03			1

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

       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

16/Sep/1999	       perl 5.005, patch 03			2

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

	       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

16/Sep/1999	       perl 5.005, patch 03			3

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

       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

16/Sep/1999	       perl 5.005, patch 03			4

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

       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

16/Sep/1999	       perl 5.005, patch 03			5

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

       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);

16/Sep/1999	       perl 5.005, patch 03			6

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

       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

16/Sep/1999	       perl 5.005, patch 03			7

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

		   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 -.


16/Sep/1999	       perl 5.005, patch 03			8

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

		   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

16/Sep/1999	       perl 5.005, patch 03			9

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

		   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 <jvromans@squirrel.nl>

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

16/Sep/1999	       perl 5.005, patch 03		       10

Getopt::Long(3)	 Perl Programmers Reference Guide Getopt::Long(3)

       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.

16/Sep/1999	       perl 5.005, patch 03		       11

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net