getopt-declare 1.13 → 1.20

data/Declare.rdoc

@@ -5,14 +5,24 @@
 #
 #  = VERSION
 #
-#  This document describes version 1.09 of Getopt::Declare,
-#  released May 21, 1999 for Perl.
-#  Released Jan 15, 2003 for Ruby.
+#  This document describes version 1.20 of Getopt::Declare,
+#  Released Jan 15, 2007 for Ruby.
+#
+#  Original Perl's Getopt-Declare v1.09, Released May 21, 1999.
 #
 #  = SYNOPSIS
 #
 #   require "Getopt/Declare"
-#   args = Getopt::Declare.new(specification_string, optional_source);
+#   args = Getopt::Declare.new(<<'EOF')
+#
+#   -q, --quiet                 quiet
+#   -f, --files <files:if>...   input files
+#
+#   EOF
+#
+#   p args['-q']
+#   p args['-f']
+#   p args.unused
 #
 #
 #  = DESCRIPTION
@@ -81,8 +91,8 @@
 #  * Optional conditional execution of embedded actions (i.e. only on
 #    successful parsing of the entire command-line)
 #
-#  * Strict or non-strict parsing (unrecognized command-line elements may either
-#    trigger an error or may simply be left in +ARGV+
+#  * Strict or non-strict parsing (unrecognized command-line elements may 
+#    either trigger an error or may simply be left in +ARGV+
 #
 #  * Declarative specification of various inter-parameter relationships (for
 #    example, two parameters may be declared mutually exclusive and this
@@ -97,6 +107,8 @@
 #  * The ability to parse files (especially configuration files) instead of
 #    the command-line.
 #
+#  * GNU style parameter definition allowed (-q, --quiet) in a single line.
+#
 #  == Terminology
 #
 #  The terminology of command-line processing is often confusing, with various
@@ -136,8 +148,8 @@
 #
 #  * <b>"parameter definition"</b>
 #
-#    A specification of one actual syntax variant matched by a parameter. Always
-#    consists of a leading _parameter_ _flag_ or _parameter_ _variable_,
+#    A specification of one actual syntax variant matched by a parameter. 
+#    Always consists of a leading _parameter_ _flag_ or _parameter_ _variable_,
 #    optionally followed by one or more _parameter_ _components_ (that is,
 #    other parameter variables or _punctuators_. In the above example, 
 #    <tt>--window <height> x <width></tt> is a parameter definition.
@@ -145,18 +157,18 @@
 #
 #  * <b>"parameter flag" (or just "flag")</b>
 #
-#    A sequence of non-space characters which introduces a parameter. Traditionally
-#    a parameter flag begins with "-" or "--", but Getopt::Declare allows
-#    almost any sequence of characters to be used as a flag. In the above example,
-#    <tt>--window</tt> is the parameter flag.
+#    A sequence of non-space characters which introduces a parameter. 
+#    Traditionally a parameter flag begins with "-" or "--", but 
+#    Getopt::Declare allows almost any sequence of characters to be used as
+#    a flag. In the above example, <tt>--window</tt> is the parameter flag.
 #
 #
 #  * <b>"parameter variable"</b>
 #
 #    A place-holder (within a parameter specification) for a value that 
 #    will appear in any argument matching that parameter. In the above example,
-#    <tt>-height</tt>, <tt>-width</tt>, <tt>-h</tt>, <tt>-w</tt>, <tt>-x</tt>, and <tt>-y</tt> are 
-#    all parameter variables.
+#    <tt>-height</tt>, <tt>-width</tt>, <tt>-h</tt>, <tt>-w</tt>, <tt>-x</tt>,
+#    and <tt>-y</tt> are all parameter variables.
 #
 #
 #  * <b>"parameter punctuator" (or just "punctuator")</b>
@@ -204,8 +216,9 @@
 #  The parameter definition consists of a leading flag or parameter
 #  variable, followed by any number of parameter variables or
 #  punctuators, optionally separated by spaces. The parameter definition
-#  is terminated by one or more tabs (at least one trailing tab _must_
-#  be present).
+#  is terminated by one or more tabs or, alternatively, 3 or more spaces
+#  (at least one trailing tab or 3 trailing spaces _must_ appear for the
+#  line to be considered a parameter definition).
 #
 #  For example, all of the following are valid Getopt::Declare parameter
 #  definitions:
@@ -248,9 +261,9 @@
 #  	--lines1-10
 #  	--lines 1-10
 #
-#  Note that the optional nature of spaces in parameter specification implies that
-#  flags and punctuators cannot contain the character '<' (which is taken as the
-#  delimiter for a parameter variable) nor the character '[' (which
+#  Note that the optional nature of spaces in parameter specification implies 
+#  that flags and punctuators cannot contain the character '<' (which is taken
+#  as the delimiter for a parameter variable) nor the character '[' (which
 #  introduces an optional parameter component - see
 #  "Optional parameter components".
 #
@@ -344,8 +357,8 @@
 #  	-list [<page>...]
 #
 #  Two or more parameter components may be made jointly optional, by specifying
-#  them in the same pair of brackets. Optional components may also be nested. For
-#  example:
+#  them in the same pair of brackets. Optional components may also be nested. 
+#  For example:
 #
 #  	-range <from> [.. [<to>] ]
 #
@@ -364,6 +377,18 @@
 #  Note that the actual flags for these three parameters are <tt>-num</tt>, 
 #  <tt>-lexic</tt> and <tt>-b</tt>, respectively.
 #
+#  == GNU-style parameters
+#
+#  As of v1.20 of Getopt-Declare, it is also possible to write
+#  parameter descriptions following GNU's conventions.
+#  You can write, for example:
+#
+#       -f, --file <file:if>     Filename to read
+#
+#  This allows both <tt>-f <file></tt> and <tt>--file <file></tt> to be 
+#  valid options.
+#  When retrieving the value, use the short form <tt>args['-f']</tt>.
+#
 #  == Parameter descriptions
 #
 #  Providing a textual description for each parameter (or parameter
@@ -423,7 +448,7 @@
 #  same name. For example:
 #
 #  	+range <from>..<to>	Set range
-#  					{ setrange($from, $to) }
+#  					{ setrange(from, to) }
 #
 #  	-list <page:i>...	Specify pages to list
 #  					{ page.each { |i|
