lib/Getopt/Long/README

   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 => ["posix"]);
 178     $p2 = new Getopt::Long::Parser (config => ["no_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 2002,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" --------------------