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