diff options
Diffstat (limited to 'lib/Getopt/Long/README')
| -rw-r--r-- | lib/Getopt/Long/README | 214 |
1 files changed, 0 insertions, 214 deletions
diff --git a/lib/Getopt/Long/README b/lib/Getopt/Long/README deleted file mode 100644 index b1b8e2a8f4..0000000000 --- a/lib/Getopt/Long/README +++ /dev/null @@ -1,214 +0,0 @@ -Module Getopt::Long - extended processing of command line options -================================================================= - -Module Getopt::Long implements an extended getopt function called -GetOptions(). This function implements the POSIX standard for command -line options, with GNU extensions, while still capable of handling -the traditional one-letter options. -In general, this means that command line options can have long names -instead of single letters, and are introduced with a double dash `--'. - -Optionally, Getopt::Long can support the traditional bundling of -single-letter command line options. - -Getopt::Long is part of the Perl 5 distribution. It is the successor -of newgetopt.pl that came with Perl 4. It is fully upward compatible. -In fact, the Perl 5 version of newgetopt.pl is just a wrapper around -the module. - -For complete documentation, see the Getopt::Long POD document or use -the command - - perldoc Getopt::Long - -FEATURES -======== - -* Long option names - -Major advantage of using long option names is that it is much easier -to memorize the option names. Using single-letter names one quickly -runs into the problem that there is no logical relationship between -the semantics of the selected option and its option letter. -Disadvantage is that it requires more typing. Getopt::Long provides -for option name abbreviation, so option names may be abbreviated to -uniqueness. Also, modern shells like Cornell's tcsh support option -name completion. As a rule of thumb, you can use abbreviations freely -while running commands interactively but always use the full names in -scripts. - -Examples (POSIX): - - --long --width=80 --height=24 - -Extensions: - - -long (convenience) +width=80 (deprecated) -height 24 (traditional) - -By default, long option names are case insensitive. - -* Single-letter options and bundling - -When single-letter options are requested, Getopt::Long allows the -option names to be bundled, e.g. "-abc" is equivalent to "-a -b -c". -In this case, long option names must be introduced with the POSIX "--" -introducer. - -Examples: - - -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same) - even -l24w80 (l = 24 and w = 80) - -By default, single-letter option names are case sensitive. - -* Flexibility: - - - options can have alternative names, using an alternative name - will behave as if the primary name was used; - - options can be negatable, e.g. "debug" will switch it on, while - "nodebug" will switch it off. - - options can set values, but also add values producing an array - of values instead of a single scalar value, or set values in a hash. - - options can have multiple values, e.g., "--position 25 624". - -* Options linkage - -Using Getopt::Long gives the programmer ultimate control over the -command line options and how they must be handled: - - - by setting a global variable in the calling program; - - by setting a specified variable; - - by entering the option name and the value in an associative array - (hash) or object (if it is a blessed hash); - - by calling a user-specified subroutine with the option name and - the value as arguments (for hash options: the name, key and value); - - combinations of the above. - -* Customization: - -The module can be customized by specifying settings in the 'use' -directive, or by calling a special method, Getopt::Long::Configure. -For example, the following two cases are functionally equal: - - use Getopt::Long qw(:config bundling no_ignore_case); - -and - - use Getopt::Long; - Getopt::Long::Configure qw(bundling no_ignore_case); - -Some of the possible customizations. Most of them take a "no_" prefix -to reverse the effect: - - - default - - Restore default settings. - - - auto_abbrev - - Allow option names to be abbreviated to uniqueness. - - - getopt_compat - - Allow '+' to start options. - - - gnu_compat - - Compatibility with GNU getopt_long(). - - - permute - - require_order - - Whether non-options are allowed to be mixed with options. - - permute means that - - -foo arg1 -bar arg2 arg3 - - is equivalent to - - -foo -bar arg1 arg2 arg3 - - (provided -foo does not take an argument value). - - require_order means that options processing - terminates when the first non-option is encountered. - - -foo arg1 -bar arg2 arg3 - - is equivalent to - - -foo -- arg1 -bar arg2 arg3 - - - bundling - - Setting this variable to a non-zero value will allow - single-character options to be bundled. To distinguish bundles - from long option names, long options must be introduced with - "--" and single-character options (and bundles) with "-". - - - ignore_case - - Ignore case when matching options. - - - pass_through - - Do not issue error messages for unknown options, but leave - them (pass-through) in @ARGV. - - - prefix - - The string that starts options. See also prefix_pattern. - - - prefix_pattern - - A Perl pattern that identifies the strings that introduce - options. Default is --|-|\+ unless environment variable - POSIXLY_CORRECT has been set, in which case it is --|-. - - - long_prefix_pattern - - A perl pattern that is used to identify which prefixes - should be treated as long style. Any prefixes that don't - match this pattern will have short option semantics. - Defaults to --. - - - debug - - Enable copious debugging output. - -* Object oriented interface: - -Using the object oriented interface, multiple parser objects can be -instantiated, each having their own configuration settings: - - $p1 = new Getopt::Long::Parser (config => ["bundling"]); - $p2 = new Getopt::Long::Parser (config => ["posix"]); - if ($p1->getoptions(...options descriptions...)) ... - -AVAILABILITY -============ - -The official version for module Getopt::Long comes with the Perl 5 -distribution. -Newer versions will be made available on the Comprehensive Perl Archive -Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans". -Or use the CPAN search engine: - http://search.cpan.org/search?mode=module&query=Getopt::Long - http://search.cpan.org/search?module=Getopt::Long - -COPYRIGHT AND DISCLAIMER -======================== - -Module Getopt::Long is Copyright 2009,1990 by Johan Vromans. -This program is free software; you can redistribute it and/or -modify it under the terms of the Perl Artistic License or the -GNU General Public License as published by the Free Software -Foundation; either version 2 of the License, or (at your option) any -later version. - -------------------------------------------------------------------- -Johan Vromans jvromans@squirrel.nl -Squirrel Consultancy Exloo, the Netherlands -http://www.squirrel.nl http://www.squirrel.nl/people/jvromans ------------------- "Arms are made for hugging" -------------------- |