getopt-declare 1.28 → 1.29

data/samples/cmdline_usage.rb

@@ -0,0 +1,28 @@
+#!/bin/env ruby
+
+require "Getopt/Declare"
+
+#  In the next 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>).
+#
+#  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").
+#
+
+args = Getopt::Declare.new( <<-'EOSPEC' )
+
+  		-a		Append mode
+  		-b		Back-up mode
+  		-bu		[ditto]
+  		-c <file>	Copy mode
+  		-d [<file>]	Delete mode
+  		-e[xec]		Execute mode
+
+  		[cluster:singles]
+EOSPEC
+
+args.usage 

data/samples/demo_cmdline.rb

@@ -55,7 +55,7 @@ File creation options:
 Garbling options:
 
 	-g [<seed:i>]		Garble output with optional seed [requires: +c]
-                                { print "garbling with $seed\n"; }
+                                { print "garbling with #{seed}\n"; }
 	-i			Case insensitive garbling [required]
                                 { print "insensitive\n"; }
 	-s			Case sensitive garbling 

metadata

@@ -1,108 +1,105 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.1
-specification_version: 1
 name: getopt-declare
 version: !ruby/object:Gem::Version 
-  version: "1.28"
-date: 2007-07-09 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: getoptdeclare.rubyforge.org
-rubyforge_project: getoptdeclare
-description: Comprehensive and easy to use command-line parser library using regular expressions.  Port of Damian Conway's Perl Getopt-Declare.
-autorequire: 
-default_executable: 
-bindir: bin
-has_rdoc: true
-required_ruby_version: !ruby/object:Gem::Version::Requirement 
-  requirements: 
-  - - ">"
-    - !ruby/object:Gem::Version 
-      version: 0.0.0
-  version: 
+  hash: 53
+  prerelease: false
+  segments: 
+  - 1
+  - 29
+  version: "1.29"
 platform: ruby
-signing_key: 
-cert_chain: 
-post_install_message: 
 authors: 
 - Gonzalo Garramuno
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-19 00:00:00 -03:00
+default_executable: 
+dependencies: []
+
+description: "\tInteractive Fiction Mapping Tool.\n"
+email: ggarra13@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- Manifest.txt
+- README.txt
 files: 
-- lib
-- lib/Getopt
+- getopt-declare.gemspec
 - lib/Getopt/Declare.rb
+- lib/Getopt/Declare2.rb
 - lib/Getopt/DelimScanner.rb
-- Declare.rdoc
-- HISTORY.txt
-- README.txt
-- Manifest.txt
-- samples
+- samples/cmdline_array.rb
 - samples/cmdline_basic.rb
+- samples/cmdline_code.rb
+- samples/cmdline_defer.rb
+- samples/cmdline_file.rb
+- samples/cmdline_finish.rb
+- samples/cmdline_inlines.rb
 - samples/cmdline_mid.rb
+- samples/cmdline_noargv.rb
 - samples/cmdline_parameters.rb
-- samples/cmdline_regex.rb
 - samples/cmdline_pvtype.rb
-- samples/cmdline_code.rb
 - samples/cmdline_pvtype2.rb
-- samples/cmdline_file.rb
+- samples/cmdline_regex.rb
+- samples/cmdline_singles.rb
+- samples/cmdline_usage.rb
+- samples/demo_cmdline.rb
 - samples/demo_csv.rb
-- samples/demo_shell.rb
 - samples/demo_interp.rb
-- samples/demo_cmdline.rb
-- samples/cmdline_noargv.rb
-- samples/cmdline_array.rb
-- samples/cmdline_defer.rb
-- samples/cmdline_singles.rb
-- samples/cmdline_inlines.rb
-- samples/cmdline_finish.rb
-- Rakefile
-- test
-- test/test_cmdline_cmdline.rb
-- test/test_cmdline_basic.rb
-- test/test_cmdline_finish.rb
-- test/test_cmdline_mid.rb
-- test/test_cmdline_parameters.rb
-- test/test_cmdline_pvtype2.rb
-- test/test_cmdline_pvtype.rb
-- test/test_cmdline_regex.rb
-- test/test_demo_csv.rb
+- samples/demo_shell.rb
 - test/test_cluster_singles.rb
 - test/test_cmdline_array.rb
-- test/test_cmdline_require.rb
-test_files: 
-- test/test_cmdline_cmdline.rb
 - test/test_cmdline_basic.rb
+- test/test_cmdline_cmdline.rb
 - test/test_cmdline_finish.rb
 - test/test_cmdline_mid.rb
 - test/test_cmdline_parameters.rb
-- test/test_cmdline_pvtype2.rb
 - test/test_cmdline_pvtype.rb
+- test/test_cmdline_pvtype2.rb
 - test/test_cmdline_regex.rb
-- test/test_demo_csv.rb
 - test/test_cmdline_require.rb
-- test/test_cluster_singles.rb
-- test/test_cmdline_array.rb
-rdoc_options: 
-- --main
-- README.txt
-extra_rdoc_files: 
-- HISTORY.txt
-- README.txt
+- test/test_demo_csv.rb
 - Manifest.txt
-executables: []
+- README.txt
+has_rdoc: true
+homepage: http://www.rubyforge.org/projects/getoptdeclare/
+licenses: []
 
-extensions: []
+post_install_message: 
+rdoc_options: []
 
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 55
+      segments: 
+      - 1
+      - 8
+      - 0
+      version: 1.8.0
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: hoe
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Version::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: 1.2.1
-    version: 
+rubyforge_project: getopt-declare
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A regex command-line parsing library.
+test_files: []
+

data/Declare.rdoc

