home *** CD-ROM | disk | FTP | other *** search
/ BURKS 2 / BURKS_AUG97.ISO / SLAKWARE / D12 / PERL1.TGZ / perl1.tar / usr / lib / perl5 / Getopt / Long.pm next >
Text File  |  1996-06-28  |  26KB  |  892 lines
  1. # GetOpt::Long.pm -- POSIX compatible options parsing
  2.  
  3. # RCS Status      : $Id: GetoptLong.pm,v 2.1 1996/02/02 20:24:35 jv Exp $
  4. # Author          : Johan Vromans
  5. # Created On      : Tue Sep 11 15:00:12 1990
  6. # Last Modified By: Johan Vromans
  7. # Last Modified On: Fri Feb  2 21:24:32 1996
  8. # Update Count    : 347
  9. # Status          : Released
  10.  
  11. package Getopt::Long;
  12. require 5.000;
  13. require Exporter;
  14.  
  15. @ISA = qw(Exporter);
  16. @EXPORT = qw(&GetOptions $REQUIRE_ORDER $PERMUTE $RETURN_IN_ORDER);
  17. $VERSION = sprintf("%d.%02d", q$Revision: 2.1 $ =~ /(\d+)\.(\d+)/);
  18. use strict;
  19.  
  20. =head1 NAME
  21.  
  22. GetOptions - extended processing of command line options
  23.  
  24. =head1 SYNOPSIS
  25.  
  26.   use Getopt::Long;
  27.   $result = GetOptions (...option-descriptions...);
  28.  
  29. =head1 DESCRIPTION
  30.  
  31. The Getopt::Long module implements an extended getopt function called
  32. GetOptions(). This function adheres to the POSIX syntax for command
  33. line options, with GNU extensions. In general, this means that options
  34. have long names instead of single letters, and are introduced with a
  35. double dash "--". There is no bundling of command line options, as was
  36. the case with the more traditional single-letter approach. For
  37. example, the UNIX "ps" command can be given the command line "option" 
  38.  
  39.   -vax
  40.  
  41. which means the combination of B<-v>, B<-a> and B<-x>. With the new
  42. syntax B<--vax> would be a single option, probably indicating a
  43. computer architecture. 
  44.  
  45. Command line options can be used to set values. These values can be
  46. specified in one of two ways:
  47.  
  48.   --size 24
  49.   --size=24
  50.  
  51. GetOptions is called with a list of option-descriptions, each of which
  52. consists of two elements: the option specifier and the option linkage.
  53. The option specifier defines the name of the option and, optionally,
  54. the value it can take. The option linkage is usually a reference to a
  55. variable that will be set when the option is used. For example, the
  56. following call to GetOptions:
  57.  
  58.   &GetOptions("size=i" => \$offset);
  59.  
  60. will accept a command line option "size" that must have an integer
  61. value. With a command line of "--size 24" this will cause the variable
  62. $offset to get the value 24.
  63.  
  64. Alternatively, the first argument to GetOptions may be a reference to
  65. a HASH describing the linkage for the options. The following call is
  66. equivalent to the example above:
  67.  
  68.   %optctl = ("size" => \$offset);
  69.   &GetOptions(\%optctl, "size=i");
  70.  
  71. Linkage may be specified using either of the above methods, or both.
  72. Linkage specified in the argument list takes precedence over the
  73. linkage specified in the HASH.
  74.  
  75. The command line options are taken from array @ARGV. Upon completion
  76. of GetOptions, @ARGV will contain the rest (i.e. the non-options) of
  77. the command line.
  78.  
  79. Each option specifier designates the name of the option, optionally
  80. followed by an argument specifier. Values for argument specifiers are:
  81.  
  82. =over 8
  83.  
  84. =item <none>
  85.  
  86. Option does not take an argument. 
  87. The option variable will be set to 1.
  88.  
  89. =item !
  90.  
  91. Option does not take an argument and may be negated, i.e. prefixed by
  92. "no". E.g. "foo!" will allow B<--foo> (with value 1) and B<-nofoo>
  93. (with value 0).
  94. The option variable will be set to 1, or 0 if negated.
  95.  
  96. =item =s
  97.  
  98. Option takes a mandatory string argument.
  99. This string will be assigned to the option variable.
  100. Note that even if the string argument starts with B<-> or B<-->, it
  101. will not be considered an option on itself.
  102.  
  103. =item :s
  104.  
  105. Option takes an optional string argument.
  106. This string will be assigned to the option variable.
  107. If omitted, it will be assigned "" (an empty string).
  108. If the string argument starts with B<-> or B<-->, it
  109. will be considered an option on itself.
  110.  
  111. =item =i
  112.  
  113. Option takes a mandatory integer argument.
  114. This value will be assigned to the option variable.
  115. Note that the value may start with B<-> to indicate a negative
  116. value. 
  117.  
  118. =item :i
  119.  
  120. Option takes an optional integer argument.
  121. This value will be assigned to the option variable.
  122. If omitted, the value 0 will be assigned.
  123. Note that the value may start with B<-> to indicate a negative
  124. value.
  125.  
  126. =item =f
  127.  
  128. Option takes a mandatory real number argument.
  129. This value will be assigned to the option variable.
  130. Note that the value may start with B<-> to indicate a negative
  131. value.
  132.  
  133. =item :f
  134.  
  135. Option takes an optional real number argument.
  136. This value will be assigned to the option variable.
  137. If omitted, the value 0 will be assigned.
  138.  
  139. =back
  140.  
  141. A lone dash B<-> is considered an option, the corresponding option
  142. name is the empty string.
  143.  
  144. A double dash on itself B<--> signals end of the options list.
  145.  
  146. =head2 Linkage specification
  147.  
  148. The linkage specifier is optional. If no linkage is explicitly
  149. specified but a ref HASH is passed, GetOptions will place the value in
  150. the HASH. For example:
  151.  
  152.   %optctl = ();
  153.   &GetOptions (\%optctl, "size=i");
  154.  
  155. will perform the equivalent of the assignment
  156.  
  157.   $optctl{"size"} = 24;
  158.  
  159. For array options, a reference to an array is used, e.g.:
  160.  
  161.   %optctl = ();
  162.   &GetOptions (\%optctl, "sizes=i@");
  163.  
  164. with command line "-sizes 24 -sizes 48" will perform the equivalent of
  165. the assignment
  166.  
  167.   $optctl{"sizes"} = [24, 48];
  168.  
  169. If no linkage is explicitly specified and no ref HASH is passed,
  170. GetOptions will put the value in a global variable named after the
  171. option, prefixed by "opt_". To yield a usable Perl variable,
  172. characters that are not part of the syntax for variables are
  173. translated to underscores. For example, "--fpp-struct-return" will set
  174. the variable $opt_fpp_struct_return. Note that this variable resides
  175. in the namespace of the calling program, not necessarily B<main>.
  176. For example:
  177.  
  178.   &GetOptions ("size=i", "sizes=i@");
  179.  
  180. with command line "-size 10 -sizes 24 -sizes 48" will perform the
  181. equivalent of the assignments
  182.  
  183.   $opt_size = 10;
  184.   @opt_sizes = (24, 48);
  185.  
  186. A lone dash B<-> is considered an option, the corresponding Perl
  187. identifier is $opt_ .
  188.  
  189. The linkage specifier can be a reference to a scalar, a reference to
  190. an array or a reference to a subroutine.
  191.  
  192. If a REF SCALAR is supplied, the new value is stored in the referenced
  193. variable. If the option occurs more than once, the previous value is
  194. overwritten. 
  195.  
  196. If a REF ARRAY is supplied, the new value is appended (pushed) to the
  197. referenced array. 
  198.  
  199. If a REF CODE is supplied, the referenced subroutine is called with
  200. two arguments: the option name and the option value.
  201. The option name is always the true name, not an abbreviation or alias.
  202.  
  203. =head2 Aliases and abbreviations
  204.  
  205. The option name may actually be a list of option names, separated by
  206. "|"s, e.g. "foo|bar|blech=s". In this example, "foo" is the true name
  207. op this option. If no linkage is specified, options "foo", "bar" and
  208. "blech" all will set $opt_foo.
  209.  
  210. Option names may be abbreviated to uniqueness, depending on
  211. configuration variable $Getopt::Long::autoabbrev.
  212.  
  213. =head2 Non-option call-back routine
  214.  
  215. A special option specifier, <>, can be used to designate a subroutine
  216. to handle non-option arguments. GetOptions will immediately call this
  217. subroutine for every non-option it encounters in the options list.
  218. This subroutine gets the name of the non-option passed.
  219. This feature requires $Getopt::Long::order to have the value $PERMUTE.
  220. See also the examples.
  221.  
  222. =head2 Option starters
  223.  
  224. On the command line, options can start with B<-> (traditional), B<-->
  225. (POSIX) and B<+> (GNU, now being phased out). The latter is not
  226. allowed if the environment variable B<POSIXLY_CORRECT> has been
  227. defined.
  228.  
  229. Options that start with "--" may have an argument appended, separated
  230. with an "=", e.g. "--foo=bar".
  231.  
  232. =head2 Return value
  233.  
  234. A return status of 0 (false) indicates that the function detected
  235. one or more errors.
  236.  
  237. =head1 COMPATIBILITY
  238.  
  239. Getopt::Long::GetOptions() is the successor of
  240. B<newgetopt.pl> that came with Perl 4. It is fully upward compatible.
  241. In fact, the Perl 5 version of newgetopt.pl is just a wrapper around
  242. the module.
  243.  
  244. If an "@" sign is appended to the argument specifier, the option is
  245. treated as an array.  Value(s) are not set, but pushed into array
  246. @opt_name. This only applies if no linkage is supplied.
  247.  
  248. If configuration variable $Getopt::Long::getopt_compat is set to a
  249. non-zero value, options that start with "+" may also include their
  250. arguments, e.g. "+foo=bar". This is for compatiblity with older
  251. implementations of the GNU "get