@@ -461,7 +486,7 @@
 #  				verbose = 2      
 #  			      else
 #  			        verbose = 1
-#                                end
+#                             end
 #  			    }
 #
 #  * <tt>\_FOUND_</tt>  Hash
@@ -485,8 +510,8 @@
 #
 #    For reasons that will be explained in "Rejection and termination",
 #    a given parameter is not marked as found until _after_ its
-#    associated actions are executed. That is, <tt>_FOUND_[\_PARAM_]</tt> will not
-#    (usually) be true during a parameter action.
+#    associated actions are executed. That is, <tt>_FOUND_[\_PARAM_]</tt> will 
+#    not (usually) be true during a parameter action.
 #
 #
 #  Note that, although numerous other internal variables on which the
@@ -543,8 +568,9 @@
 #
 #  	-v	Verbose mode
 #
-#  means that the arguments "-q" and "-Q" will both match the <tt>-q</tt> parameter, but
-#  that only "-v" (and _not_ "-V") will match the <tt>-v</tt> parameter.
+#  means that the arguments "-q" and "-Q" will both match the <tt>-q</tt> 
+#  parameter, but that only "-v" (and _not_ "-V") will match the <tt>-v</tt>
+#  parameter.
 #
 #  If a <tt>[nocase]</tt> directive appears anywhere _outside_ a parameter 
 #  description, then the entire specification is declared case-insensitive 
@@ -630,16 +656,18 @@
 #
 #    which restricts a parameter variable to matching positive, non-zero
 #    numbers (that is, floating point numbers strictly greater than zero).
+#    Scientific notation can also be used.
 #
 #  * :0+i  
 #
-#    which restricts a parameter variable to matching non-negative integers (that
-#    is: 0, 1, 2, 3, etc.)
+#    which restricts a parameter variable to matching non-negative integers 
+#    (that is: 0, 1, 2, 3, etc.)
 #
 #  * :0+n  
 #
-#    which restricts a parameter variable to matching non-negative numbers (that
-#    is, floating point numbers greater than or equal to zero).
+#    which restricts a parameter variable to matching non-negative numbers 
+#    (that is, floating point numbers greater than or equal to zero).
+#    Scientific notation can also be used.
 #
 #  * :s  
 #
@@ -664,9 +692,10 @@
 #
 #  * :of  
 #
-#    which is used to match output file names. It is exactly like type ':if' except
-#    that it requires that the string is either "-" (indicating standard output)
-#    or the name of a file that is either writable or non-existent.
+#    which is used to match output file names. It is exactly like type ':if'
+#    except that it requires that the string is either "-" (indicating 
+#    standard output) or the name of a file that is either writable or
+#    non-existent.
 #
 #  * :s  
 #
@@ -697,14 +726,14 @@
 #
 #  * %T
 #
-#    If the sequence <tt>%T</tt> appears in a pattern, it is translated to a negative
-#    lookahead containing the parameter variable's trailing context.
+#    If the sequence <tt>%T</tt> appears in a pattern, it is translated to a 
+#    negative lookahead containing the parameter variable's trailing context.
 #    Hence the parameter definition:
 #
 #  	-find <what:/(%T.)+/> ;
 #
-#    ensures that the command line argument "-find abcd;" causes <tt><-what></tt>
-#    to match "abcd", _not_ "abcd;".
+#    ensures that the command line argument "-find abcd;" causes 
+#    <tt><-what></tt> to match "abcd", _not_ "abcd;".
 #
 #
 #  * %D
@@ -793,10 +822,10 @@
 #    match if it's Wednesday (like its parent type ":num").
 #
 #  * the new type ":nbr" matches any string of digits (like its parent type
-#    ":a num"), but then rejects the match if the global <tt>$no_nbr</tt> variable
-#    is true. Otherwise it next prints out "a num!" (like its parent type
-#    ":a num"), and finally rejects the match if it's Wednesday (like its
-#    grandparent type ":num").
+#    ":a num"), but then rejects the match if the global <tt>$no_nbr</tt> 
+#    variable is true. Otherwise it next prints out "a num!" (like its 
+#    parent type ":a num"), and finally rejects the match if it's
+#    Wednesday (like its grandparent type ":num").
 #
 #
 #  When a type action is executed (as part of a particular parameter
@@ -804,11 +833,12 @@
 #
 #  * <tt>\_VAL_</tt>  String/Fixnum/Float
 #
-#    which contains the value matched by the type's pattern. It is this value which
-#    is ultimately assigned to the local Ruby variable which is available to
-#    parameter actions. Hence if the type action changes the value of <tt>\_VAL_</tt>,
-#    that changed value becomes the "real" value of the corresponding parameter
-#    variable (see the Roman numeral example below).
+#    which contains the value matched by the type's pattern. It is this 
+#    value which is ultimately assigned to the local Ruby variable which is
+#    available to parameter actions. Hence if the type action changes the
+#    value of <tt>\_VAL_</tt>, that changed value becomes the "real" value 
+#    of the corresponding parameter variable (see the Roman numeral example
+#    below).
 #    Note that <tt>\_VAL_</tt> is a variable of different type based on
 #    parameter specified.  For [pvtype:...] it is always a String variable.
 #
@@ -909,8 +939,8 @@
 #  Sometimes it is desirable to provide two or more alternate flags for
 #  the same behaviour (typically, a short form and a long form). To
 #  reduce the burden of specifying such pairs, the special directive
-#  <tt>[ditto]</tt> is provided. If the description of a parameter _begins_ with
-#  a <tt>[ditto]</tt> directive, that directive is replaced with the
+#  <tt>[ditto]</tt> is provided. If the description of a parameter _begins_ 
+#  with a <tt>[ditto]</tt> directive, that directive is replaced with the
 #  description for the immediately preceding parameter (including any
 #  other directives). For example:
 #
@@ -930,7 +960,8 @@
 #  				{ $verbose = 1; }
 #  	--verbose	[ditto]
 #
-#  would result in the <tt>--verbose</tt> option setting <tt>$verbose</tt> just like the
+#  would result in the <tt>--verbose</tt> option setting 
+#  <tt>$verbose</tt> just like the
 #  <tt>-v</tt> option. On the other hand, the specification:
 #
 #  	-v		Verbose mode