@@ -1,1943 +0,0 @@
-#
-#  = NAME
-#
-#  Getopt::Declare - Declaratively Expressed Command-Line Arguments via Regular Expressions
-#
-#  = VERSION
-#
-#  This document describes version 1.25 and later of Getopt::Declare,
-#  Released Jan 21, 2007 for Ruby.
-#
-#  Original Perl's Getopt-Declare v1.09, Released May 21, 1999.
-#
-#  = SYNOPSIS
-#
-#   require "Getopt/Declare"
-#   args = Getopt::Declare.new(<<'EOF')
-#
-#   -q, --quiet                 quiet
-#   -f, --files <files:if>...   input files
-#   -n, --number  <num:n>       a float number [required]
-#   -i, --integer <num:i>       an integer number
-#
-#   EOF
-#
-#   p args['-q']
-#   p args['-f']
-#   p args.unused
-#
-#
-#  = DESCRIPTION
-#
-#  == Overview
-#
-#  Getopt::Declare is <em>yet another</em> command-line argument parser,
-#  one which is specifically designed to be powerful but exceptionally
-#  easy to use.
-#
-#  To parse the command-line in +ARGV+, one simply creates a
-#  Getopt::Declare object, by passing Getopt::Declare::new() a
-#  specification of the various parameters that may be encountered:
-#
-#  	args = Getopt::Declare.new(specification)
-#
-#  The specification is a single string such as this:
-#
-#  	specification = %q(
-#
-#  		-a		Process all data
-#
-#  		-b <t:n>	Set mean byte length threshold to <t>
-#  					{ bytelen = t }
-#
-#  		+c <FILE>	Create new file <FILE>
-#
-#  		--del 		Delete old file
-#  					{ delold() }
-#
-#  		delete 		[ditto]
-#
-#  		e <h:i>x<w:i>	Expand image to height <h> and width <w>
-#  					{ expand(h,w) }
-#
-#  		-F <file>...	Process named file(s)
-#  					{ defer { file.each {|i| 
-#                                                   process(i) } } }
-#
-#  		=getrand [<n:i>] Get a random number
-#  				 (or, optionally, <n> of them)
-#  					{ n = 1 unless !n.empty? }
-#
-#  		--		Traditionally indicates end of arguments
-#  					{ finish(1) }
-#  	)
-#
-#  in which the syntax of each parameter is declared, along with a
-#  description and (optionally) one or more actions to be performed when
-#  the parameter is encountered. The specification string may also
-#  include other usage formatting information (such as group headings or
-#  separators) as well as standard Ruby comments (which are ignored).
-#
-#  Calling Getopt::Delare::new() parses the contents of the array +ARGV+,
-#  extracting any arguments which match the parameters defined in the
-#  specification string, and storing the parsed values as hash elements
-#  within the new Getopt::Declare object being created.
-#
-#  Other features of the Getopt::Declare package include:
-#
-#  * The use of full Ruby regular expressions to constrain matching
-#    of parameter components.
-#
-#  * Automatic generation of error, usage and version information.
-#
-#  * 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+
-#
-#  * Declarative specification of various inter-parameter relationships (for
-#    example, two parameters may be declared mutually exclusive and this
-#    relationship will then be automatically enforced).
-#
-#  * Intelligent clustering of adjacent flags (for example: the
-#    command-line sequence "-a -b -c" may be abbreviated to "-abc", unless
-#    there is also a <tt>-abc</tt> flag declared).
-#
-#  * Selective or global case-insensitivity of parameters.
-#
-#  * 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
-#  terms (such as "argument", "parameter", "option", "flag", etc.)
-#  frequently being used interchangeably and inconsistently in the various
-#  Getopt packages available. In this documentation, the following
-#  terms are used consistently: 
-#
-#  * <b>"command-line"</b>
-#
-#    The space-separated concatenation of the elements of the array +ARGV+
-#    at the time a Getopt::Declare object is created.
-#
-#  * <b>"parameter specification" (or just "parameter")</b>
-#
-#    A specification of a single entity which may appear in the
-#    command-line. Always includes at least one syntax for the entity.
-#    Optionally may include other _variant>_ syntaxes, one or more
-#    _descriptions_ of the entity, and/or _actions_ to be performed when
-#    the entity is encountered. For example, the following is a single
-#    parameter specification (with two variants):
-#
-#      --window <height> x <width>	    Set window to <height> by <width>
-#  					{ setwin(width,height) }
-#
-#      --window <h>x<w>@<x>,<y>	    Set window size and centroid
-#  					{ setwin(w,h,x,y) }
-#
-#
-#  * <b>"argument"</b>
-#
-#    A substring of the command-line which matches a single parameter variant.
-#    Unlike some other Getopt packages, in Getopt::Declare an argument
-#    may be a single element of +ARGV+, or part of a single +ARGV+ element,
-#    or the concatenation of several adjacent +ARGV+ elements.
-#
-#
-#  * <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_,
-#    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.
-#
-#
-#  * <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.
-#
-#
-#  * <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.
-#
-#
-#  * <b>"parameter punctuator" (or just "punctuator")</b>
-#
-#    A literal sequence of characters (within a parameter specification)
-#    which will appear in any argument matching that parameter. In the above
-#    example, the literals +x+ and <tt>@</tt> are punctuators.
-#
-#
-#  * <b>"parameter description"</b>
-#
-#    A textual description of the purpose and/or use of a particular variant of
-#    parameter. In the above examples, the string:
-#
-#  	Set window to <height> by <width>
-#
-#    is a parameter description.
-#
-#
-#  * <b>"parameter action" (or just "action")</b>
-#
-#    A block of Ruby code to be executed in response to encountering a specific
-#    parameter. In the above example:
-#
-#  	{ setwin(width,height) }
-#
-#    is a parameter action.
-#
-#  * <b>"parameter variants"</b>
-#
-#    One or more different syntaxes for a single parameter, all sharing
-#    the same leading flag, but having different trailing parameter
-#    variables and/or punctuators. Getopt::Declare considers all parameter
-#    definitions with the same leading flag to be merely variant forms of
-#    a single "underlying" parameter. The above example shows two parameter
-#    variants for the <tt>--window</tt> parameter.
-#
-#
-#  == Parameter definitions
-#
-#  As indicated above, a parameter specification consists of three
-#  parts: the parameter definition, a textual description, and any
-#  actions to be performed when the parameter is matched.
-#
-#  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 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:
-#
-#  	-v				
-#  	in=<infile>			
-#  	+range <from>..<to>		
-#  	--lines <start> - <stop>	
-#  	ignore bad lines		
-#  	<outfile>				
-#
-#  Note that each of the above examples has to have at least one trailing tab
-#  (even if here Ruby's rdoc strips them). Note too that this hodge-podge of
-#  parameter styles is certainly not recommended within a single program,
-#  but is shown so as to illustrate some of the range of parameter syntax
-#  conventions Getopt::Declare supports.
-#
-#  The spaces between components of the parameter definition are optional but
-#  significant, both in the definition itself and in the arguments that
-#  the definition may match. If there is no space between components in the
-#  specification, then no space is allowed between corresponding arguments
-#  on the command-line. If there _is_ space between components of the
-#  specification, then space between those components is optional on the
-#  command-line.
-#
-#  For example, the <tt>--lines</tt> parameter above matches:
-#
-#  	--lines1-10
-#  	--lines 1-10
-#  	--lines 1 -10
-#  	--lines 1 - 10
-#  	--lines1- 10
-#
-#  If it were instead specified as:
-#
-#  	--lines <start>-<stop>	
-#
-#  then it would match only:
-#
-#  	--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
-#  introduces an optional parameter component - see
-#  "Optional parameter components".
-#
-#
-#  == Types of parameter variables
-#
-#  By default, a parameter variable will match a single blank-terminated
-#  or comma-delimited string. For example, the parameter:
-#
-#  	-val <value>	
-#
-#  would match any of the following the arguments:
-#
-#  	-value                  # <value> <- "ue"
-#  	-val abcd               # <value> <- "abcd"
-#  	-val 1234               # <value> <- "1234"
-#  	-val "a value"          # <value> <- "a value"
-#
-#
-#  It is also possible to restrict the types of values which may be
-#  matched by a given parameter variable. For example:
-#
-#  	-limit <threshold:n>	Set threshold to some (real) value
-#  	-count <N:i>		Set count to <N> (must be an integer)
-#
-#  If a parameter variable is suffixed with ":n", it will match any
-#  reasonable numeric value, whilst the ":i" suffix restricts a
-#  parameter variable to only matching integer values. 
-#  These two "type specifiers" are the simplest examples of a much more
-#  powerful mechanism, which allows parameter variables to be restricted
-#  to matching any specific regular expression. See "Defining new
-#  parameter variable types".
-#
-#  Parameter variables are treated as scalars by default, but this too
-#  can be altered. Any parameter variable immediately followed by
-#  an ellipsis (<tt>...</tt>) is treated as a list variable, and matches its
-#  specified type sequentially as many times as possible. For example,
-#  the parameter specification:
-#
-#  	-pages <page:i>...	
-#
-#  would match either of the following arguments:
-#
-#  	-pages 1
-#  	-pages 1 2 7 20
-#
-#  Note that both scalar and list parameter variables are "respectful" of the
-#  flags of other parameters as well as their own trailing punctuators.
-#  For example, given the specifications:
-#
-#  	-a			
-#  	-b <b_list>...		
-#  	-c <c_list>... ;	
-#
-#  The following arguments will be parsed as indicated:
-#
-#  	-b -d -e -a             # <b_list>  <-  ("-d", "-e")
-#  	-b -d ;                 # <b_list>  <-  ("-d", ";")
-#  	-c -d ;                 # <c_list>  <-  ("-d")
-#
-#  List parameter variables are also "repectful" of the needs of
-#  subsequent parameter variables. That is, a parameter specification
-#  like:
-#
-#  	-copy <files>... <dir>	
-#
-#  will behave as expected, putting all but the last string after the 
-#  <tt>-copy</tt> flag into the parameter variable <tt>files</tt>, while
-#  the very last string is assigned to <tt>dir</tt>.
-#
-#
-#  == Optional parameter components
-#
-#  Except for the leading flag, any part of a parameter definition
-#  may be made optional by placing it in square brackets.
-#  For example:
-#
-#  	+range <from> [..] [<to>]
-#
-#  which matches any of:
-#
-#  	+range 1..10
-#  	+range 1..
-#  	+range 1 10
-#  	+range 1
-#
-#  List parameter variables may also be made optional (the ellipsis must
-#  follow the parameter variable name immediately, so it goes _inside_
-#  the square brackets):
-#
-#  	-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:
-#
-#  	-range <from> [.. [<to>] ]
-#
-#  Scalar optional parameter variables (such as [<tt>to</tt>]>)
-#  are given undefined values if they are skipped during a successful 
-#  parameter match. List optional parameter variables (such as
-#  [<tt>page</tt>...]) are assigned an empty list if unmatched.
-#
-#  One important use for optional punctuators is to provide abbreviated
-#  versions of specific flags. For example:
-#
-#  	-num[eric]		# Match "-num" or "-numeric"
-#  	-lexic[ographic]al	# Match "-lexical" or "-lexicographical"
-#  	-b[ells+]w[histles]	# Match "-bw" or "-bells+whistles"
-#
-#  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 definitions following GNU's conventions, within a single line.
-#  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
-#  variant) is optional, but strongly recommended. Apart from providing 
-#  internal documentation, parameter descriptions are used in the 
-#  automatically-generated usage information provided by Getopt::Declare.
-#
-#  Descriptions may be placed after the tab(s) following the
-#  parameter definition and may be continued on subsequent lines,
-#  provided those lines do not contain any tabs after the first
-#  non-whitespace character (because any such line will instead be
-#  treated as a new parameter specification). The description is
-#  terminated by a blank line, an action specification (see below) or
-#  another parameter specification.
-#
-#  For example:
-#
-#  	-v				Verbose mode
-#  	in=<infile>			Specify input file
-#  					(will fail if file does not exist)
-#
-#  	+range <from>..<to>		Specify range of columns to consider
-#  	--lines <start> - <stop>	Specify range of lines to process
-#
-#  	ignore bad lines		Ignore bad lines :-)
-#
-#  	<outfile>			Specify an output file
-#
-#  The parameter description may also contain special directives which
-#  alter the way in which the parameter is parsed. See the various
-#  subsections of "ADVANCED FEATURES" for more information.
-#
-#
-#  == Actions
-#
-#  Each parameter specification may also include one or more blocks of
-#  Ruby code, specified in a pair of curly brackets (which _must_ start on
-#  a new line).
-#
-#  Each action is executed as soon as the corresponding parameter is
-#  successfully matched in the command-line (but see "Deferred actions"
-#  for a means of delaying this response).
-#
-#  For example:
-#
-#  	-v	Verbose mode
-#  			{ $verbose = 1 }
-#  	-q	Quiet mode
-#  			{ $verbose = 0 }
-#
-#  Actions are executed (as +begin+ blocks) in the package in which the
-#  Getopt::Declare object containing them was created. Hence they
-#  have access to all package variables and functions in that namespace.
-#
-#  In addition, each parameter variable belonging to the corresponding
-#  parameter is made available as a (block-scoped) Ruby variable with the
-#  same name. For example:
-#
-#  	+range <from>..<to>	Set range
-#  					{ setrange(from, to) }
-#
-#  	-list <page:i>...	Specify pages to list
-#  					{ page.each { |i|
-#  						list(i) if i > 0
-#  					  }
-#  					}
-#
-#  Note that single parameter variables become scalar Ruby variables,
-#  all matching their type (Fixnum, Float, String) and list parameter 
-#  variables become Ruby arrays.
-#
-#
-#  == Predefined variables available in actions
-#
-#  Within an action the following variables are also available:
-#
-#  * <tt>\_PARAM_</tt>  String
-#
-#    Stores the identifier of the current parameter: either the leading
-#    flag or, if there is no leading flag, the name of the first parameter
-#    variable.
-#
-#  * <tt>\_PUNCT_</tt>  Hash
-#
-#    Stores the substring matched by each punctuator in the current parameter.
-#    The hash is indexed by the punctuator itself. The main purpose of this 
-#    variable is to allow actions to check whether optional punctuators were
-#    in fact matched.
-#
-#    For example:
-#
-#  	-v[erbose]	Set verbose mode
-#  			(doubly verbose if full word used)
-#  			    { if _PUNCT_["erbose"]
-#  				verbose = 2      
-#  			      else
-#  			        verbose = 1
-#                             end
-#  			    }
-#
-#  * <tt>\_FOUND_</tt>  Hash
-#
-#    This hash stores boolean values indicating whether or not a given
-#    parameter has already been found. The hash keys are the leading flags
-#    or parameter variables of each parameter. For instance, the following
-#    specification makes the <tt>-q</tt> and <tt>-v</tt> parameters mutually 
-#    exclusive (but see "Parameter dependencies" for a _much_ easier way 
-#    to achieve this effect):
-#
-#  	-v	Set verbose mode
-#  			{ raise "Can't be verbose *and* quiet!\n" if
-#  				_FOUND_["-q"]
-#  			}
-#
-#  	-q	Set quiet mode
-#  			{ raise "Can't be quiet *and* verbose!\n" if
-#  				_FOUND_["-v"]
-#  			}
-#
-#    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.
-#
-#
-#  Note that, although numerous other internal variables on which the
-#  generated parser relies are also visible within parameter actions,
-#  accessing any of them may have Dire Consequences. Moreover, these
-#  other variables may no longer be accessible (or even present) in
-#  future versions of Getopt::Declare. All such internal variables
-#  have names beginning with an underscore. Avoiding such variables names
-#  will ensure there are no conflicts between actions and the parser
-#  itself.
-#
-#
-#  == The command-line parsing process
-#
-#  Whenever a Getopt::Declare object is created, the current command-line
-#  is parsed by sequentially, by attempting to match each parameter
-#  in the object's specification string against the current elements in the
-#  +ARGV+ array (but see "Parsing from other sources"). The order
-#  in which parameters are tried against +ARGV+ is determined by
-#  three rules:
-#
-#  1. Parameters with longer flags are tried first. Hence the command-line
-#     argument "-quiet" would be parsed as matching the parameter 
-#     <tt>-quiet</tt> rather than the parameter <tt>-q <string></tt>, even 
-#     if the <tt>-q</tt> parameter was defined first.
-#
-#  2. Parameter _variants_ with the most components are
-#     matched first. Hence the argument "-rand 12345" would be parsed as 
-#     matching the parameter variant <tt>-rand <seed></tt>, rather than the
-#     variant <tt>-rand</tt>, even if the "shorter" <tt>-rand</tt> variant 
-#     was defined first.
-#
-#  3. Otherwise, parameters are matched in the order they are defined.
-#
-#  Elements of +ARGV+ which do not match any defined parameter are collected
-#  during the parse and are eventually put back into +ARGV+
-#  (see "Strict and non-strict command-line parsing").
-#
-#
-#  = ADVANCED FEATURES
-#
-#  == Case-insensitive parameter matching
-#
-#  By default, a Getopt::Declare object parses the command-line in
-#  a <em>case-sensitive</em> manner. The <tt>[nocase]</tt> directive enables 
-#  a specific  parameter (or, alternatively, _all_ parameters) to be matched
-#  case-insensitively.
-#
-#  If a <tt>[nocase]</tt> directive is included in the description of a
-#  specific parameter variant, then that variant (only) will be matched
-#  without regard for case. For example, the specification:
-#
-#  	-q	Quiet mode [nocase]
-#
-#  	-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.
-#
-#  If a <tt>[nocase]</tt> directive appears anywhere _outside_ a parameter 
-#  description, then the entire specification is declared case-insensitive 
-#  and all parameters defined in that specification are matched without 
-#  regard to case.
-#
-#
-#  == Termination and rejection
-#
-#  It is sometimes useful to be able to terminate command-line
-#  processing before all arguments have been parsed. To this end,
-#  Getopt::Declare provides a special local operator (+finish+) which
-#  may be used within actions. The +finish+ operator takes a single optional
-#  argument. If the argument is true (or omitted),
-#  command-line processing is terminated at once (although the current
-#  parameter is still marked as having been successfully matched). For
-#  example:
-#
-#  	--	Traditional argument list terminator
-#  			{ finish }
-#
-#  	-no--	Use non-traditional terminator instead
-#  			{ nontrad = 1 }
-#
-#  	##	Non-traditional terminator (only valid if -no-- flag seen)
-#  			{ finish(nontrad) }
-#
-#  It is also possible to reject a single parameter match from within an
-#  action (and then continue trying other candidates). This allows
-#  actions to be used to perform more sophisticated tests on the type of
-#  a parameter variable, or to implement complicated parameter
-#  interdependencies.
-#
-#  To reject a parameter match, the +reject+ operator is used. The
-#  +reject+ operator takes an optional argument.
-#  If the argument is true (or was omitted), the current parameter
-#  match is immediately rejected. For example:
-#
-#  	-ar <r:n>	Set aspect ratio (must be in the range [0..1])
-#  				{
-#  				  $sawaspect += 1
-#  				  reject( r <= 0 || r > 1 )
-#  				  setaspect(r)
-#  				}
-#
-#  	-q		Quiet option (not available on Wednesdays)
-#  				{
-#  				  reject(Time.new.localtime.day == 3)
-#  				  $verbose = 0
-#  				}
-#
-#  Note that any actions performed _before_ the call to +reject+ will
-#  still have effect (for example, the variable <tt>$sawaspect</tt> remains
-#  incremented even if the aspect ratio parameter is subsequently rejected).
-#
-#  The +reject+ operator may also take a second argument, which is
-#  used as an error message if the rejected argument subsequently
-#  fails to match any other parameter. For example:
-#
-#  	-q	Quiet option (not available on Wednesdays)
-#  			{
-#  			  reject(Time.new.localtime.day == 3, "Not today!")
-#  			  $verbose = 0;
-#  			}
-#
-#
-#  == Specifying other parameter variable types
-#
-#  As was mentioned in "Type of parameter variables", parameter
-#  variables can be restricted to matching only numbers or only integers
-#  by using the type specifiers ":n" and ":i". Getopt::Declare
-#  provides seven other inbuilt type specifiers, as well as two mechanisms
-#  for defining new restrictions on parameter variables.
-#
-#  The other inbuilt type specifiers are:
-#
-#  * :+i
-#
-#    which restricts a parameter variable to matching positive, non-zero
-#    integers (that is: 1, 2, 3, etc.)
-#
-#  * :+n
-#
-#    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.)
-#
-#  * :0+n  
-#
-#    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  
-#
-#    which allows a parameter variable to match any quote-delimited or
-#    whitespace-terminated string. Note that this specifier simply makes
-#    explicit the default behaviour.
-#
-#  * :d  
-#
-#    which is used to match directory names. Like type ':s', type ':d'
-#    matches any quote-delimited or whitespace-terminated string. However
-#    this type requires that the matched string is name of an existing 
-#    (and accesable) directory.
-#
-#  * :qs  
-#
-#    which allows a parameter variable to match any quote-delimited or
-#    whitespace-terminated string. Note that this specifier simply makes
-#    explicit the default behaviour.
-#
-#  * :id
-# 
-#    which allows a parameter variable to match any identifier
-#    sequence. That is: a alphabetic or underscore, followed by
-#    zero-or-more alphanumerics or underscores.
-#
-#  * :if  
-#
-#    which is used to match input file names. Like type ':s', type ':if'
-#    matches any quote-delimited or whitespace-terminated string. However
-#    this type does _not_ respect other command-line flags and also
-#    requires that the matched string is either "-" (indicating standard
-#    input) or the name of a readable file.
-#
-#  * :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.
-#
-#  * :s  
-#
-#    which allows a parameter variable to match any quote-delimited or
-#    whitespace-terminated string. Note that this specifier simply makes
-#    explicit the default behaviour.
-#
-#
-#  For example:
-#
-#  	-repeat <count:+i>	Repeat <count> times (must be > 0)
-#
-#  	-scale <factor:0+n>	Set scaling factor (cannot be negative)
-#
-#
-#  Alternatively, parameter variables can be restricted to matching a
-#  specific regular expression, by providing the required pattern
-#  explicitly (in matched "/" delimiters after the ":"). For example:
-#
-#  	-parity <p:/even|odd|both/>	Set parity (<p> must be "even",
-#  					"odd" or "both")
-#
-#  	-file <name:/\w*\.[A-Z]{3}/>	File name must have a three-
-#  					capital-letter extension
-#
-#  If an explicit regular expression is used, there are three "convenience"
-#  extensions available:
-#
-#  * %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.
-#    Hence the parameter definition:
-#
-#  	-find <what:/(%T.)+/> ;
-#
-#    ensures that the command line argument "-find abcd;" causes 
-#    <tt><-what></tt> to match "abcd", _not_ "abcd;".
-#
-#
-#  * %D
-#
-#    If the sequence <tt>%D</tt> appears in a pattern, it is translated into
-#    a subpattern which matches any single digit (like a <tt>\d</tt>), but 
-#    only if that digit would _not_ match the parameter variable's trailing 
-#    context.
-#    Hence <tt>%D</tt> is just a convenient short-hand for <tt>(?:%T\d)</tt> 
-#    (and is actually implemented that way).
-#
-#  * %F
-#
-#    By default, any explicit pattern is modified by Getopt::Declare
-#    so that it fails if the argument being matched represents some defined
-#    parameter flag. If however the sequence <tt>%F</tt> appears anywhere in a
-#    pattern, it causes the pattern _not_ to reject strings which would
-#    otherwise match another flag. For example, the inbuilt types ':if' and
-#    ':of' use <tt>%F</tt> to enable them to match filenames which happen to be
-#    identical to parameter flags.
-#
-#
-#  == Defining new parameter variable types
-#
-#  Explicit regular expressions are very powerful, but also cumbersome to
-#  use (or reuse) in some situations. Getopt::Declare provides a general
-#  "parameter variable type definition" mechanism to simplify such cases.
-#
-#  To declare a new parameter variable type, the <tt>[pvtype:...]</tt> 
-#  directive is used. A <tt>[pvtype...]</tt> directive specifies the name, 
-#  matching pattern, and action for the new parameter variable type 
-#  (though both the pattern and action are optional).
-#
-#  The name string may be _any_ whitespace-terminated sequence of
-#  characters which does not include a ">". The name may also be specified
-#  within a pair of quotation marks (single or double) or within any Perl
-#  quotelike operation. For example:
-#
-#  	[pvtype: num     ]	# Makes this valid: -count <N:num>
-#  	[pvtype: 'a num' ]	# Makes this valid: -count <N:a num>
-#  	[pvtype: %q{nbr} ]	# Makes this valid: -count <N:nbr>
-#
-#  The pattern is used in initial matching of the parameter variable.
-#  Patterns are normally specified as a "/"-delimited Perl regular
-#  expression:
-#
-#  	[pvtype: num      /\d+/        ]	
-#  	[pvtype: 'a num'  /\d+(\.\d*)/ ]
-#  	[pvtype: %q{nbr}  /[+-]?\d+/   ]
-#
-#  Alternatively the pattern associated with a new type may be specified
-#  as a ":" followed by the name of another parameter variable type (in
-#  quotes if necessary). In this case the new type matches the same
-#  pattern (and action! - see below) as the named type.  For example:
-#
-#  	[pvtype: num      :+i      ]	# <X:num> is the same as <X:+i>
-#  	[pvtype: 'a num'  :n       ]	# <X:a num> is the same as <X:n>
-#  	[pvtype: %q{nbr}  :'a num' ]	# <X:nbr> is also the same as <X:n>
-#
-#  As a third alternative, the pattern may be omitted altogether, in
-#  which case the new type matches whatever the inbuilt pattern ":s"
-#  matches.
-#
-#  The optional action which may be included in any <tt>[pvtype:...]</tt>
-#  directive is executed _after_ the corresponding parameter variable
-#  matches the command line but _before_ any actions belonging to the
-#  enclosing parameter are executed. Typically, such type actions
-#  will call the +reject+ operator (see "Termination and rejection")
-#  to test extra conditions, but any valid Perl code is acceptible. For
-#  example:
-#
-#  	[pvtype: num      /\d+/    { reject if (localtime)[6]==3 }	]
-#  	[pvtype: 'a num'  :n       { print "a num!" }		]
-#  	[pvtype: %q{nbr}  :'a num' { reject $no_nbr }		]
-#
-#  If a new type is defined in terms of another (for example, ":a num"
-#  and ":nbr" above), any action specified by that new type is
-#  _prepended_ to the action of that other type. Hence:
-#
-#
-#  * the new type ":num" matches any string of digits, but then rejects the
-#    match if it's Wednesday.
-#
-#  * the new type ":a num" matches any string of digits (like its parent
-#    type ":num"), _then_ prints out "a num!", _and_ _then_ rejects the
-#    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").
-#
-#
-#  When a type action is executed (as part of a particular parameter
-#  match), three local variables are available:
-#
-#  * <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).
-#    Note that <tt>\_VAL_</tt> is a variable of different type based on
-#    parameter specified.  For [pvtype:...] it is always a String variable.
-#
-#  * <tt>\_VAR_</tt>  String
-#
-#    which contains the name of the parameter variable being matched.
-#
-#  * <tt>\_PARAM_</tt>  String
-#
-#    which contains the name of the parameter currently being matched.
-#
-#
-#  Here is a example of the use of these variables:
-#
-#  	args = Getopt::Declare.new( <<-'EOPARAM' )
-#
-#  	[pvtype: type  /AB|[OAB]/	                                ]
-#  	[pvtype: Rh?   /Rh[+-]/					        ]
-#  	[pvtype: days  :+i  { 
-#                            reject(_VAL_ < 14,"#{_PARAM_} (too soon!)") 
-#                              } 
-#          ]
-#
-#  	  -donated <d:days>		  Days since last donation
-#  	  -applied <a:days>		  Days since applied to donate
-#
-#  	  -blood <type:type> [<rh:Rh?>]	  Specify blood type
-#  					  and (optionally) rhesus factor
-#  	EOPARAM
-#
-#  In the above example, the ":days" parameter variable type is defined
-#  to match whatever the ":+i" type matches (that is positive, non-zero
-#  integers), with the proviso that the matching value (<tt>\_VAL_</tt>) must
-#  be at least 14. If a shorter value is specified for <tt>d</tt>,
-#  or <tt>a</tt> parameter variables, then Getopt::Declare would
-#  issue the following (respective) error messages:
-#
-#  	Error: -donated (too soon!)
-#  	Error: -applied (too soon!)
-#
-#  Note that the "inbuilt" parameter variable types ("i", "n", etc.) are
-#  really just predefined type names, and hence can be altered if necessary:
-#
-#  	args = Getopt::Declare.new( <<-'EOPARAM' )
-#
-#  	[pvtype: 'n' /[MDCLXVI]+/ { reject( !(_VAL_=to_roman(_VAL_))) } ]
-#
-#  		-index <number:n>	Index number
-#  			{ print data[number]; }
-#  	EOPARAM
-#
-#  The above <tt>[pvtype:...]</tt> directive means that all parameter variables
-#  specified with a type ":n" henceforth only match valid Roman
-#  numerals, but that any such numerals are _automatically_ converted to
-#  ordinary numbers (by passing <tt>\_VAL_</tt>) through the <tt>to_roman</tt>
-#  function).
-#
-#  Hence the requirement that all ":n" numbers now must be Roman can be
-#  imposed _transparently_, at least as far as the actual parameter
-#  variables which use the ":n" type are concerned. Thus <tt>number</tt> can
-#  be still used to index the array <tt>data</tt> despite the new restrictions
-#  placed upon it by the redefinition of type ":n".
-#
-#  Note too that, because the ":+n" and ":0+n" types are implicitly 
-#  defined in terms of the original ":n" type (as if the directives:
-#
-#  	[pvtype: '+n'  :n { reject if _VAL_ <= 0  }  ]
-#  	[pvtype: '0+n' :n { reject if _VAL_ < 0   }  ]
-#
-#  were included in every specification), the above redefinition of ":n"
-#  affects those types as well. In such cases the format conversion is
-#  performed _before_ the "sign" tests (in other words, the "inherited"
-#  actions are performed _after_ any newly defined ones).
-#
-#  Parameter variable type definitions may appear anywhere in a
-#  Getopt::Declare specification and are effective for the entire
-#  scope of the specification. In particular, new parameter variable
-#  types may be defined _after_ they are used.
-#
-#  == Undocumented parameters
-#
-#  If a parameter description is omitted, or consists entirely of
-#  whitespace, or contains the special directive <tt>[undocumented]</tt>, then
-#  the parameter is still parsed as normal, but will not appear in the
-#  automatically generated usage information (see "Usage information").
-#
-#  Apart from allowing for "secret" parameters (a dubious benefit), this
-#  feature enables the programmer to specify some undocumented action
-#  which is to be taken on encountering an otherwise unknown argument.
-#  For example:
-#
-#  	<unknown>	
-#  			{ handle_unknown(unknown) }
-#
-#
-#  == "Dittoed" parameters
-#
-#  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
-#  description for the immediately preceding parameter (including any
-#  other directives). For example:
-#
-#  	-v		Verbose mode
-#  	--verbose	[ditto] (long form)
-#
-#  In the automatically generated usage information this would be displayed as:
-#
-#  	-v		Verbose mode
-#  	--verbose	   "     "   (long form)
-#
-#  Furthermore, if the "dittoed" parameter has no action(s) specified, the
-#  action(s) of the preceding parameter are reused. For example, the
-#  specification:
-#
-#  	-v		Verbose mode
-#  				{ $verbose = 1; }
-#  	--verbose	[ditto]
-#
-#  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
-#  				{ $verbose = 1; }
-#  	--verbose	[ditto]
-#  				{ $verbose = 2; }
-#
-#
-#  would give separate actions to each flag.
-#
-#
-#  == Deferred actions
-#
-#  It is often desirable or necessary to defer actions taken in response
-#  to particular flags until the entire command-line has been parsed. The most
-#  obvious case is where modifier flags must be able to be specified _after_
-#  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.
-#
-#  For example:
-#
-#  	<files>...	Files to be processed
-#  			    { defer { files.each { |i| 
-#                                                  print i,"\n" } } }
-#
-#  	-rev[erse]	Process in reverse order
-#  			    { $ordered = -1 }
-#
-#  	-rand[om]	Process in random order
-#  			    { $ordered = 0 }
-#
-#
-#  With the above specification, the <tt>-rev</tt> and/or <tt>-rand</tt> flags
-#  can be specified _after_ the list of files, but still affect the processing
-#  of those files. Moreover, if the command-line parsing fails for some reason
-#  (perhaps due to an unrecognized argument), the deferred processing will
-#  not be performed.
-#
-#
-#  == Flag clustering
-#
-#  Like some other Getopt modules, Getopt::Declare allows parameter
-#  flags to be "clustered". That is, if two or more flags have the same
-#  "flag prefix" (one or more leading non-whitespace, non-alphanumeric 
-#  characters), those flags may be concatenated behind a single copy of that 
-#  flag prefix.
-#  For example, given the parameter specifications:
-#
-#  	-+              Swap signs
-#  	-a              Append mode
-#  	-b              Bitwise compare
-#  	-c <FILE>       Create new file
-#  	+del            Delete old file
-#  	+e <NICE:i>     Execute (at specified nice level) when complete
-#
-#  The following command-lines (amongst others) are all exactly equivalent:
-#
-#  	-a -b -c newfile +e20 +del
-#  	-abc newfile +dele20
-#  	-abcnewfile+dele20
-#  	-abcnewfile +e 20del
-#
-#  The last two alternatives are correctly parsed because
-#  Getopt::Declare allows flag clustering at _any point_ where the
-#  remainder of the command-line being processed starts with a
-#  non-whitespace character and where the remaining substring would not
-#  otherwise immediately match a parameter flag.
-#
-#  Hence the trailing "+dele20" in the third command-line example is parsed as
-#  "+del +e20" and not "-+ del +e20". This is because the previous "-"
-#  prefix is _not_ propagated (since the leading "+del" _is_ a valid flag).
-#
-#  In contrast, the trailing "+e 20del" in the fourth example is parsed as
-#  "+e 20 +del" because, after the " 20" is parsed (as the integer
-#  parameter variable <tt><NICE></tt>, the next characters are "del",
-#  which _do_ _not_ form a flag themselves unless prefixed with the
-#  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:
-#
-#  	-a		Blood type is A
-#  	-b		Blood type is B
-#  	-ab	 	Blood type is AB
-#  	-ba	 	Donor has a Bachelor of Arts
-#
-#  A command-line argument "-aba" might be parsed as
-#  "-a -b -a" or "-a -ba" or "-ab -a". In all such
-#  cases, Getopt::Declare prefers the longest unmatched flag first.
-#  Hence the previous example would be parsed as "-ab -a", unless
-#  the <tt>-ab</tt> flag had already appeared in the command-line (in which
-#  case, it would be parsed as "-a -ba").
-#
-#  These rules are designed to produce consistency and "least surprise",
-#  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.
-#
-#  The options are:
-#
-#  * <tt>[cluster: any]</tt>
-#
-#    This version of the directive allows any flag to be clustered (that is,
-#    it merely makes explicit the default behaviour).
-#
-#  * <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).
-#
-#  * <tt>[cluster: singles]</tt>
-#
-#    This version of the directive restricts clustering to parameters which are
-#    "pure" flags, and which consist of a flag prefix followed by a single
-#    alphanumeric character.
-#
-#  * <tt>[cluster: none]</tt>
-#
-#    This version of the directive turns off clustering completely.
-#
-#  For example:
-#
-#  	args = Getopt::Declare.new(<<-'EOSPEC')
-#  		-a              Append mode
-#  		-b              Back-up mode
-#  		-bu             [ditto]
-#  		-c <file>       Copy mode
-#  		-d [<file>]     Delete mode
-#  		-e[xec]         Execute mode
-#
-#  		[cluster:singles]
-#  	EOSPEC
-#
-#  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>).
-#
-#  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").
-#
-#
-#  == Strict and non-strict command-line parsing
-#
-#  "Strictness" in Getopt::Declare refers to the way in which unrecognized
-#  command-line arguments are handled. By default, Getopt::Declare is
-#  "non-strict", in that it simply skips silently over any unrecognized
-#  command-line argument, leaving it in +ARGV+ at the conclusion of
-#  command-line processing (but only if they were originally parsed
-#  from +ARGV+).
-#
-#  No matter where they came from, the remaining arguments are also available
-#  by calling the +unused+ method on the Getopt::Declare object, after it
-#  has parsed. In a list context, this method returns a list of the
-#  unprocessed arguments; in a scalar context a single string with the unused
-#  arguments concatenated is returned.
-#
-#  Likewise, there is a +used+ method that returns the arguments that were
-#  successfully processed by the parser.
-#
-#  However, if a new Getopt::Declare object is created with a
-#  specification string containing the <tt>[strict]</tt> directive (at any
-#  point in the specification):
-#
-#  	args = Getopt::Declare.new(<<-'EOSPEC')
-#
-#  		[strict]
-#
-#  		-a	Append mode
-#  		-b	Back-up mode
-#  		-c	Copy mode
-#  	EOSPEC
-#
-#  then the command-line is parsed "strictly". In this case, any
-#  unrecognized argument causes an error message (see "DIAGNOSTICS") to
-#  be written to <tt>$stderr</tt>, and command-line processing to (eventually)
-#  fail. On such a failure, the call to Getopt::Declare::new() returns
-#  +nil+ instead of the usual hash.
-#
-#  The only concession that "strict" mode makes to the unknown is that,
-#  if command-line processing is prematurely terminated via the
-#  +finish+ operator, any command-line arguments which have not yet
-#  been examined are left in +ARGV+ and do not cause the parse to fail (of
-#  course, if any unknown arguments were encountered _before_ the
-#  +finish+ was executed, those earlier arguments _will_ cause
-#  command-line processing to fail).
-#
-#  The "strict" option is useful when _all_ possible parameters
-#  can be specified in a single Getopt::Declare object, whereas the
-#  "non-strict" approach is needed when unrecognized arguments are either
-#  to be quietly tolerated, or processed at a later point (possibly in a
-#  second Getopt::Declare object).
-#
-#
-#  == Other global directives
-#
-#  Getopt::Declare offers some other less used global directives to control
-#  how some options are handled.
-#
-#  The directives are:
-#
-#  * <tt>[tight]</tt>
-#
-#    Specifies that the usage (help) description should be printed in a tight
-#    form, eliminating as many empty or whitespace only lines as possible.
-#
-#  * <tt>[debug]</tt>
-#
-#    For debugging purposes, it specifies that the internal parser that 
-#    Getopt::Declare generates gets saved to a file called .CODE.rb.
-#    This file is placed in the directory where the command was run from.
-#
-#
-#  == Parameter dependencies
-#
-#  Getopt::Declare provides five other directives which modify the
-#  behaviour of the command-line parser in some way. One or more of these
-#  directives may be included in any parameter description. In addition,
-#  the <tt>[mutex:...]</tt> directive may also appear in any usage "decoration"
-#  (see "Usage information").
-#
-#  Each directive specifies a particular set of conditions that a
-#  command-line must fulfil (for example, that certain parameters may not
-#  appear on the same command-line). If any such condition is violated,
-#  an appropriate error message is printed (see "DIAGNOSTICS").
-#  Furthermore, once the command-line is completely parsed, if any
-#  condition was violated, the program terminates
-#  (whilst still inside Getopt::Declare::new()).
-#
-#
-#  The directives are:
-#
-#  * <tt>[required]</tt>
-#
-#    Specifies that an argument matching at least one variant of the
-#    corresponding parameter _must_ be specified somewhere in the
-#    command-line. That is, if two or more required parameters share the
-#    same flag, it suffices that _any_ _one_ of them matches an argument
-#    (recall that Getopt::Declare considers all parameter specifications
-#    with the same flag merely to be variant forms of a single "underlying"
-#    parameter).
-#
-#    If an argument matching a "required" flag is _not_ found in the
-#    command-line, an error message to that effect is issued,
-#    command-line processing fails, and Getopt::Declare::new() returns
-#    +nil+.
-#
-#
-#  * <tt>[repeatable]</tt>
-#
-#    By default, Getopt::Declare objects allow each of their parameters to
-#    be matched only once (that is, once any variant of a particular
-#    parameter matches an argument, _all_ variants of that same parameter
-#    are subsequently excluded from further consideration when parsing the
-#    rest of the command-line).
-#
-#    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:
-#
-#  	-nice		Increase nice value (linearly if repeated)
-#  			[repeatable]
-#  				{ set_nice( get_nice()+1 ) }
-#
-#  	-w		Toggle warnings [repeatable] for the rest
-#  			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:
-#
-#  	[repeatable]
-#
-#  	-nice		Increase nice value (linearly if repeated)
-#  				{ set_nice( get_nice()+1 ) }
-#
-#  	-w		Toggle warnings for the rest of the command-line 
-#  				{ warn = !warn }
-#
-#
-#  * <tt>[mutex: <flag list>]</tt>
-#
-#    <tt>[mutex:...]</tt> directive specifies that the parameters whose
-#    flags it lists are mutually exclusive. That is, no two or more of them
-#    may appear in the same command-line. For example:
-#
-#  	-case		set to all lower case
-#  	-CASE		SET TO ALL UPPER CASE
-#  	-Case		Set to sentence case
-#  	-CaSe		SeT tO "RAnSom nOTe" CasE
-#
-#  			[mutex: -case -CASE -Case -CaSe]
-#
-#    The interaction of the <tt>[mutex:...]</tt> and <tt>[required]</tt> 
-#    directives is potentially awkward in the case where two "required" 
-#    arguments are also mutually exclusive (since the <tt>[required]</tt>
-#    directives insist that both parameters must appear in the command-line, 
-#    whilst the <tt>[mutex:...]</tt> directive expressly forbids this).
-#
-#    Getopt::Declare resolves such contradictory constraints by
-#    relaxing the meaning of "required" slightly. If a flag is marked
-#    "required", it is considered "found" for the purposes of error
-#    checking if it or _any_ other flag with which it is mutually
-#    exclusive appears on the command-line. 
-#
-#    Hence the specifications:
-#
-#  	-case		set to all lower case      [required]
-#  	-CASE		SET TO ALL UPPER CASE      [required]
-#  	-Case		Set to sentence case       [required]
-#  	-CaSe		SeT tO "RAnSom nOTe" CasE  [required]
-#
-#  			[mutex: -case -CASE -Case -CaSe]
-#
-#    mean that _exactly_ _one_ of these four flags must appear on the
-#    command-line, but that the presence of any one of them will suffice
-#    to satisfy the "requiredness" of all four.
-#
-#    It should also be noted that mutual exclusion is only tested for
-#    _after_ a parameter has been completely matched (that is, after the
-#    execution of its actions, if any). This prevents "rejected" parameters
-#    (see "Termination and rejection") from incorrectly generating
-#    mutual exclusion errors. However, it also sometimes makes it necessary
-#    to defer the actions of a pair of mutually exclusive parameters (for
-#    example, if those actions are expensive or irreversible).
-#
-#
-#  * <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:
-#
-#  	-left		Justify to left margin
-#  	-right		Justify to right margin
-#  	-centre		Centre each line
-#
-#  	[mutex: -left -right -centre]
-#
-#    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 
-#  	-centre		Centre each line  [excludes: -left -right]
-#
-#    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>
-#    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.
-#
-#
-#  * <tt>[requires: -condition]</tt>
-#
-#    The <tt>[requires]</tt> directive specifies a set of flags which
-#    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:
-#
-#  	-num		Use numeric sort order
-#  	-lex		Use "dictionary" sort order
-#  	-len		Sort on length of line (or field)
-#
-#  	-field <N:+i>	Sort on value of field <N> 
-#
-#  	-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.
-#
-#    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()
-#  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).
-#
-#  * 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>,
-#    concatenates their contents, and parses that.
-#
-#    If neither file is found (or if both are inaccessible)
-#    Getopt::Declare::new() immediately returns zero. If a
-#    file is found but the parse subsequently fails, +nil+ is returned.
-#
-#  * An ARRAY containing the single string ['-BUILD']
-#
-#    in which case Getopt::Declare::new() builds a parser from the
-#    supplied grammar and returns it, but does not parse anything.
-#    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 []
-#
-#    in which case Getopt::Declare::new() immediately returns zero.
-#    This alternative is useful when using a +File+:
-#
-#  	args = Getopt::Declare.new(grammar,
-#  				   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.
-#
-#  * An ARRAY containing the word "-ARGV" followed by another ARRAY
-#
-#    in which case Getopt::Declare::new() treats the array elements as
-#    parameters to parse (as if it were +ARGV+).
-#
-#       arr  = ['-in','opt with spaces']
-#  	args = Getopt::Declare.new(grammar, ['-ARGV', arr])
-#
-#  * 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.
-#
-#    If the list does not denote any accessible file(s)
-#    Getopt::Declare::new() immediately returns zero. If matching files
-#    are found, but not successfully parsed, +nil+ is returned.
-#
-#  * A string
-#
-#    in which case Getopt::Declare::new() parses that string directly.
-#
-#  Note that when Getopt::Declare::new() parses from a
-#  source other than +ARGV+, unrecognized arguments are _not_
-#  placed back in +ARGV+.
-#
-#
-#  == Using Getopt::Declare objects after command-line processing
-#
-#  After command-line processing is completed, the object returned by
-#  Getopt::Declare::new() will have the following features:
-#
-#  * 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.
-#
-#    The value of the element will be another hash which contains
-#    the names and values of each distinct parameter variable and/or
-#    punctuator which was matched by the parameter. Punctuators generate
-#    string values containing the actual text matched. Other parameter
-#    variables generate values based on their specification (Fixnum,
-#    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.
-#
-#    The following example illustrates the various possibilities:
-#
-#  	args = Getopt::Declare.new( %q{
-#
-#  		-v <value> [etc]	One or more values
-#  		<infile>		Input file [required]
-#  		-o <outfiles>...	Output files
-#  	} )
-#
-#  	if  args['-v']
-#  		print  "Using value: ", args['-v']['<value>']
-#  		print  " (etcetera)" if args['-v']['etc']
-#  		print  "\n"
-#       end
-#
-#  	infile = File.new( args['<infile>'] )
-#  	data = infile
-#
-#  	for outfile in args['-o']
-#  		outfile = File.new(outfile,'w')
-#               outfile.puts "processed"
-#  		outfile.close
-#  	end
-#
-#    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:
-#
-#  	args = Getopt::Declare.new( %q{
-#
-#  	-ar <r:n>	Set aspect ratio (will be clipped to [0..1])
-#  				{
-#  				  r = 0 if r < 0
-#  				  r = 1 if r > 1
-#  				}
-#  	} )
-#
-#    then the value of <tt>args['-ar']</tt> will always be between zero 
-#    and one.
-#
-#  * The +ARGV+ array
-#
-#    In its "non-strict" mode, once a Getopt::Declare object has
-#    completed its command-line processing, it pushes any unrecognized
-#    arguments back into the emptied command-line array +ARGV+ (whereas
-#    all _recognized_ arguments will have been removed).
-#
-#    Note that these remaining arguments will be in sequential elements
-#    (starting at <tt>ARGV[0]</tt>), _not_ in their original positions in
-#    +ARGV+.
-#
-#
-#  * 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).
-#
-#
-#  * The Getopt::Declare::version() method
-#
-#    Another useful method of a Getopt::Declare object is <tt>version()</tt>,
-#    which prints out the name of the enclosing program, the last time it
-#    was modified, and the value of <tt>$VERSION</tt>, if it is defined.
-#    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.
-#
-#
-#  * The Getopt::Declare::parse() method
-#
-#    It is possible to separate the construction of a Getopt::Declare
-#    parser from the actual parsing it performs. If
-#    Getopt::Declare::new() is called with a second parameter ['-BUILD']
-#    (see "Parsing from other sources", it constructs and returns a
-#    parser, without parsing anything.
-#    The resulting parser object can then be used to parse multiple sources,
-#    by calling its <tt>parse()</tt> method. 
-#
-#    Getopt::Declare::parse() takes an optional parameter which specifies
-#    the source of the text to be parsed (it parses +ARGV+ if the
-#    parameter is omitted). This parameter takes the same set of values as the
-#    optional second parameter of Getopt::Declare::new() (see "Parsing
-#    from other sources").
-#
-#    Getopt::Declare::parse() returns true if the source is located and
-#    parsed successfully. It returns a defined false (zero) if the source is
-#    not located. A +nil+ is returned if the source is located, but not
-#    successfully parsed.
-#
-#    Thus, the following code first constructs a parsers for a series of 
-#    alternate configuration files and the command line, and then parses them:
-#
-#  	# BUILD PARSERS
-#  	config  = Getopt::Declare::new(config_grammar, ['-BUILD']);
-#  	cmdline = Getopt::Declare::new(cmdline_grammar, ['-BUILD']);
-#
-#  	# TRY STANDARD CONFIG FILES
-#  	config.parse(['-CONFIG'])
-#
-#  	# OTHERWISE, TRY GLOBAL CONFIG
-#  	or config.parse('/usr/local/config/.demo_rc')
-#
-#  	# OTHERWISE, TRY OPENING A FILEHANDLE (OR JUST GIVE UP)
-#  	or config.parse(File.new(".config") || ['-SKIP']);
-#
-#  	# NOW PARSE THE COMMAND LINE
-#
-#  	cmdline.parse() or raise "cannot parse";
-#
-#
-#  * The Getopt::Declare::code() method
-#
-#    It is also possible to retreive the command-line parsing code generated
-#    internally by Getopt::Declare::new(). The Getopt::Declare::code()
-#    method returns a string containing the complete command-line processing
-#    code, as a single +begin+ block plus a leading +package+ declaration.
-#
-#    Getopt::Declare::code() takes as its sole argument a string
-#    containing the complete name of the package (for the leading
-#    +package+ declaration in the generated code). If this string is empty
-#    or undefined, the package name defaults to "main".
-#
-#    Since the default behaviour of Getopt::Declare::new() is to execute
-#    the command-line parsing code it generates, if the goal is only to 
-#    generate the parser code, the optional second ['-BUILD'] parameter
-#    (see "Parsing from other sources") should be specified when calling
-#    Getopt::Declare::new().
-#
-#    For example, the following program "inlines" a Getopt::Declare
-#    specification, by extracting it from between the first "=for
-#    Getopt::Declare" and the next "=cut" appearing on +$stdin+:
-#
-#    Just type in something, like:
-#
-#    =for Getopt::Declare
-#
-#                 -a              Append mode
-#    =cut
-#
-#    $/ = '=cut'
-#    if t = $stdin.readline
-#      t.sub!( /^=for\s+Getopt::Declare\s*\n(.*?)\n=cut/esm ) { 
-#              '(self,source) = []'+encode("#$1") }
-#    end
-#
-#    print t
-#
-#
-#    Note that the generated inlined version expects to find a lexical variable
-#    named +source+, which tells it what to parse (this variable is
-#    normally set by the optional parameters of Getopt::Declare::new() or
-#    Getopt::Declare::parse()).
-#
-#    The inlined code leaves all extracted parameters in the lexical
-#    variable +self+ and the does not autogenerate help or version flags
-#    (since there is no actual Getopt::Declare object in the inlined code
-#    through which to generate them).
-#
-#  = AUTOGENERATED FEATURES
-#
-#  == Usage information
-#
-#  The specification passed to Getopt::Declare::new is used (almost
-#  verbatim) as a "usage" display whenever usage information is
-#  requested.
-#
-#  Such requests may be made either by specifying an argument matching
-#  the help parameter (see "Help parameters") or by explicitly calling
-#  the Getopt::Declare::usage() method (through an action or after
-#  command-line processing):
-#
-#  	args = Getopt::Declare.new( %q{
-#
-#  		-usage		Show usage information and exit
-#  					{ usage(0) }
-#
-#  		+usage		Show usage information at end of program
-#  	} )
-#
-#  	# PROGRAM HERE 
-#
-#  	args.usage if args['+usage'];
-#
-#
-#  The following changes are made to the original specification before
-#  it is displayed:
-#
-#  * All actions and comments are deleted,
-#
-#  * 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.
-#
-#  Otherwise, the usage information displayed retains all the formatting
-#  present in the original specification.
-#
-#  In addition to this information, if the input source is +ARGV+,
-#  Getopt::Declare displays three sample command-lines: one indicating
-#  the normal usage (including any required parameter variables), one
-#  indicating how to invoke help (see "Help parameters"), and one
-#  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.
-#
-#  == Usage "decoration"
-#
-#  It is sometimes convenient to add other "decorative" features to a
-#  program's usage information, such as subheadings, general notes,
-#  separators, etc. Getopt::Declare accommodates this need by ignoring
-#  such items when interpreting a specification string, but printing them
-#  when asked for usage information. 
-#
-#  Any line which cannot be interpreted as either a parameter
-#  definition, a parameter description, or a parameter action, is treated
-#  as a "decorator" line, and is printed verbatim (after any square
-#  bracketted substrings have been removed from it).
-#
-#  The key to successfully decorating Getopt::Declare usage
-#  information is to ensure that decorator lines are separated from
-#  any preceding parameter specification, either by an action or by an
-#  empty line. In addition, like a parameter description, a decorator
-#  line cannot contain a tab character after the first non-whitespace
-#  character (because it would then be treated as a parameter
-#  specification).
-#
-#  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.
-#
-#  	args = Getopt::Declare.new(<<-'EOPARAM');
-#
-#  	============================================================
-#  	Required parameter:
-#
-#  		-in <infile>		Input file [required]
-#
-#  	------------------------------------------------------------
-#
-#  	Optional parameters:
-#
-#  		(The first two are mutually exclusive) [mutex: -r -p]
-#
-#  		-r[and[om]]		Output in random order
-#  		-p[erm[ute]]		Output all permutations
-#
-#  		---------------------------------------------------
-#
-#  		-out <outfile>		Optional output file
-#
-#  	------------------------------------------------------------
-#  	Note: this program is known to run very slowly of files with
-#  	      long individual lines.
-#  	============================================================
-#  	EOPARAM
-#
-#
-#  == Help parameters
-#
-#  By default, Getopt::Declare automatically defines _all_ of the following
-#  parameters:
-#
-#  	-help	Show usage information [undocumented]
-#  			{ usage(0) }
-#  	-Help	[ditto]
-#  	-HELP	[ditto]
-#  	--help	[ditto]
-#  	--Help	[ditto]
-#  	--HELP	[ditto]
-#  	-h	[ditto]
-#  	-H	[ditto]
-#
-#  Hence, most attempts by the user to get help will automatically work
-#  successfully.
-#
-#  Note however that, if a parameter with any of these flags is
-#  explicitly specified in the string passed to Getopt::Declare::new(),
-#  that flag (only) is removed from the list of possible help flags. For
-#  example:
-#
-#  	-w <pixels:+i>	Specify width in pixels
-#  	-h <pixels:+i>	Specify height in pixels
-#
-#  would cause the <tt>-h</tt> help parameter to be removed (although help
-#  would still be accessible through the other seven alternatives).
-#
-#
-#  == Version parameters
-#
-#  Getopt::Declare also automatically creates a set of parameters which can be
-#  used to retreive program version information:
-#
-#  	-version	Show version information [undocumented]
-#  				{ version(0) }
-#  	-Version	[ditto]
-#  	-VERSION	[ditto]
-#  	--version	[ditto]
-#  	--Version	[ditto]
-#  	--VERSION	[ditto]
-#  	-v		[ditto]
-#  	-V		[ditto]
-#
-#  As with the various help commands, explicitly specifying a parameter
-#  with any of the above flags removes that flag from the list of version
-#  flags.
-#
-#
-#  = DIAGNOSTICS
-#
-#  Getopt::Declare may issue the following diagnostics whilst parsing a
-#  command-line. All of them are fatal (the first five, instantly so):
-#
-#  * "Error: bad Getopt::Declare parameter variable specification near %s"
-#
-#    A matching pair of angle brackets were specified as part of a
-#    parameter definition, but did not form a valid parameter variable
-#    specification (that is, it wasn't in the form: <_name_> or
-#    <_name_:_type_>).
-#
-#  * "Error: bad type in Getopt::Declare parameter variable specification
-#            near %s"
-#
-#    An unknown type specifier was used in a parameter variable type suffix.
-#
-#  * "Error: bad action in Getopt::Declare specification:\n %s"
-#
-#    A Perl syntax error was detected in the indicated action.
-#
-#  * "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.
-#
-#  * "Error: incomplete action in Getopt::Declare specification:\n %s"
-#
-#    An action was found, but it was missing one or more closing '}'s.
-#
-#  * "Error: bad condition in directive [requires: %s]\n"
-#
-#    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>.
-#
-#  * "Error: in generated command-line parser code:\n %s"
-#
-#    Either there was a Ruby syntax error in one some action (which was
-#    not caught by the previous diagnostic), or (less likely) there is a
-#    bug in the code generator inside Getopt::Declare.
-#
-#  * "Error: incorrect specification of %s parameter"
-#
-#    The flag for the indicated parameter was found, but the argument did not
-#    then match any of that parameter's variant syntaxes.
-#
-#  * "Error: parameter %s not allowed with %s"
-#
-#    Two mutually exclusive flags were specified together.
-#
-#  * "Error: required parameter %s not found"
-#
-#    No argument matching the specified "required" parameter was found
-#    during command-line processing.
-#
-#  * "Error: parameter %s can only be specified with %s"
-#
-#    The indicated parameter has a <tt>[requires:...]</tt> directive, which
-#    was not satisfied.
-#
-#  * "Error: unknown command-line argument (%s)"
-#
-#    A command-line argument was encountered which did not match any
-#    specified parameter. This diagnostic can only only appear if the
-#    "strict" option is in effect.
-#
-#  * "Error: in parameter %s (%s must be an integer greater than zero)"
-#
-#    A parameter variable in the indicated parameter was declared with the
-#    type ":+i" (or a type derived from it), but the corresponding
-#    argument was not a positive, non-zero integer.
-#
-#  * "Error: in parameter %s (%s must be a number greater than zero)"
-#
-#    A parameter variable in the indicated parameter was declared with the
-#    type ":+n" (or a type derived from it), but the corresponding
-#    argument was not a positive, non-zero number.
-#
-#  * "Error: in parameter %s (%s must be an positive integer)"
-#
-#    A parameter variable in the indicated parameter was declared with the
-#    type ":0+i" (or a type derived from it), but the corresponding
-#    argument was not a positive integer.
-#
-#  * "Error: in parameter %s (%s must be a positive number)"
-#
-#    A parameter variable in the indicated parameter was declared with the
-#    type ":0+n" (or a type derived from it), but the corresponding
-#    argument was not a positive number.
-#
-#  = AUTHORS
-#
-#  Damian Conway (damian@conway.org)      Perl Implementation.
-#
-#  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.
-#
-#  If nothing else, it shouldn't take 1500 lines to explain a
-#  package that was designed for intuitive ease of use!
-#
-#  Bug reports and other feedback are most welcome.
-#
-#
-#  = COPYRIGHT
-#
-#     Ruby Port:
-#         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)
-#
-#     Original Perl Code:
-#         Copyright (c) 1997-2000, Damian Conway. 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)
-#
-#  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: 
-# 
-#  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.
-#
-