cpan/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 is part of the Perl 5 distribution. It is the successor
  15 of newgetopt.pl that came with Perl 4. It is fully upward compatible.
  16 In fact, the Perl 5 version of newgetopt.pl is just a wrapper around
  17 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   - options can have multiple values, e.g., "--position 25 624".
  73
  74 * Options linkage
  75
  76 Using Getopt::Long gives the programmer ultimate control over the
  77 command line options and how they must be handled:
  78
  79   - by setting a global variable in the calling program;
  80   - by setting a specified variable;
  81   - by entering the option name and the value in an associative array
  82     (hash) or object (if it is a blessed hash);
  83   - by calling a user-specified subroutine with the option name and
  84     the value as arguments (for hash options: the name, key and value);
  85   - combinations of the above.
  86
  87 * Customization:
  88
  89 The module can be customized by specifying settings in the 'use'
  90 directive, or by calling a special method, Getopt::Long::Configure.
  91 For example, the following two cases are functionally equal:
  92
  93     use Getopt::Long qw(:config bundling no_ignore_case);
  94
  95 and
  96
  97     use Getopt::Long;
  98     Getopt::Long::Configure qw(bundling no_ignore_case);
  99
 100 Some of the possible customizations. Most of them take a "no_" prefix
 101 to reverse the effect:
 102
 103   - default
 104
 105         Restore default settings.
 106
 107   - auto_abbrev
 108
 109         Allow option names to be abbreviated to uniqueness.
 110
 111   - getopt_compat
 112
 113         Allow '+' to start options.
 114
 115   - gnu_compat
 116
 117         Compatibility with GNU getopt_long().
 118
 119   - permute
 120   - require_order
 121
 122         Whether non-options are allowed to be mixed with options.
 123
 124         permute means that
 125
 126             -foo arg1 -bar arg2 arg3
 127
 128         is equivalent to
 129
 130             -foo -bar arg1 arg2 arg3
 131
 132         (provided -foo does not take an argument value).
 133
 134         require_order means that options processing
 135         terminates when the first non-option is encountered.
 136
 137             -foo arg1 -bar arg2 arg3
 138
 139         is equivalent to
 140
 141             -foo -- arg1 -bar arg2 arg3
 142
 143   - bundling
 144
 145         Setting this variable to a non-zero value will allow
 146         single-character options to be bundled. To distinguish bundles
 147         from long option names, long options must be introduced with
 148         "--" and single-character options (and bundles) with "-".
 149
 150   - ignore_case
 151
 152         Ignore case when matching options.
 153
 154   - pass_through
 155
 156         Do not issue error messages for unknown options, but leave
 157         them (pass-through) in @ARGV.
 158
 159   - prefix
 160
 161         The string that starts options. See also prefix_pattern.
 162
 163   - prefix_pattern
 164
 165         A Perl pattern that identifies the strings that introduce
 166         options. Default is --|-|\+ unless environment variable
 167         POSIXLY_CORRECT has been set, in which case it is --|-.
 168
 169   - long_prefix_pattern
 170
 171         A perl pattern that is used to identify which prefixes
 172         should be treated as long style. Any prefixes that don't
 173         match this pattern will have short option semantics.
 174         Defaults to --.
 175
 176   - debug
 177
 178         Enable copious debugging output.
 179
 180 * Object oriented interface:
 181
 182 Using the object oriented interface, multiple parser objects can be
 183 instantiated, each having their own configuration settings:
 184
 185     $p1 = new Getopt::Long::Parser (config => ["bundling"]);
 186     $p2 = new Getopt::Long::Parser (config => ["posix"]);
 187     if ($p1->getoptions(...options descriptions...)) ...
 188
 189 AVAILABILITY
 190 ============
 191
 192 The official version for module Getopt::Long comes with the Perl 5
 193 distribution.
 194 Newer versions will be made available on the Comprehensive Perl Archive
 195 Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans".
 196 Or use the CPAN search engine:
 197   http://search.cpan.org/search?mode=module&query=Getopt::Long
 198   http://search.cpan.org/search?module=Getopt::Long
 199
 200 COPYRIGHT AND DISCLAIMER
 201 ========================
 202
 203 Module Getopt::Long is Copyright 2009,1990 by Johan Vromans.
 204 This program is free software; you can redistribute it and/or
 205 modify it under the terms of the Perl Artistic License or the
 206 GNU General Public License as published by the Free Software
 207 Foundation; either version 2 of the License, or (at your option) any
 208 later version.
 209
 210 -------------------------------------------------------------------
 211 Johan Vromans                                  jvromans@squirrel.nl
 212 Squirrel Consultancy                         Exloo, the Netherlands
 213 http://www.squirrel.nl       http://www.squirrel.nl/people/jvromans
 214 ------------------ "Arms are made for hugging" --------------------