@@ -950,11 +981,11 @@
 #  the command-line arguments they modify.
 #
 #  To support this, Getopt::Declare provides a local operator (+defer+) which
-#  delays the execution of a particular action until the command-line processing
-#  is finished. The +defer+ operator takes a single block, the execution of which
-#  is deferred until the command-line is fully and successfully parsed. If
-#  command-line processing _fails_ for some reason (see "DIAGNOSTICS"), the
-#  deferred blocks are never executed.
+#  delays the execution of a particular action until the command-line 
+#  processing is finished. The +defer+ operator takes a single block, the
+#  execution of which is deferred until the command-line is fully and
+#  successfully parsed. If  command-line processing _fails_ for some reason
+#  (see "DIAGNOSTICS"), the deferred blocks are never executed.
 #
 #  For example:
 #
@@ -1016,8 +1047,8 @@
 #  controlling "+".
 #
 #  In some circumstances a clustered sequence of flags on the command-line
-#  might also match a single (multicharacter) parameter flag. For example, given
-#  the specifications:
+#  might also match a single (multicharacter) parameter flag. 
+#  For example, given the specifications:
 #
 #  	-a		Blood type is A
 #  	-b		Blood type is B
@@ -1035,7 +1066,8 @@
 #  but (as the above example illustrates) may not always do so. If the
 #  idea of unconstrained flag clustering is too libertarian for a particular
 #  application, the feature may be restricted (or removed completely),
-#  by including a <tt>[cluster:...]</tt> directive anywhere in the specification string.
+#  by including a <tt>[cluster:...]</tt> directive anywhere in the 
+#  specification string.
 #
 #  The options are:
 #
@@ -1047,7 +1079,8 @@
 #  * <tt>[cluster: flags]</tt>
 #
 #    This version of the directive restricts clustering to parameters which are
-#    "pure" flags (that is, those which have no parameter variables or punctuators).
+#    "pure" flags (that is, those which have no parameter variables or 
+#    punctuators).
 #
 #  * <tt>[cluster: singles]</tt>
 #
@@ -1072,15 +1105,17 @@
 #  		[cluster:singles]
 #  	EOSPEC
 #
-#  In the above example, only the <tt>-a</tt> and <tt>-b</tt> parameters may be clustered.
+#  In the above example, only the <tt>-a</tt> and <tt>-b</tt> parameters may
+#  be clustered.
 #  The <tt>-bu</tt> parameter is excluded because it consists of more than one
-#  letter, whilst the <tt>-c</tt> and <tt>-d</tt> parameters are excluded because they
-#  take (or may take, in <tt>-d</tt>'s case) a variable. The <tt>-e[xec]</tt> parameter
-#  is excluded because it may take a trailing punctuator (<tt>[xec]</tt>).
+#  letter, whilst the <tt>-c</tt> and <tt>-d</tt> parameters are excluded 
+#  because they take (or may take, in <tt>-d</tt>'s case) a variable. The
+#  <tt>-e[xec]</tt> parameter is excluded because it may take a trailing
+#  punctuator (<tt>[xec]</tt>).
 #
 #  By comparison, if the directive had been <tt>[cluster: flags]</tt>, then
-#  <tt>-bu</tt> _could_ be clustered, though <tt>-c</tt>, <tt>-d</tt> and <tt>-e[xec]</tt> would
-#  still be excluded since they are not "pure flags").
+#  <tt>-bu</tt> _could_ be clustered, though <tt>-c</tt>, <tt>-d</tt> and 
+#  <tt>-e[xec]</tt> would still be excluded since they are not "pure flags").
 #
 #
 #  == Strict and non-strict command-line parsing
@@ -1185,8 +1220,8 @@
 #
 #    However, it is sometimes useful to allow a particular parameter to match
 #    more than once.  Any parameter whose description includes the directive
-#    <tt>[repeatable]</tt> is _never_ excluded as a potential argument match, no matter
-#    how many times it has matched previously:
+#    <tt>[repeatable]</tt> is _never_ excluded as a potential argument match, 
+#    no matter how many times it has matched previously:
 #
 #  	-nice		Increase nice value (linearly if repeated)
 #  			[repeatable]
@@ -1196,9 +1231,9 @@
 #  			of the command-line 
 #  				{ warn = !warn }
 #
-#    As a more general mechanism is a <tt>[repeatable]</tt> directive appears in a
-#    specification anywhere other than a flag's description, then _all_ parameters
-#    are marked repeatable:
+#    As a more general mechanism is a <tt>[repeatable]</tt> directive 
+#    appears in a specification anywhere other than a flag's description, 
+#    then _all_ parameters are marked repeatable:
 #
 #  	[repeatable]
 #
@@ -1259,9 +1294,10 @@
 #  * <tt>[excludes: <flag list>]</tt>
 #
 #    The <tt>[excludes:...]</tt> directive provides a "pairwise" version of
-#    mutual exclusion, specifying that the current parameter is mutually exclusive
-#    with all the other parameters lists, but those other parameters are not
-#    mutually exclusive with each other. That is, whereas the specification:
+#    mutual exclusion, specifying that the current parameter is mutually 
+#    exclusive with all the other parameters lists, but those other
+#    parameters are not mutually exclusive with each other. That is, 
+#    whereas the specification:
 #
 #  	-left		Justify to left margin
 #  	-right		Justify to right margin
@@ -1269,8 +1305,8 @@
 #
 #  	[mutex: -left -right -centre]
 #
-#    means that only one of these three justification alternatives can ever be used
-#    at once, the specification:
+#    means that only one of these three justification alternatives can ever 
+#    be used at once, the specification:
 #
 #  	-left		Justify to left margin   
 #  	-right		Justify to right margin 
@@ -1278,7 +1314,8 @@
 #
 #    means that <tt>-left</tt> and <tt>-right</tt> can still be used together
 #    (probably to indicate "left _and_ right" justification), but that
-#    neither can be used with <tt>-centre</tt>. Note that the <tt>[excludes:...]</tt>
+#    neither can be used with <tt>-centre</tt>. Note that 
+#    the <tt>[excludes:...]</tt>
 #    directive also differs from the <tt>[mutex:...]</tt> in that it is always 
 #    connected with a paricular parameter, _implicitly_
 #    using the flag of that parameter as the target of exclusion.
