pod/modpods/Getopt.pod

   1 =head1 NAME
   2
   3 getopt - Process single-character switches with switch clustering
   4
   5 getopts - Process single-character switches with switch clustering
   6
   7 GetOptions - extended getopt processing
   8
   9 =head1 SYNOPSIS
  10
  11     use Getopt::Std;
  12     getopt('oDI');  # -o, -D & -I take arg.  Sets opt_* as a side effect.
  13     getopts('oif:');  # -o & -i are boolean flags, -f takes an argument
  14                       # Sets opt_* as a side effect.
  15
  16     use Getopt::Long;
  17     $result = GetOptions (...option-descriptions...);
  18
  19 =head1 DESCRIPTION
  20
  21 The getopt() functions processes single-character switches with switch
  22 clustering.  Pass one argument which is a string containing all switches
  23 that take an argument.  For each switch found, sets $opt_x (where x is the
  24 switch name) to the value of the argument, or 1 if no argument.  Switches
  25 which take an argument don't care whether there is a space between the
  26 switch and the argument.
  27
  28 The Getopt::Long module implements an extended getopt function called
  29 GetOptions(). This function adheres to the new syntax (long option names,
  30 no bundling).  It tries to implement the better functionality of
  31 traditional, GNU and POSIX getopt() functions.
  32
  33 Each description should designate a valid Perl identifier, optionally
  34 followed by an argument specifier.
  35
  36 Values for argument specifiers are:
  37
  38   <none>   option does not take an argument
  39   !        option does not take an argument and may be negated
  40   =s :s    option takes a mandatory (=) or optional (:) string argument
  41   =i :i    option takes a mandatory (=) or optional (:) integer argument
  42   =f :f    option takes a mandatory (=) or optional (:) real number argument
  43
  44 If option "name" is set, it will cause the Perl variable $opt_name to
  45 be set to the specified value. The calling program can use this
  46 variable to detect whether the option has been set. Options that do
  47 not take an argument will be set to 1 (one).
  48
  49 Options that take an optional argument will be defined, but set to ''
  50 if no actual argument has been supplied.
  51
  52 If an "@" sign is appended to the argument specifier, the option is
  53 treated as an array.  Value(s) are not set, but pushed into array
  54 @opt_name.
  55
  56 Options that do not take a value may have an "!" argument specifier to
  57 indicate that they may be negated. E.g. "foo!" will allow B<-foo> (which
  58 sets $opt_foo to 1) and B<-nofoo> (which will set $opt_foo to 0).
  59
  60 The option name may actually be a list of option names, separated by
  61 '|'s, e.g. B<"foo|bar|blech=s". In this example, options 'bar' and
  62 'blech' will set $opt_foo instead.
  63
  64 Option names may be abbreviated to uniqueness, depending on
  65 configuration variable $autoabbrev.
  66
  67 Dashes in option names are allowed (e.g. pcc-struct-return) and will
  68 be translated to underscores in the corresponding Perl variable (e.g.
  69 $opt_pcc_struct_return).  Note that a lone dash "-" is considered an
  70 option, corresponding Perl identifier is $opt_ .
  71
  72 A double dash "--" signals end of the options list.
  73
  74 If the first option of the list consists of non-alphanumeric
  75 characters only, it is interpreted as a generic option starter.
  76 Everything starting with one of the characters from the starter will
  77 be considered an option.
  78
  79 The default values for the option starters are "-" (traditional), "--"
  80 (POSIX) and "+" (GNU, being phased out).
  81
  82 Options that start with "--" may have an argument appended, separated
  83 with an "=", e.g. "--foo=bar".
  84
  85 If configuration variable $getopt_compat is set to a non-zero value,
  86 options that start with "+" may also include their arguments,
  87 e.g. "+foo=bar".
  88
  89 A return status of 0 (false) indicates that the function detected
  90 one or more errors.
  91
  92 =head1 EXAMPLES
  93
  94 If option "one:i" (i.e. takes an optional integer argument), then
  95 the following situations are handled:
  96
  97    -one -two            -> $opt_one = '', -two is next option
  98    -one -2              -> $opt_one = -2
  99
 100 Also, assume "foo=s" and "bar:s" :
 101
 102    -bar -xxx            -> $opt_bar = '', '-xxx' is next option
 103    -foo -bar            -> $opt_foo = '-bar'
 104    -foo --              -> $opt_foo = '--'
 105
 106 In GNU or POSIX format, option names and values can be combined:
 107
 108    +foo=blech           -> $opt_foo = 'blech'
 109    --bar=               -> $opt_bar = ''
 110    --bar=--             -> $opt_bar = '--'
 111
 112 =over 12
 113
 114 =item $autoabbrev
 115
 116 Allow option names to be abbreviated to uniqueness.
 117 Default is 1 unless environment variable
 118 POSIXLY_CORRECT has been set.
 119
 120 =item $getopt_compat
 121
 122 Allow '+' to start options.
 123 Default is 1 unless environment variable
 124 POSIXLY_CORRECT has been set.
 125
 126 =item $option_start
 127
 128 Regexp with option starters.
 129 Default is (--|-) if environment variable
 130 POSIXLY_CORRECT has been set, (--|-|\+) otherwise.
 131
 132 =item $order
 133
 134 Whether non-options are allowed to be mixed with
 135 options.
 136 Default is $REQUIRE_ORDER if environment variable
 137 POSIXLY_CORRECT has been set, $PERMUTE otherwise.
 138
 139 =item $ignorecase
 140
 141 Ignore case when matching options. Default is 1.
 142
 143 =item $debug
 144
 145 Enable debugging output. Default is 0.
 146
 147 =back
 148
 149 =head1 NOTE
 150
 151 Does not yet use the Exporter--or even packages!!
 152 Thus, it's not a real module.
 153