diff options
Diffstat (limited to 'cpan/Getopt-Long/README')
| -rw-r--r-- | cpan/Getopt-Long/README | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/cpan/Getopt-Long/README b/cpan/Getopt-Long/README new file mode 100644 index 0000000000..b1b8e2a8f4 --- /dev/null +++ b/cpan/Getopt-Long/README @@ -0,0 +1,214 @@ +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" -------------------- |