@@ -1290,7 +1327,8 @@
 #    must also appear in order for a particular flag to be permitted in the
 #    command-line. The condition is a boolean expression, in which the
 #    terms are the flags or various parameters, and the operations are 
-#    <tt>&&</tt>, <tt>||</tt>, <tt>!</tt>, and bracketting. For example, the specifications:
+#    <tt>&&</tt>, <tt>||</tt>, <tt>!</tt>, and bracketting. For example, 
+#    the specifications:
 #
 #  	-num		Use numeric sort order
 #  	-lex		Use "dictionary" sort order
@@ -1301,31 +1339,36 @@
 #  	-rev		Reverse sort order
 #  			[requires: -num || -lex || !(-len && -field)]
 #
-#    means that the <tt>-rev</tt> flag is allowed only if either the <tt>-num</tt> or the
-#    <tt>-lex</tt> parameter has been used, or if it is not true that
-#    _both_ the <tt>-len</tt> _and_ the <tt>-field</tt> parameters have been used.
+#    means that the <tt>-rev</tt> flag is allowed only if either the 
+#    <tt>-num</tt> or the <tt>-lex</tt> parameter has been used, or if it
+#    is not true that _both_ the <tt>-len</tt> _and_ the <tt>-field</tt>
+#    parameters have been used.
 #
-#    Note that the operators <tt>&&</tt>, <tt>||</tt> and <tt>!</tt> retain their normal
-#    Ruby precedences.
+#    Note that the operators <tt>&&</tt>, <tt>||</tt> and <tt>!</tt> retain 
+#    their normal Ruby precedences.
 #
 #
 #  == Parsing from other sources
 #
 #  Getopt::Declare normally parses the contents of +ARGV+, but can
 #  be made to parse specified files or other sources instead. 
-#  To accommodate this, Getopt::Declare::new() takes an optional second parameter, which specifies a file to be parsed. 
-#  This second parameter can also be passed directly onto Getopt::Declare::parse()
+#  To accommodate this, Getopt::Declare::new() takes an optional second 
+#  parameter, which specifies a file to be parsed. 
+#  This second parameter can also be passed directly onto 
+#  Getopt::Declare::parse()
 #  The parameter may be either:
 #
 #  * An +IO+ object
 #
 #    in which case Getopt::Declare::new() reads the corresponding handle until
-#    end-of-file, and parses the resulting text (even if it is an empty string).
+#    end-of-file, and parses the resulting text (even if it is an 
+#    empty string).
 #
 #  * An ARRAY containing the single string ['-CONFIG']
 #
 #    in which case Getopt::Declare::new() looks for the files
-#    <tt>ENV['HOME']/.#{progname}rc</tt> and <tt>ENV['PWD']/.#{progname}rc</tt>,
+#    <tt>ENV['HOME']/.#{progname}rc</tt> and 
+#    <tt>ENV['PWD']/.#{progname}rc</tt>,
 #    concatenates their contents, and parses that.
 #
 #    If neither file is found (or if both are inaccessible)
@@ -1339,7 +1382,8 @@
 #    See "The Getopt::Declare::code() method" and 
 #    "The Getopt::Declare::parse() method".
 #
-#  * An ARRAY containing the single string ['-SKIP'] or the single value [nil] or nothing []
+#  * An ARRAY containing the single string ['-SKIP'] or the single 
+#    value [nil] or nothing []
 #
 #    in which case Getopt::Declare::new() immediately returns zero.
 #    This alternative is useful when using a +File+:
@@ -1348,8 +1392,8 @@
 #  				   File.new(filename) || ['-SKIP'])
 #
 #    because it makes explicit what happens if File::new() fails. Of course,
-#    if the <tt>['-SKIP']</tt> alternative were omitted, Getopt::Declare::new would
-#    still return immediately, having found +nil+ as its second argument.
+#    if the <tt>['-SKIP']</tt> alternative were omitted, Getopt::Declare::new
+#    would still return immediately, having found +nil+ as its second argument.
 #
 #  * An ARRAY containing the word "-ARGV" followed by another ARRAY
 #
@@ -1362,7 +1406,8 @@
 #  * Any other ARRAY
 #
 #    in which case Getopt::Declare::new() treats the array elements as a
-#    list of filenames, concatenates the contents of those files, and parses that.
+#    list of filenames, concatenates the contents of those files, and 
+#    parses that.
 #
 #    If the list does not denote any accessible file(s)
 #    Getopt::Declare::new() immediately returns zero. If matching files
@@ -1385,8 +1430,8 @@
 #  * Parameter data
 #
 #    For each successfully matched parameter, the Getopt::Declare object
-#    will contain a hash element. The key of that element will be the leading flag
-#    or parameter variable name of the parameter.
+#    will contain a hash element. The key of that element will be the 
+#    leading flag or parameter variable name of the parameter.
 #
 #    The value of the element will be another hash which contains
 #    the names and values of each distinct parameter variable and/or
@@ -1396,8 +1441,9 @@
 #    Float, String). List parameter variables generate Arrays.
 #
 #    As a special case, if a parameter consists of a single component
-#    (either a single flag or a single parameter variable), then the value for the
-#    corresponding hash key is not another hash, but the actual value matched.
+#    (either a single flag or a single parameter variable), then the value
+#    for the corresponding hash key is not another hash, but the actual 
+#    value matched.
 #
 #    The following example illustrates the various possibilities:
 #
@@ -1425,9 +1471,9 @@
 #
 #    The values which are assigned to the various hash elements are copied from
 #    the corresponding blocked-scoped variables which are available within
-#    actions. In particular, if the value of any of those block-scoped variables
-#    is changed within an action, that changed value is saved in the hash. For
-#    example, given the specification:
+#    actions. In particular, if the value of any of those block-scoped 
+#    variables is changed within an action, that changed value is saved in
+#    the hash. For example, given the specification:
 #
 #  	args = Getopt::Declare.new( %q{
 #
@@ -1455,12 +1501,14 @@
 #
 #  * The Getopt::Declare::usage() method
 #
