pod/modpods/GetOptions.pod

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