home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _b40645658adb7d611bac6c0133d77d72 < prev    next >
Encoding:
Text File  |  2004-06-01  |  6.5 KB  |  207 lines
  1. Module Getopt::Long - extended processing of command line options
  2. =================================================================
  3.  
  4. Module Getopt::Long implements an extended getopt function called
  5. GetOptions(). This function implements the POSIX standard for command
  6. line options, with GNU extensions, while still capable of handling
  7. the traditional one-letter options.
  8. In general, this means that command line options can have long names
  9. instead of single letters, and are introduced with a double dash `--'.
  10.  
  11. Optionally, Getopt::Long can support the traditional bundling of
  12. single-letter command line options.
  13.  
  14. Getopt::Long::GetOptions() is part of the Perl 5 distribution. It is
  15. the successor of newgetopt.pl that came with Perl 4. It is fully
  16. upward compatible. In fact, the Perl 5 version of newgetopt.pl is just
  17. a wrapper around the module.
  18.  
  19. For complete documentation, see the Getopt::Long POD document or use
  20. the command
  21.  
  22.     perldoc Getopt::Long
  23.  
  24. FEATURES
  25. ========
  26.  
  27. * Long option names
  28.  
  29. Major advantage of using long option names is that it is much easier
  30. to memorize the option names. Using single-letter names one quickly
  31. runs into the problem that there is no logical relationship between
  32. the semantics of the selected option and its option letter.
  33. Disadvantage is that it requires more typing. Getopt::Long provides
  34. for option name abbreviation, so option names may be abbreviated to
  35. uniqueness. Also, modern shells like Cornell's tcsh support option
  36. name completion. As a rule of thumb, you can use abbreviations freely
  37. while running commands interactively but always use the full names in
  38. scripts. 
  39.  
  40. Examples (POSIX):
  41.  
  42.     --long --width=80 --height=24
  43.  
  44. Extensions:
  45.  
  46.     -long (convenience) +width=80 (deprecated) -height 24 (traditional)
  47.  
  48. By default, long option names are case insensitive.
  49.  
  50. * Single-letter options and bundling
  51.  
  52. When single-letter options are requested, Getopt::Long allows the
  53. option names to be bundled, e.g. "-abc" is equivalent to "-a -b -c".
  54. In this case, long option names must be introduced with the POSIX "--"
  55. introducer.
  56.  
  57. Examples:
  58.  
  59.     -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same)
  60.     even -l24w80 (l = 24 and w = 80)
  61.  
  62. By default, single-letter option names are case sensitive.
  63.  
  64. * Flexibility:
  65.  
  66.   - options can have alternative names, using an alternative name
  67.     will behave as if the primary name was used;
  68.   - options can be negatable, e.g. "debug" will switch it on, while
  69.     "nodebug" will switch it off.    
  70.   - options can set values, but also add values producing an array
  71.     of values instead of a single scalar value, or set values in a hash.
  72.  
  73. * Options linkage
  74.  
  75. Using Getopt::Long gives the programmer ultimate control over the
  76. command line options and how they must be handled:
  77.  
  78.   - by setting a global variable in the calling program;
  79.   - by setting a specified variable;
  80.   - by entering the option name and the value in an associative array
  81.     (hash) or object (if it is a blessed hash);
  82.   - by calling a user-specified subroutine with the option name and
  83.     the value as arguments (for hash options: the name, key and value);
  84.   - combinations of the above.
  85.  
  86. * Customization:
  87.  
  88. The module can be customized by specifying settings in the 'use'
  89. directive, or by calling a special method, Getopt::Long::Configure.
  90. For example, the following two cases are functionally equal:
  91.  
  92.     use Getopt::Long qw(:config bundling no_ignore_case);
  93.  
  94. and
  95.  
  96.     use Getopt::Long;
  97.     Getopt::Long::Configure qw(bundling no_ignore_case);
  98.     
  99. Some of the possible customizations. Most of them take a "no_" prefix
  100. to reverse the effect:
  101.  
  102.   - default
  103.  
  104.     Restore default settings.
  105.  
  106.   - auto_abbrev      
  107.  
  108.     Allow option names to be abbreviated to uniqueness. 
  109.  
  110.   - getopt_compat   
  111.  
  112.     Allow '+' to start options.
  113.  
  114.   - gnu_compat
  115.  
  116.     Compatibility with GNU getopt_long().
  117.  
  118.   - permute
  119.   - require_order           
  120.  
  121.     Whether non-options are allowed to be mixed with options.
  122.  
  123.     permute means that 
  124.  
  125.         -foo arg1 -bar arg2 arg3
  126.  
  127.     is equivalent to
  128.  
  129.         -foo -bar arg1 arg2 arg3
  130.  
  131.     (provided -foo does not take an argument value).
  132.  
  133.     require_order means that options processing
  134.     terminates when the first non-option is encountered.
  135.  
  136.         -foo arg1 -bar arg2 arg3
  137.  
  138.     is equivalent to
  139.  
  140.         -foo -- arg1 -bar arg2 arg3
  141.  
  142.   - bundling
  143.  
  144.     Setting this variable to a non-zero value will allow 
  145.     single-character options to be bundled. To distinguish bundles
  146.     from long option names, long options must be introduced with 
  147.     "--" and single-character options (and bundles) with "-".
  148.  
  149.   - ignore_case      
  150.  
  151.     Ignore case when matching options.
  152.  
  153.   - pass_through
  154.  
  155.     Do not issue error messages for unknown options, but leave
  156.     them (pass-through) in @ARGV.
  157.  
  158.   - prefix
  159.  
  160.     The string that starts options. See also prefix_pattern.
  161.  
  162.   - prefix_pattern
  163.  
  164.     A Perl pattern that identifies the strings that introduce
  165.     options. Default is (--|-|\+) unless environment variable
  166.     POSIXLY_CORRECT has been set, in which case it is (--|-).
  167.  
  168.   - debug
  169.  
  170.     Enable copious debugging output.
  171.  
  172. * Object oriented interface:
  173.  
  174. Using the object oriented interface, multiple parser objects can be
  175. instantiated, each having their own configuration settings:
  176.  
  177.     $p1 = new Getopt::Long::Parser (config => ["bundling"]);
  178.     $p2 = new Getopt::Long::Parser (config => ["posix"]);
  179.     if ($p1->getoptions(...options descriptions...)) ...
  180.  
  181. AVAILABILITY
  182. ============
  183.  
  184. The official version for module Getopt::Long comes with the Perl 5
  185. distribution. 
  186. Newer versions will be made available on the Comprehensive Perl Archive
  187. Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans".
  188. Or use the CPAN search engine:
  189.   http://search.cpan.org/search?mode=module&query=Getopt::Long
  190.   http://search.cpan.org/search?module=Getopt::Long
  191.  
  192. COPYRIGHT AND DISCLAIMER
  193. ========================
  194.  
  195. Module Getopt::Long is Copyright 2003,1990 by Johan Vromans.
  196. This program is free software; you can redistribute it and/or
  197. modify it under the terms of the Perl Artistic License or the
  198. GNU General Public License as published by the Free Software
  199. Foundation; either version 2 of the License, or (at your option) any
  200. later version.
  201.  
  202. -------------------------------------------------------------------
  203. Johan Vromans                                  jvromans@squirrel.nl
  204. Squirrel Consultancy                       Haarlem, the Netherlands
  205. http://www.squirrel.nl       http://www.squirrel.nl/people/jvromans
  206. ------------------ "Arms are made for hugging" --------------------
  207.