-#    Once a Getopt::Declare object is created, its <tt>usage()</tt> method may be called
-#    to explicitly print out usage information corresponding to the specification
-#    with which it was built. See "Usage information" for more details.
-#    If the <tt>usage()</tt> method is called with an argument, that argument is passed
-#    to <tt>exit</tt> after the usage information is printed (the no-argument version of
-#    <tt>usage()</tt> simply returns at that point).
+#    Once a Getopt::Declare object is created, its <tt>usage()</tt> method 
+#    may be called to explicitly print out usage information corresponding 
+#    to the specification with which it was built. See "Usage information" 
+#    for more details.
+#    If the <tt>usage()</tt> method is called with an argument, that argument
+#    is passed to <tt>exit</tt> after the usage information is printed
+#    (the no-argument version of <tt>usage()</tt> simply returns at that
+#    point).
 #
 #
 #  * The Getopt::Declare::version() method
@@ -1471,8 +1519,8 @@
 #    Note that this implies that _all_ Getopt::Declare objects in a
 #    single program will print out identical version information.
 #
-#    Like the <tt>usage()</tt> method, if <tt>version</tt> is passed an argument, it
-#    will exit with that value after printing.
+#    Like the <tt>usage()</tt> method, if <tt>version</tt> is passed an 
+#    argument, it will exit with that value after printing.
 #
 #
 #  * The Getopt::Declare::parse() method
@@ -1539,7 +1587,6 @@
 #    specification, by extracting it from between the first "=for
 #    Getopt::Declare" and the next "=cut" appearing on +$stdin+:
 #
-#    =begin
 #    Just type in something, like:
 #
 #    =for Getopt::Declare
@@ -1547,8 +1594,6 @@
 #                 -a              Append mode
 #    =cut
 #
-#    =end
-#
 #    $/ = '=cut'
 #    if t = $stdin.readline
 #      t.sub!( /^=for\s+Getopt::Declare\s*\n(.*?)\n=cut/esm ) { 
@@ -1599,11 +1644,13 @@
 #
 #  * All actions and comments are deleted,
 #
-#  * any <tt>[ditto]</tt> directive is converted to an appropriate set of "ditto" marks,
+#  * any <tt>[ditto]</tt> directive is converted to an appropriate set of 
+#    "ditto" marks,
 #
 #  * any text in matching square brackets (including any directive) is deleted,
 #
-#  * any parameter variable type specifier (":i", ":n", ":/pat/", etc.) is deleted.
+#  * any parameter variable type specifier (":i", ":n", ":/pat/", etc.) is
+#    deleted.
 #
 #  Otherwise, the usage information displayed retains all the formatting
 #  present in the original specification.
@@ -1615,10 +1662,10 @@
 #  indicating how to determine the current version of the program (see
 #  "Version parameters").
 #
-#  The usage information is printed to <tt>$stdout</tt> and (since Getopt::Declare
-#  tends to encourage longer and better-documented parameter lists) if
-#  the IO::Pager> package is available, an IO::Pager> object is used to
-#  page out the entire usage documentation.
+#  The usage information is printed to <tt>$stdout</tt> and (since
+#  Getopt::Declare tends to encourage longer and better-documented parameter
+#  lists) if the IO::Pager> package is available, an IO::Pager> object is
+#  used to page out the entire usage documentation.
 #
 #  == Usage "decoration"
 #
@@ -1643,8 +1690,8 @@
 #
 #  The following specification demonstrates various forms of usage
 #  decoration. In fact, there are only four actual parameters (<tt>-in</tt>,
-#  <tt>-r</tt>, <tt>-p</tt>, and <tt>-out</tt>) specified. Note in particular that _leading_ tabs
-#  are perfectly acceptible in decorator lines.
+#  <tt>-r</tt>, <tt>-p</tt>, and <tt>-out</tt>) specified. Note in particular 
+#  that _leading_ tabs are perfectly acceptible in decorator lines.
 #
 #  	args = Getopt::Declare.new(<<-'EOPARAM');
 #
@@ -1735,7 +1782,8 @@
 #    specification (that is, it wasn't in the form: <_name_> or
 #    <_name_:_type_>).
 #
-#  * "Error: bad type in Getopt::Declare parameter variable specification near %s"
+#  * "Error: bad type in Getopt::Declare parameter variable specification
+#            near %s"
 #
 #    An unknown type specifier was used in a parameter variable type suffix.
 #
@@ -1745,9 +1793,10 @@
 #
 #  * "Error: unattached action in Getopt::Declare specification:\n %s"
 #
-#    An action was found for which there was no preceding parameter specification.
-#    This usually occurs because the trailing tab was omitted from the preceding
-#    parameter specification.
+#    An action was found for which there was no preceding parameter 
+#    specification.
+#    This usually occurs because the trailing tab was omitted from the
+#    preceding parameter specification.
 #
 #  * "Error: incomplete action in Getopt::Declare specification:\n %s"
 #
@@ -1758,7 +1807,8 @@
 #    The condition specified as part of the indicated <tt>[requires:...]</tt>
 #    directive was not a well-formed boolean expression. Common problems
 #    include: omitting a <tt>&&</tt>/<tt>||</tt> operator between two flags,
-#    mismatched brackets, or using <tt>and</tt>/<tt>or</tt> instead of <tt>&&</tt>/<tt>||</tt>.
+#    mismatched brackets, or using <tt>and</tt>/<tt>or</tt> instead of 
+#    <tt>&&</tt>/<tt>||</tt>.
 #
 #  * "Error: in generated command-line parser code:\n %s"
 #
@@ -1821,7 +1871,7 @@
 #
 #  Gonzalo Garramuno (GGarramuno@aol.com) Ruby Port, Minor Bug Fixes,
 #                                         Inline docs, and :d stdtype.
-## 
+# 
 #  = BUGS AND ANNOYANCES
 #
 #  There are undoubtedly serious bugs lurking somewhere in this code.
@@ -1835,7 +1885,7 @@
 #  = COPYRIGHT
 #
 #     Ruby Port:
-#         Copyright (c) 2004, Gonzalo Garramuno. All Rights Reserved.
+#         Copyright (c) 2004-2007, Gonzalo Garramuno. All Rights Reserved.
 #       This package is free software. It may be used, redistributed
 #       and/or modified under the terms of the Perl Artistic License
 #            (see http://www.perl.com/perl/misc/Artistic.html)
@@ -1848,14 +1898,18 @@
 #
 #  This Getopt::Declare module relies on a custom version of DelimScanner.rb,
 #  which is roughly a port of Perl's Text::Balanced.
-#  The main change added to that library was to add returning :suffix to several
-#  functions.  DelimScanner.rb is: 
+#  The main change added to that library was to add returning :suffix to 
+#  several functions.  DelimScanner.rb is: 
 # 
 #  Copyright (c) 2002, 2003 The FaerieMUD Consortium. Most rights reserved.
 # 
-#  This work is licensed under the Creative Commons Attribution License. To view
-#  a copy of this license, visit http://creativecommons.org/licenses/by/1.0 or
-#  send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California
-#  94305, USA.
-
+#  This work is licensed under the Creative Commons Attribution License. 
+#  To view a copy of this license, visit 
+#  http://creativecommons.org/licenses/by/1.0 or
+#  send a letter to 
+#
+#  Creative Commons
+#  559 Nathan Abbott Way, 
+#  Stanford, California 94305, USA.
+#
 

data/HISTORY.txt

@@ -1,3 +1,9 @@
+1.20 - Added support for using 3 spaces in addition to tabs for
+       parameter descriptions.
+       Added support for GNU -p, --param descriptions, for easier
+       GNU parameter support.
+       Fixed help description bug with [ditto] of single parameter flags.
+
 1.13 - Fixed bug that would always match parameters in a case insensitive
        way, as if [nocase] had been used.  This should speed the parser a 
        tiny bit.

data/Rakefile

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+rdoc_files = ["Declare.rdoc", 'HISTORY.txt']
+
+#
+# TASK: Gem specification and creation ('gem')
+#
+spec = Gem::Specification.new do |spec|
+  spec.name = "getopt-declare"
+  spec.version = '1.20'
+  spec.author = "Gonzalo Garramuno"
+  spec.email = 'ggarra@advancedsl.com.ar, GGarramuno@aol.com'
+  spec.homepage = 'http://www.rubyforge.org/projects/getoptdeclare/'
+  spec.summary = 'Getopt-Declare is a command-line argument parser.'
+  spec.require_path = "lib"
+  spec.autorequire = "Getopt/Declare"
+  spec.files = ["lib/Getopt/Declare.rb", "lib/Getopt/DelimScanner.rb", 
+                "Rakefile"]
+  spec.description = <<-"EOF"
+    Comprehensive and easy to use command-line parser library using
+    regular expressions.  Port of Damian Conway\'s Perl Getopt-Declare.
+EOF
+  # to fix emacs coloring bug
+  spec.extra_rdoc_files = rdoc_files
+  spec.has_rdoc = true
+  spec.test_files = Dir.glob('samples/*.rb')
+  spec.rubyforge_project = 'getoptdeclare'
+  spec.required_ruby_version = '>= 1.6.8'
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+end
+
+
+#
+# TASK: Run rdoc to document code ('rdoc')
+#
+html_dir = 'doc/html'
+library = 'Getopt/Declare'
+Rake::RDocTask.new('rdoc') do |t|
+  t.rdoc_files.include(rdoc_files, 'lib/**/*.rb')
+  t.main = 'doc/index.html'  # Main web page
+  t.title = "#{library} API documentation"
+  t.rdoc_dir = html_dir
+end
+
+
+#
+# TASK: Upload docs to rubyforge ('upload-docs')
+#
+desc 'Upload documentation to RubyForge.'
+task 'upload-docs' => ['rdoc'] do
+  rubyforge_user    = 'gga'
+  rubyforge_project = spec.rubyforge_project
+  rubyforge_path = "/var/www/gforge-projects/#{rubyforge_project}/"
+
+  sh "scp -r #{html_dir}/* #{rubyforge_user}@rubyforge.org:#{rubyforge_path}"
+end
+
+
+#
+# Main task
+#
+task :default => ['gem', 'upload-docs']

data/lib/Getopt/Declare.rb

@@ -1,11 +1,11 @@
 #
 #  Getopt::Declare - Declaratively Expressed Command-Line Arguments via Regular Expressions
 #
-#  Ruby port of Perl's Getopt::Declare, version 1.12, 
+#  Ruby port of Perl's Getopt::Declare, version 1.20, 
 #  released May 21, 1999.
 #
-#   	$Release Version: 1.12 $
-#       $Date: 2004/01/15 10:53:09 $
+#   	$Release Version: 1.20 $
+#       $Date: 2007/01/15 10:53:09 $
 #   	by Gonzalo Garramu�o
 #
 #  For detailed instructions, see Declare.rdoc file
@@ -26,6 +26,7 @@
 
 require "Getopt/DelimScanner"
 
+
 # Verifies that code is valid Ruby code.  returns false if not
 def valid_syntax?(code, fname = 'parser_code')
   eval("BEGIN {return true}\n#{code}", nil, fname, 0)
@@ -69,10 +70,14 @@ module Getopt
   # Main Class
   class Declare
 
-    VERSION = '1.12'
+    VERSION = '1.20'
 
     # For debugging, use [debug] and it will output the ruby code as .CODE.rb
-    @@debug = nil
+    @@debug = false
+
+    # Main separator used to distinguish arguments in Getopt/Declare spec.
+    # By default, one or more tabs or 3 spaces or more.
+    @@separator = '(?:\t+| {3})'
 
     # Class used to handle the beginning of options
     class StartOpt
@@ -108,7 +113,7 @@ module Getopt
     class EndOpt < StartOpt
       # Returns regex used matching end of options
       def matcher(g)
-	'())?'  # for emacs coloring we need a '
+	'())?' 
       end
     end  # EndOpt
 
@@ -123,7 +128,7 @@ module Getopt
 	@@stdtype = {
 	  ':i'	=> { 'pattern' => '(?:(?:%T[+-]?)%D+)' },
 	  ':n'	=> { 'pattern' => '(?:(?:%T[+-]?)(?:%D+(?:%T\.%D*)?' +
-	    '(?:%T[eE]%D+)?|%T\.%D+(?:%T[eE]%D+)?))',
+	    '(?:%T[eE](?:[+-])?%D+)?|%T\.%D+(?:%T[eE](?:[+-])?%D+)?))',
 	  },
 	  ':s'	=> { 'pattern' => '(?:%T(?:\S|\0))+' },
 	  ':qs'	=> { 'pattern' => %q#"(?:\\"|[^"])*"|'(?:\\'|[^"])*|(?:%T(?:\S|\0))+#
@@ -275,7 +280,7 @@ module Getopt
 	end
 
 	c = conversion
-	c = "\n	          _VAL_ = _VAL_#{c}" if not c.empty?
+	c = "\n	          _VAL_ = _VAL_#{c}" if c
 
 	code = <<-EOS
 	          _VAR_ = %q|<#{@name}>|
@@ -309,7 +314,7 @@ EOS
 	   return '.to_f'
 	 end
        }
-       return ''
+       return nil
      end
 
      # Return string with code to cache argument in Getopt::Declare's cache
@@ -365,7 +370,7 @@ EOS
 
        # Handle conversion to proper type
        c = conversion
-       if not c.empty?
+       if c
 	 code << "		  #{@name}.map! { |i| i#{c} }\n"
        end
 
@@ -503,16 +508,8 @@ EOS
       end
     end
 
-    attr_accessor :flag
-    attr_accessor :args
-    attr_accessor :actions
-    attr_accessor :ditto
-    attr_accessor :required
-    attr_accessor :requires
-    attr_accessor :id
-    attr_accessor :repeatable
-    attr_accessor :desc
-
+    attr_accessor :flag, :args, :actions, :ditto, :nocase
+    attr_accessor :required, :requires, :id, :repeatable, :desc
 
 
     # Constructor
@@ -530,6 +527,7 @@ EOS
       @id       = @@nextid
       @desc	= spec.dup
       @items	= 0
+      @nocase   = false
 
       @desc.sub!(/\A\s*(.*?)\s*\Z/,'\1')
 
@@ -570,14 +568,14 @@ EOS
 
 	    # PUNCTUATION
 	  elsif spec.sub!( /\A(\s*)((\\.|[^\] \t\n\[<])+)/, "" )
-	    ows, punct = [ "#$1", "#$2" ]
+	    ows, punct = $1, $2
 	    punct.gsub!( /\\(?!\\)(.)/, '\1' )
 
 	    if first == 1
 	      @flag = punct
 	      @@flags.push( punct )
 	    else
-	      @args.push( Punctuator.new(punct,!ows.length()) )
+	      @args.push( Punctuator.new(punct, !(ows.size > 0)) )
 	      @items += 1
 	    end
 
@@ -587,7 +585,6 @@ EOS
 	ensure
 	  first = 0
 	end
-
       end # while
 
 
@@ -608,7 +605,7 @@ EOS
       flag = @flag
       clump = owner.clump
       i = 0
-      nocase = ((Getopt::Declare::_nocase() || @nocase) ? 'i' : '')
+      nocasei = ((Getopt::Declare::nocase || @nocase) ? 'i' : '')
 
       code << "          catch(:paramout) do\n"
       code += (!@repeatable) ? "            while !_FOUND_['" + name() + "']" :
@@ -634,7 +631,7 @@ EOS
 
 	code << '
                   _args && _pos = gindex( _args, /\G(?:\s|\0)*' + 
-	  Regexp::quote(flag) + boundary + '/' + nocase + ", _pos) or throw(:paramout) 
+	  Regexp::quote(flag) + boundary + '/' + nocasei + ", _pos) or throw(:paramout) 
                   unless @_errormsg
 		    @_errormsg = %q|incorrect specification of '" + flag + "' parameter|
                   end
@@ -663,7 +660,7 @@ EOS
 	  code << @args[i].ows(@args[i].matcher(trailer[i]))
 	}
 
-	code << '/x' + nocase + ", _pos ) or throw(:paramout)\n"
+	code << '/x' + nocasei + ", _pos ) or throw(:paramout)\n"
       end # if @args
 
       0.upto( argcount ) { |i|
@@ -694,16 +691,25 @@ EOS
 	code << "\n                  " + action + "\n"
       end
 
-      if (flag && @items==0)
+      if flag && @items==0
 	code << "\n                  @cache['#{flag}'] = '#{flag}'\n"
+        if @ditto
+          code << "\n                  @cache['#{@ditto.flag}'] = '#{flag}'\n"
+        end
       end
 
       if @items > 1
 	code << "                  @cache['#{self.name}'] = {} unless @cache['#{self.name}']\n"
+        if @ditto
+          code << "\n                  @cache['#{@ditto.name}'] = {} unless @cache['#{@ditto.name}']\n"
+        end
       end
 
       for subarg in @args
-	code << subarg.cachecode(self.name(),@items)
+	code << subarg.cachecode(self.name,@items)
+        if ditto
+	code << subarg.cachecode(@ditto.name,@items)
+        end
       end
 
       if flag =~ /\A([^a-z0-9]+)/i
@@ -742,10 +748,9 @@ EOS
 
   private
 
-  # Check if global ignore case in regex is defined
-  def Declare._nocase(*t)
-    @@nocase = t[0] if t[0]
-    @@nocase
+  class << self
+    @nocase = false
+    attr_accessor :nocase
   end
 
   #
@@ -782,13 +787,13 @@ EOS
   # Given an array or hash, flatten them to a string
   def flatten(val, nested = nil)
     case val
-      when Array
+    when Array
       return val.map{ |i| flatten(i,1) }.join(" ")
-      when Hash
+    when Hash
       return val.keys().map{ |i| nested || 
 	  i =~ /^-/ ? [i, flatten(val[i],1)] : 
                       [flatten(val[i],1)] }.join(" ")
-      else
+    else
       return val
     end
   end
@@ -851,9 +856,9 @@ EOS
 
     if desc =~ /\[no\s*case\]/i
       if arg
-	arg.nocase = true #should it be _nocase
+	arg.nocase = true
       else 
-	_nocase( true )
+	nocase = true
       end
     end
 
@@ -935,7 +940,7 @@ EOS
       originaldesc.gsub!(/""/,'" ')
     end
 
-    "#{originaldesc}#{extra}"
+    "#{originaldesc}#{extra}\n"
   end
 
   # Check mutex conditions
@@ -961,6 +966,17 @@ EOS
     end
   end
 
+  # Returns a regex to match a single argument line
+  def re_argument
+    /\A(.*?\S.*?#{@@separator})(.*?\n)/
+  end
+
+  # Returns a regex to keep matching a multi-line description
+  # for an argument.
+  def re_more_desc
+    /\A((?![ \t]*(\{|\n)|.*?\S.*?#{@@separator}.*?\S).*?\S.*\n)/
+  end
+
   public
 
   # Constructor
@@ -993,9 +1009,10 @@ EOS
     _strict = false
     _all_repeatable = false
     _lastdesc = nil
-    Getopt::Declare::_nocase( false )
+    Getopt::Declare::nocase = false
     Getopt::Declare::ScalarArg::_reset_stdtype()
 
+
     # CONSTRUCT GRAMMAR
     while i.length > 0
 
@@ -1047,21 +1064,39 @@ EOS
 
 
       # ARG + DESC:
-      if i.sub!(/\A(.*?\S.*?)(\t.*\n)/,"")
-	spec = "#$1"
+      if i.sub!(re_argument,"")
+	spec = "#$1".strip
 	desc = "#$2"
 	_strict ||= desc =~ /\[strict\]/
 
-	desc += "#$1" while i.sub!(/\A((?![ \t]*(\{|\n)|.*?\S.*?\t.*?\S).*?\S.*\n)/,"")
+        while i.sub!(re_more_desc,"")
+          desc += "#$1"
+        end
 	
 	ditto = nil
-	ditto = 1 if _lastdesc and desc.sub!(/\A\s*\[ditto\]/,_lastdesc)
-	_lastdesc = desc
+        if _lastdesc and desc.sub!(/\A\s*\[ditto\]/,_lastdesc)
+          ditto = arg
+        else
+          _lastdesc = desc
+        end
+
+        # Check for GNU spec line like:  -d, --debug
+        arg = nil
+        if spec =~ /(-[\w_\d]+),\s+(--[\w_\d]+)(\s+.*)?/
+          specs = ["#$1#$3", "#$2#$3"]
+          specs.each { |spec|
+            arg = Arg.new(spec,desc,ditto)
+            _args.push( arg )
+            _infer(desc, arg, _mutex)
+            ditto = arg
+          }
+        else
+          arg = Arg.new(spec,desc,ditto)
+          _args.push( arg )
+          _infer(desc, arg, _mutex)
+        end
 
-	arg = Arg.new(spec,desc,ditto)
-	_args.push( arg )
 
-	_infer(desc, arg, _mutex)
 	next
       end
 
@@ -1222,10 +1257,6 @@ EOS
     Getopt::Declare::ScalarArg::addtype(t)
   end
 
-
-  @@nocase = false
-
-
   # Print out version information and maybe exit
   def version(*t)
     prog = "#{$0}"
@@ -1278,15 +1309,14 @@ EOS
 
 
       # ARG + DESC:
-      if t.sub!(/\A(.*?\S.*?\t+)(.*?\n)/,"")
+      if t.sub!(re_argument,"")
 	decfirst = 0 unless !decfirst.nil?
 	spec = "#$1".expand_tabs!()
 	desc = "#$2".expand_tabs!()
 
-	t.gsub!(/\A((?![ \t]*(\{|\n)|.*?\S.*?\t.*?\S).*?\S.*\n)/) { |i|
-	  desc += "#$1".expand_tabs!()
-	  ""
-	}
+	while t.gsub!(re_more_desc, '')
+	  desc += "#$1".expand_tabs!
+	end
 
 	next if desc =~ /\[undocumented\]/i
 

metadata

@@ -1,21 +1,21 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11
+rubygems_version: 0.9.0
 specification_version: 1
 name: getopt-declare
 version: !ruby/object:Gem::Version 
-  version: "1.13"
-date: 2006-05-17 00:00:00 -03:00
+  version: "1.20"
+date: 2007-01-17 00:00:00 -03:00
 summary: Getopt-Declare is a command-line argument parser.
 require_paths: 
 - lib
 email: ggarra@advancedsl.com.ar, GGarramuno@aol.com
 homepage: http://www.rubyforge.org/projects/getoptdeclare/
 rubyforge_project: getoptdeclare
-description: Comprehensive and easy to use command-line parser library using regular expressions.  Port of Conway's Perl Getopt-Declare.
+description: Comprehensive and easy to use command-line parser library using regular expressions.  Port of Damian Conway's Perl Getopt-Declare.
 autorequire: Getopt/Declare
 default_executable: 
 bindir: bin
-has_rdoc: false
+has_rdoc: true
 required_ruby_version: !ruby/object:Gem::Version::Requirement 
   requirements: 
   - - ">="
@@ -25,14 +25,15 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: 
 - Gonzalo Garramuno
 files: 
 - lib/Getopt/Declare.rb
 - lib/Getopt/DelimScanner.rb
+- Rakefile
 - Declare.rdoc
 - HISTORY.txt
-- getoptdeclare.gemspec
 test_files: 
 - samples/cmdline_basic.rb
 - samples/cmdline_mid.rb
@@ -57,7 +58,6 @@ rdoc_options: []
 extra_rdoc_files: 
 - Declare.rdoc
 - HISTORY.txt
-- getoptdeclare.gemspec
 executables: []
 
 extensions: []

data/getoptdeclare.gemspec

@@ -1,22 +0,0 @@
-require "rubygems"
-
-spec = Gem::Specification.new do |spec|
-	spec.name = "getopt-declare"
-	spec.version = '1.13'
-	spec.author = "Gonzalo Garramuno"
-	spec.email = 'ggarra@advancedsl.com.ar, GGarramuno@aol.com'
-	spec.homepage = 'http://www.rubyforge.org/projects/getoptdeclare/'
-	spec.summary = 'Getopt-Declare is a command-line argument parser.'
-	spec.require_path = "lib"
-	spec.autorequire = "Getopt/Declare"
-	spec.files = ["lib/Getopt/Declare.rb", "lib/Getopt/DelimScanner.rb"]
-	spec.description = <<-EOF
-    Comprehensive and easy to use command-line parser library using
-    regular expressions.  Port of Conway's Perl Getopt-Declare.
-EOF
-	spec.extra_rdoc_files = ["Declare.rdoc", "HISTORY.txt", "getoptdeclare.gemspec"]
-	spec.has_rdoc = false
-	spec.test_files = Dir.glob('samples/*.rb')
-	spec.rubyforge_project = 'getoptdeclare'
-	spec.required_ruby_version = '>= 1.6.8'
-end