Provided by: libgetopt-tabular-perl_0.3-2_all bug

NAME

       Getopt::Tabular - table-driven argument parsing for Perl 5

SYNOPSIS

           use Getopt::Tabular;

       (or)

           use Getopt::Tabular qw/GetOptions
                                  SetHelp SetHelpOption
                                  SetError GetError/;

           ...

           &Getopt::Tabular::SetHelp (long_help, usage_string);

           @opt_table = (
                         [section_description, "section"],
                         [option, type, num_values, option_data, help_string],
                         ...
                        );
           &GetOptions (\@opt_table, \@ARGV [, \@newARGV]) || exit 1;

DESCRIPTION

       Getopt::Tabular is a Perl 5 module for table-driven argument parsing, vaguely inspired by
       John Ousterhout's Tk_ParseArgv.  All you really need to do to use the package is set up a
       table describing all your command-line options, and call &GetOptions with three arguments:
       a reference to your option table, a reference to @ARGV (or something like it), and an
       optional third array reference (say, to @newARGV).  &GetOptions will process all arguments
       in @ARGV, and copy any leftover arguments (i.e. those that are not options or arguments to
       some option) to the @newARGV array.  (If the @newARGV argument is not supplied,
       "GetOptions" will replace @ARGV with the stripped-down argument list.)  If there are any
       invalid options, "GetOptions" will print an error message and return 0.

       Before I tell you all about why Getopt::Tabular is a wonderful thing, let me explain some
       of the terminology that will keep popping up here.

       argument
           any single word appearing on the command-line, i.e. one element of the @ARGV array.

       option
           an argument that starts with a certain sequence of characters; the default is "-".
           (If you like GNU-style options, you can change this to "--".)  In most
           Getopt::Tabular-based applications, options can come anywhere on the command line, and
           their order is unimportant (unless one option overrides a previous option).  Also,
           Getopt::Tabular will allow any non-ambiguous abbreviation of options.

       option argument
           (or value) an argument that immediately follows certain types of options.  For
           instance, if "-foo" is a scalar-valued integer option, and "-foo 3" appears on the
           command line, then 3 will be the argument to "-foo".

       option type
           controls how "GetOptions" deals with an option and the arguments that follow it.
           (Actually, for most option types, the type interacts with the "num_values" field,
           which determines whether the option is scalar- or vector-valued.  This will be fully
           explained in due course.)

FEATURES

       Now for the advertising, i.e. why Getopt::Tabular is a good thing.

       ·   Command-line arguments are carefully type-checked, both by pattern and number---e.g.
           if an option requires two integers, GetOptions makes sure that exactly two integers
           follow it!

       ·   The valid command-line arguments are specified in a data structure separate from the
           call to GetOptions; this makes it easier to have very long lists of options, and to
           parse options from multiple sources (e.g. the command line, an environment variable,
           and a configuration file).

       ·   Getopt::Tabular can intelligently generate help text based on your option
           descriptions.

       ·   The type system is extensible, and if you can define your desired argument type using
           a single Perl regular expression then it's particularly easy to extend.

       ·   To make your program look smarter, options can be abbreviated and come in any order.

       ·

            You can parse options in a "spoof" mode that has no side-effects -- this
           is useful for making a validation pass over the command line without
           actually doing anything.

       In general, I have found that Getopt::Tabular tends to encourage programs with long lists
       of sophisticated options, leading to great flexibility, intelligent operation, and the
       potential for insanely long command lines.

BASIC OPERATION

       The basic operation of Getopt::Tabular is driven by an option table, which is just a list
       of option descriptions (otherwise known as option table entries, or just entries).  Each
       option description tells "GetOptions" everything it needs to know when it encounters a
       particular option on the command line.  For instance,

           ["-foo", "integer", 2, \@Foo, "set the foo values"]

       means that whenever "-foo" is seen on the command line, "GetOptions" is to make sure that
       the next two arguments are integers, and copy them into the caller's @Foo array.  (Well,
       really into the @Foo array where the option table is defined.  This is almost always the
       same as "GetOptions"' caller, though.)

       Typically, you'll group a bunch of option descriptions together like this:

           @options =
               (["-range", "integer", 2, \@Range,
                 "set the range of allowed values"],
                ["-file", "string", 1, \$File,
                  "set the output file"],
                ["-clobber", "boolean", 0, \$Clobber,
                  "clobber existing files"],
                ...
               );

       and then call "GetOptions" like this:

           &GetOptions (\@options, \@ARGV) || exit 1;

       which replaces @ARGV with a new array containing all the arguments left-over after options
       and their arguments have been removed.  You can also call "GetOptions" with three
       arguments, like this:

           &GetOptions (\@options, \@ARGV, \@newARGV) || exit 1;

       in which case @ARGV is untouched, and @newARGV gets the leftover arguments.

       In case of error, "GetOptions" prints enough information for the user to figure out what's
       going wrong.  If you supply one, it'll even print out a brief usage message in case of
       error.  Thus, it's enough to just "exit 1" when "GetOptions" indicates an error by
       returning 0.

       Detailed descriptions of the contents of an option table entry are given next, followed by
       the complete run-down of available types, full details on error handling, and how help
       text is generated.

OPTION TABLE ENTRIES

       The fields in the option table control how arguments are parsed, so it's important to
       understand each one in turn.  First, the format of entries in the table is fairly rigid,
       even though this isn't really necessary with Perl.  It's done that way to make the
       Getopt::Tabular code a little easier; the drawback is that some entries will have unused
       values (e.g. the "num_values" field is never used for boolean options, but you still have
       to put something there as a place-holder).  The fields are as follows:

       option
           This is the option name, e.g. "-verbose" or "-some_value".  For most option types,
           this is simply an option prefix followed by text; for boolean options, however, it can
           be a little more complicated.  (The exact rules are discussed under "OPTION TYPES".)
           And yes, even though you tell Getopt::Tabular the valid option prefixes, you still
           have to put one onto the option names in the table.

       type
           The option type decides what action will be taken when this option is seen on the
           command line, and (if applicable) what sort of values will be accepted for this
           option.  There are three broad classes of types: those that imply copying data from
           the command line into some variable in the caller's space; those that imply copying
           constant data into the caller's space without taking any more arguments from the
           command line; and those that imply some other action to be taken.  The available
           option types are covered in greater detail below (see "OPTION TYPES"), but briefly:
           "string", "integer", and "float" all imply copying values from the command line to a
           variable; "constant", "boolean", "copy", "arrayconst", and "hashconst" all imply
           copying some pre-defined data into a variable; "call" and "eval" allow the execution
           of some arbitrary subroutine or chunk of code; and "help" options will cause
           "GetOptions" to print out all available help text and return 0.

       num_values
           for "string", "integer", and "float" options, this determines whether the option is a
           scalar (num_values = 1) or vector (num_values > 1) option.  (Note that whether the
           option is scalar- or vector-valued has an important influence on what you must supply
           in the option_data field!)  For "constant", "copy", "arrayconst", and "hashconst"
           option types, num_values is a bit of a misnomer: it actually contains the value (or a
           reference to it, if array or hash) to be copied when the option is encountered.  For
           "call" options, num_values can be used to supply extra arguments to the called
           subroutine.  In any case, though, you can think of num_values as an input value.  For
           "boolean" and "eval" options, num_values is ignored and should be "undef" or 0.

       option_data
           For "string", "integer", "float", "boolean", "constant", "copy", "arrayconst", and
           "hashconst" types, this must be a reference to the variable into which you want
           "GetOptions" to copy the appropriate thing.  The "appropriate thing" is either the
           argument(s) following the option, the constant supplied as num_values, or 1 or 0 (for
           boolean options).

           For "boolean", "constant", "copy", and scalar-valued "string", "integer", and "float"
           options, this must be a scalar reference.  For vector-valued "string", "integer", and
           "float" options (num_values > 1), and for "arrayconst" options, this must be an array
           reference.  For "hashconst" options, this must be a hash reference.

           Finally, option_data is also used as an input value for "call" and "eval" options: for
           "call", it should be a subroutine reference, and for "eval" options, it should be a
           string containing valid Perl code to evaluate when the option is seen.  The subroutine
           called by a "call" option should take at least two arguments: a string, which is the
           actual option that triggered the call (because the same subroutine could be tied to
           many options), and an array reference, which contains all command line arguments after
           that option.  (Further arguments can be supplied in the num_values field.)  The
           subroutine may freely modify this array, and those modifications will affect the
           behaviour of "GetOptions" afterwards.

           The chunk of code passed to an "eval" option is evaluated in the package from which
           "GetOptions" is called, and does not have access to any internal Getopt::Tabular data.

       help_string
           (optional) a brief description of the option.  Don't worry about formatting this in
           any way; when "GetOptions" has to print out your help, it will do so quite nicely
           without any intervention.  If the help string is not defined, then that option will
           not be included in the option help text.  (However, you could supply an empty string
           -- which is defined -- to make "GetOptions" just print out the option name, but
           nothing else.)

       arg_desc
           (optional) an even briefer description of the values that you expect to follow your
           option.  This is mainly used to supply place-holders in the help string, and is
           specified separately so that "GetOptions" can act fairly intelligently when formatting
           a help message.  See "HELP TEXT" for more information.

OPTION TYPES

       The option type field is the single-most important field in the table, as the type for an
       option "-foo" determines (along with num_values) what action "GetOptions" takes when it
       sees "-foo" on the command line: how many following arguments become "-foo"'s arguments,
       what regular expression those arguments must conform to, or whether some other action
       should be taken.

       As mentioned above, there are three main classes of argument types:

       argument-driven options
           These are options that imply taking one or more option arguments from the command line
           after the option itself is taken.  The arguments are then copied into some variable
           supplied (by reference) in the option table entry.

       constant-valued options
           These are options that have a constant value associated with them; when the option is
           seen on the command line, that constant is copied to some variable in the caller's
           space.  (Both the constant and the value are supplied in the option table entry.)
           Constants can be scalars, arrays, or hashes.

       other options
           These imply some other action to be taken, usually supplied as a string to "eval" or a
           subroutine to call.

   Argument-driven option types
       string, integer, float
           These are the option types that imply "option arguments", i.e. arguments after the
           option that will be consumed when that option is encountered on the command line and
           copied into the caller's space via some reference.  For instance, if you want an
           option "-foo" to take a single string as an argument, with that string being copied to
           the scalar variable $Foo, then you would have this entry in your option table:

               ["-foo", "string", 1, \$Foo]

           (For conciseness, I've omitted the help_string and argdesc entries in all of the
           example entries in this section.  In reality, you should religiously supply help text
           in order to make your programs easier to use and easier to maintain.)

           If num_values is some n greater than one, then the option_data field must be an array
           reference, and n arguments are copied from the command line into that array.  (The
           array is clobbered each time "-foo" is encountered, not appended to.)  In this case,
           "-foo" is referred to as a vector-valued option, as it must be followed by a fixed
           number of arguments.  (Eventually, I plan to add list-valued options, which take a
           variable number of arguments.)  For example an option table like

               ["-foo", "string", 3, \@Foo]

           would result in the @Foo array being set to the three strings immediately following
           any "-foo" option on the command line.

           The only difference between string, integer, and float options is how picky
           "GetOptions" is about the value(s) it will accept.  For string options, anything is
           OK; for integer options, the values must look like integers (i.e., they must match
           "/[+-]?\d+/"); for float options, the values must look like C floating point numbers
           (trust me, you don't want to see the regexp for this).  Note that since string options
           will accept anything, they might accidentally slurp up arguments that are meant to be
           further options, if the user forgets to put the correct string.  For instance, if
           "-foo" and "-bar" are both scalar-valued string options, and the arguments "-foo -bar"
           are seen on the command-line, then "-bar" will become the argument to "-foo", and
           never be processed as an option itself.  (This could be construed as either a bug or a
           feature.  If you feel really strongly that it's a bug, then complain and I'll consider
           doing something about it.)

           If not enough arguments are found that match the required regular expression,
           "GetOptions" prints to standard error a clear and useful error message, followed by
           the usage summary (if you supplied one), and returns 0.  The error messages look
           something like "-foo option must be followed by an integer", or "-foo option must be
           followed by 3 strings", so it really is enough for your program to "exit 1" without
           printing any further message.

       User-defined patterns
           Since the three option types described above are defined by nothing more than a
           regular expression, it's easy to define your own option types.  For instance, let's
           say you want an option to accept only strings of upper-case letters.  You could then
           call &Getopt::Tabular::AddPatternType as follows:

               &Getopt::Tabular::AddPatternType
                 ("upperstring", "[A-Z]+", "uppercase string")

           Note that the third parameter is optional, and is only supplied to make error messages
           clearer.  For instance, if you now have a scalar-valued option "-zap" of type
           "upperstring":

              ["-zap", "upperstring", 1, \$Zap]

           and the user gets it wrong and puts an argument that doesn't consist of all uppercase
           letters after "-zap", then "GetOptions" will complain that "-zap option must be
           followed by an uppercase string".  If you hadn't supplied the third argument to
           &AddType, then the error message would have been the slightly less helpful "-zap
           option must be followed by an upperstring".  Also, you might have to worry about how
           "GetOptions" pluralizes your description: in this case, it will simply add an "s",
           which works fine much of the time, but not always.  Alternately, you could supply a
           two-element list containing the singular and plural forms:

               &Getopt::Tabular::AddPatternType
                 ("upperstring", "[A-Z]+",
                   ["string of uppercase letters", "strings of uppercase letters"])

           So, if "-zap" instead expects three "upperstring"s, and the user goofs, then the error
           message would be (in the first example) "-zap option must be followed by 3 uppercase
           strings" or "-zap option must be followed by three strings of uppercase letters"
           (second example).

           Of course, if you don't intend to have vector-valued options of your new type,
           pluralization hardly matters.  Also, while it might seem that this is a nice stab in
           the direction of multi-lingual support, the error messages are still hard-coded to
           English in other places.  Maybe in the next version...

   Constant-valued option types
       boolean
           For boolean options, option_data must be a scalar reference; num_values is ignored
           (you can just set it to "undef" or 0).  Booleans are slightly weird in that every
           boolean option implies two possible arguments that will be accepted on the command
           line, called the positive and negative alternatives.  The positive alternative (which
           is what you specify as the option name) results in a true value, while the negative
           alternative results in false.  Most of the time, you can let "GetOptions" pick the
           negative alternative for you: it just inserts "no" after the option prefix, so
           "-clobber" becomes "-noclobber".  (More precisely, "GetOptions" tests all option
           prefixes until one of them matches at the beginning of the option name.  It then
           inserts "no" between this prefix and the rest of the string.  So, if you want to
           support both GNU-style options (like "--clobber") and one-hyphen options ("-c"), be
           sure to give "--" first when setting the option patterns with &SetOptionPatterns.
           Otherwise, the negative alternative to "--clobber" will be "-no-clobber", which might
           not be what you wanted.)  Sometimes, though, you want to explicitly specify the
           negative alternative.  This is done by putting both alternatives in the option name,
           separated by a vertical bar, e.g. "-verbose|-quiet".

           For example, the above two examples might be specified as

               ["-clobber", "boolean", undef, \$Clobber],
               ["-verbose|-quiet", "boolean", undef, \$Verbose],...);

           If "-clobber" is seen on the command line, $Clobber will be set to 1; if "-noclobber"
           is seen, then $Clobber will be set to 0.  Likewise, "-verbose" results in $Verbose
           being set to 1, and "-quiet" will set $Verbose to 0.

       const
           For const options, put a scalar value (not reference) in num_values, and a scalar
           reference in option_data.  For example:

               ["-foo", "const", "hello there", \$Foo]

           On encountering "-foo", "GetOptions" will copy "hello there" to $Foo.

       arrayconst
           For arrayconst options, put an array reference (input) (not an array value) in
           num_values, and another array reference (output) in option_data.  For example:

               ["-foo", "arrayconst", [3, 6, 2], \@Foo]

           On encountering "-foo", "GetOptions" will copy the array "(3,6,2)" into @Foo.

       hashconst
           For hashconst options, put a hash reference (input) (not a hash value) in num_values,
           and another hash reference (output) in option_data.  For example:

               ["-foo", "hashconst", { "Perl"   => "Larry Wall",
                                       "C"      => "Dennis Ritchie",
                                       "Pascal" => "Niklaus Wirth" },
                \%Inventors]

           On encountering "-foo", "GetOptions" will copy into %Inventors a hash relating various
           programming languages to the culprits primarily responsible for their invention.

       copy
           copy options act just like const options, except when num_values is undefined.  In
           that case, the option name itself will be copied to the scalar referenced by
           option_data, rather than the "undef" value that would be copied under these
           circumstances with a const option.  This is useful when one program accepts options
           that it simply passes to a sub-program; for instance, if prog1 calls prog2, and prog2
           might be run with the -foo option, then prog1's argument table might have this option:

               ["-foo", "copy", undef, \$Foo,
                "run prog2 with the -foo option"]

           and later on, you would run prog2 like this:

               system ("prog2 $Foo ...");

           That way, if "-foo" is never seen on prog1's command line, $Foo will be untouched, and
           will expand to the empty string when building the command line for prog2.

           If num_values is anything other than "undef", then copy options behave just like
           constant options.

   Other option types
       call
           For call options, option_data must be a reference to a subroutine.  The subroutine
           will be called with at least two arguments: a string containing the option that
           triggered the call (because the same subroutine might be activated by many options), a
           reference to an array containing all remaining command-line arguments after the
           option, and other arguments specified using the num_values field.  (To be used for
           this purpose, num_values must be an array reference; otherwise, it is ignored.)  For
           example, you might define a subroutine

               sub process_foo
               {
                  my ($opt, $args, $dest) = @_;

                  $$dest = shift @$args;    # not quite right! (see below)
               }

           with a corresponding option table entry:

               ["-foo", "call", [\$Foo], \&process_foo]

           and then "-foo" would act just like a scalar-valued string option that copies into
           $Foo.  (Well, almost ... read on.)

           A subtle point that might be missed from the above code: the value returned by
           &process_foo does matter: if it is false, then "GetOptions" will return 0 to its
           caller, indicating failure.  To make sure that the user gets a useful error message,
           you should supply one by calling "SetError"; doing so will prevent "GetOptions" from
           printing out a rather mysterious (to the end user, at least) message along the lines
           of "subroutine call failed".  The above example has two subtle problems: first, if the
           argument following "-foo" is an empty string, then "process_foo" will return the empty
           string---a false value---thus causing "GetOptions" to fail confusingly.  Second, if
           there no arguments after "-foo", then "process_foo" will return "undef"---again, a
           false value, causing "GetOptions" to fail.

           To solve these problems, we have to define the requirements for the "-foo" option a
           little more rigorously.  Let's say that any string (including the empty string) is
           valid, but that there must be something there.  Then "process_foo" is written as
           follows:

               sub process_foo
               {
                  my ($opt, $args, $dest) = @_;

                  $$dest = shift @$args;
                  (defined $$dest) && return 1;
                  &Getopt::Tabular::SetError
                    ("bad_foo", "$opt option must be followed by a string");
                  return 0;
               }

           The "SetError" routine actually takes two arguments: an error class and an error
           message.  This is explained fully in the "ERROR HANDLING" section, below.  And, if you
           find yourself writing a lot of routines like this, "SetError" is optionally exported
           from "Getopt::Tabular", so you can of course import it into your main package like
           this:

               use Getopt::Tabular qw/GetOptions SetError/;

       eval
           An eval option specifies a chunk of Perl code to be executed ("eval"'d) when the
           option is encountered on the command line.  The code is supplied (as a string) in the
           option_data field; again, num_values is ignored.  For example:

               ["-foo", "eval", undef,
                'print "-foo seen on command line\n"']

           will cause "GetOptions" to print out (via an "eval") the string "-foo seen on the
           command line\n" when -foo is seen.  No other action is taken apart from what you
           include in the eval string.  The code is evaluated in the package from which
           "GetOptions" was called, so you can access variables and subroutines in your program
           easily.  If any error occurs in the "eval", "GetOptions" complains loudly and returns
           0.

           Note that the supplied code is always evaluated in a "no strict" environment---that's
           because Getopt::Tabular is itself "use strict"-compliant, and I didn't want to force
           strictness on every quick hack that uses the module.  (Especially since eval options
           seem to be used mostly in quick hacks.)  (Anyone who knows how to fetch the strictness
           state for another package or scope is welcome to send me hints!)  However, the -w
           state is untouched.

       section
           section options are just used to help formatting the help text.  See "HELP TEXT" below
           for more details.

ERROR HANDLING

       Generally, handling errors in the argument list is pretty transparent: "GetOptions" (or
       one of its minions) generates an error message and assigns an error class, "GetOptions"
       prints the message to the standard error, and returns 0.  You can access the error class
       and error message using the "GetError" routine:

           ($err_class, $err_msg) = &Getopt::Tabular::GetError ();

       (Like "SetError", "GetError" can also be exported from Getopt::Tabular.)  The error
       message is pretty simple---it is an explanation for the end user of what went wrong, which
       is why "GetOptions" just prints it out and forgets about it.  The error class is further
       information that might be useful for your program; the current values are:

       bad_option
           set when something that looks like an option is found on the command line, but it's
           either unknown or an ambiguous abbreviation.

       bad_value
           set when an option is followed by an invalid argument (i.e., one that doesn't match
           the regexp for that type), or the wrong number of arguments.

       bad_call
           set when a subroutine called via a call option or the code evaluated for an eval
           option returns a false value.  The subroutine or eval'd code can override this by
           calling "SetError" itself.

       bad_eval
           set when the code evaluted for an eval option has an error in it.

       help
           set when the user requests help

       Note that most of these are errors on the end user's part, such as bad or missing
       arguments.  There are also errors that can be caused by you, the programmer, such as bad
       or missing values in the option table; these generally result in "GetOptions" croaking so
       that your program dies immediately with enough information that you can figure out where
       the mistake is.  bad_eval is a borderline case; there are conceivably cases where the end
       user's input can result in bogus code to evaluate, so I grouped this one in the "user
       errors" class.  Finally, asking for help isn't really an error, but the assumption is that
       you probably shouldn't continue normal processing after printing out the help---so
       "GetOptions" returns 0 in this case.  You can always fetch the error class with "GetError"
       if you want to treat real errors differently from help requests.

HELP TEXT

       One of Getopt::Tabular's niftier features is the ability to generate and format a pile of
       useful help text from the snippets of help you include in your option table.  The best way
       to illustrate this is with a couple of brief examples.  First, it's helpful to know how
       the user can trigger a help display.  This is quite simple: by default, "GetOptions"
       always has a "-help" option, presence of which on the command line triggers a help
       display.  (Actually, the help option is really your preferred option prefix plus "help".
       So, if you like to make GNU-style options to take precedence as follows:

           &Getopt::Tabular::SetOptionPatterns qw|(--)([\w-]+) (-)(\w+)|;

       then the help option will be "--help".  There is only one help option available, and you
       can set it by calling &SetHelpOption (another optional export).

       Note that in addition to the option help embedded in the option table, "GetOptions" can
       optionally print out two other messages: a descriptive text (usually a short paragraph
       giving a rough overview of what your program does, possibly referring the user to the fine
       manual page), and a usage text.  These are both supplied by calling &SetHelp, e.g.

           $Help = <<HELP;
           This is the foo program.  It reads one file (specified by -infile),
           operates on it some unspecified way (possibly modified by
           -threshold), and does absolutely nothing with the results.
           (The utility of the -clobber option has yet to be established.)
           HELP

           $Usage = <<USAGE;
           usage: foo [options]
                  foo -help to list options
           USAGE

           &Getopt::Tabular::SetHelp ($Help, $Usage)

       Note that either of the long help or usage strings may be empty, in which case
       "GetOptions" simply won't print them.  In the case where both are supplied, the long help
       message is printed first, followed by the option help summary, followed by the usage.
       "GetOptions" inserts enough blank lines to make the output look just fine on its own, so
       you shouldn't pad either the long help or usage message with blanks.  (It looks best if
       each ends with a newline, though, so setting the help strings with here-documents---as in
       this example---is the recommended approach.)

       As an example of the help display generated by a typical option table, let's take a look
       at the following:

           $Verbose = 1;
           $Clobber = 0;
           undef $InFile;
           @Threshold = (0, 1);

           @argtbl = (["-verbose|-quiet", "boolean", 0, \$Verbose,
                       "be noisy"],
                      ["-clobber", "boolean", 0, \$Clobber,
                       "overwrite existing files"],
                      ["-infile", "string", 1, \$InFile,
                       "specify the input file from which to read a large " .
                       "and sundry variety of data, to which many " .
                       "interesting operations will be applied", "<f>"],
                      ["-threshold", "float", 2, \@Threshold,
                       "only consider values between <v1> and <v2>",
                       "<v1> <v2>"]);

       Assuming you haven't supplied long help or usage strings, then when "GetOptions"
       encounters the help option, it will immediately stop parsing arguments and print out the
       following option summary:

           Summary of options:
              -verbose    be noisy [default]
              -quiet      opposite of -verbose
              -clobber    overwrite existing files
              -noclobber  opposite of -clobber [default]
              -infile <f> specify the input file from which to read a large and
                          sundry variety of data, to which many interesting
                          operations will be applied
              -threshold <v1> <v2>
                          only consider values between <v1> and <v2> [default: 0 1]

       There are a number of interesting things to note here.  First, there are three option
       table fields that affect the generation of help text: option, help_string, and argdesc.
       Note how the argdesc strings are simply option placeholders, usually used to 1) indicate
       how many values are expected to follow an option, 2) (possibly) imply what form they take
       (although that's not really shown here), and 3) explain the exact meaning of the values in
       the help text.  argdesc is just a string like the help string; you can put whatever you
       like in it.  What I've shown above is just my personal preference (which may well evolve).

       A new feature with version 0.3 of Getopt::Tabular is the inclusion of default values with
       the help for certain options.  A number of conditions must be fulfilled for this to happen
       for a given option: first, the option type must be one of the "argument-driven" types,
       such as "integer", "float", "string", or a user-defined type.  Second, the option data
       field must refer either to a defined scalar value (for scalar-valued options) or to a list
       of one or more defined values (for vector-valued options).  Thus, in the above example,
       the "-infile" option doesn't have its default printed because the $InFile scalar is
       undefined.  Likewise, if the @Threshold array were the empty list "()", or a list of
       undefined values "(undef,undef)", then the default value for "-threshold" also would not
       have been printed.

       The formatting is done as follows: enough room is made on the right hand side for the
       longest option name, initially omitting the argument placeholders.  Then, if an option has
       placeholders, and there is room for them in between the option and the help string,
       everything (option, placeholders, help string) is printed together.  An example of this is
       the "-infile" option: here, "-infile <f>" is just small enough to fit in the 12-character
       column (10 characters because that is the length of the longest option, and 2 blanks), so
       the help text is placed right after it on the same line.  However, the "-threshold" option
       becomes too long when its argument placeholders are appended to it, so the help text is
       pushed onto the next line.

       In any event, the help string supplied by the caller starts at the same column, and is
       filled to make a nice paragraph of help.  "GetOptions" will fill to the width of the
       terminal (or 80 columns if it fails to find the terminal width).

       Finally, you can have pseudo entries of type section, which are important to make long
       option lists readable (and one consequence of using Getopt::Tabular is programs with
       ridiculously long option lists -- not altogether a bad thing, I suppose).  For example,
       this table fragment:

           @argtbl = (...,
                      ["-foo", "integer", 1, \$Foo,
                       "set the foo value", "f"],
                      ["-enterfoomode", "call", 0, \&enter_foo_mode,
                       "enter foo mode"],
                      ["Non-foo related options", "section"],
                      ["-bar", "string", 2, \@Bar,
                       "set the bar strings (which have nothing whatsoever " .
                       "to do with foo", "<bar1> <bar2>"],
                      ...);

       results in the following chunk of help text:

              -foo f         set the foo value
              -enterfoomode  enter foo mode

           -- Non-foo related options ---------------------------------
              -bar b1 b2     set the bar strings (which have nothing
                             whatsoever to do with foo

       (This example also illustrates a slightly different style of argument placeholder.  Take
       your pick, or invent your own!)

SPOOF MODE

       Since callbacks from the command line ("call" and "eval" options) can do anything, they
       might be quite expensive.  In certain cases, then, you might want to make an initial pass
       over the command line to ensure that everything is OK before parsing it "for real" and
       incurring all those expensive callbacks.  Thus, "Getopt::Tabular" provides a "spoof" mode
       for parsing a command line without side-effects.  In the simplest case, you can access
       spoof mode like this:

          use Getopt::Tabular qw(SpoofGetOptions GetOptions);
            .
            .
            .
          &SpoofGetOptions (\@options, \@ARGV, \@newARGV) || exit 1;

       and then later on, you would call "GetOptions" with the original @ARGV (so it can do what
       "SpoofGetOptions" merely pretended to do):

          &GetOptions (\@options, \@ARGV, \@newARGV) || exit 1;

       For most option types, any errors that "GetOptions" would catch should also be caught by
       "SpoofGetOptions" -- so you might initially think that you can get away without that "||
       exit 1" after calling "GetOptions".  However, it's a good idea for a couple of reasons.
       First, you might inadvertently changed @ARGV -- this is usually a bug and a silly thing to
       do, so you'd probably want your program to crash loudly rather than fail mysteriously
       later on.  Second, and more likely, some of those expensive operations that you're
       initially avoiding by using "SpoofGetOptions" might themselves fail -- which would cause
       "GetOptions" to return false where "SpoofGetOption" completes without a problem.
       (Finally, there's the faint possiblity of bugs in "Getopt::Tabular" that would cause
       different behaviour in spoof mode and real mode -- this really shouldn't happen, though.)

       In reality, using spoof mode requires a bit more work.  In particular, the whole reason
       for spoof argument parsing is to avoid expensive callbacks, but since callbacks can eat
       any number of command line arguments, you have to emulate them in some way.  It's not
       possible for "SpoofGetOptions" to do this for you, so you have to help out by supplying
       "spoof" callbacks.  As an example, let's say you have a callback option that eats one
       argument (a filename) and immediately reads that file:

          @filedata = ();

          sub read_file
          {
             my ($opt, $args) = @_;

             warn ("$opt option requires an argument\n"), return 0 unless @$args;
             my $file = shift @$args;
             open (FILE, $file) ||
                (warn ("$file: $!\n"), return 0);
             push (@filedata, <FILE>);
             close (FILE);
             return 1;
          }

          @options =
             (['-read_file', 'call', undef, \&read_file]);

       Since "-read_file" could occur any number of times on the command line, we might end up
       reading an awful lot of files, and thus it might be a long time before we catch errors
       late in the command line.  Thus, we'd like to do a "spoof" pass over the command line to
       catch all errors.  A simplistic approach would be to supply a spoof callback that just
       eats one argument and returns success:

          sub spoof_read_file
          {
             my ($opt, $args) = @_;
             (warn ("$opt option requires an argument\n"), return 0)
                unless @$args;
             shift @$args;
             return 1;
          }

       Then, you have to tell "Getopt::Tabular" about this alternate callback with no side-
       effects (apart from eating that one argument):

          &Getopt::Tabular::SetSpoofCodes (-read_file => \&spoof_read_file);

       ("SetSpoofCodes" just takes a list of key/value pairs, where the keys are "call" or "eval"
       options, and the values are the "no side-effects" callbacks.  Naturally, the replacement
       callback for an "eval" option should be a string, and for a "call" option it should be a
       code reference.  This is not actually checked, however, until you call "SpoofGetOptions",
       because "SetSpoofCodes" doesn't know whether options are "call" or "eval" or what.)

       A more useful "spoof_read_file", however, would actually check if the requested file
       exists -- i.e., we should try to catch as many errors as possible, as early as possible:

          sub spoof_read_file
          {
             my ($opt, $args) = @_;
             warn ("$opt option requires an argument\n"), return 0
                unless @$args;
             my $file = shift @$args;
             warn ("$file does not exist or is not readable\n"), return 0
                unless -r $file;
             return 1;
          }

       Finally, you can frequently merge the "real" and "spoof" callback into one subroutine:

          sub read_file
          {
             my ($opt, $args, $spoof) = @_;

             warn ("$opt option requires an argument\n"), return 0 unless @$args;
             my $file = shift @$args;
             warn ("$file does not exist or is not readable\n"), return 0
                unless -r $file;
             return 1 if $spoof;
             open (FILE, $file) ||
                (warn ("$file: $!\n"), return 0);
             push (@filedata, <FILE>);
             close (FILE);
             return 1;
          }

       And then, when specifying the replacement callback to "SetSpoofCodes", just create an
       anonymous sub that calls "read_file" with $spoof true:

          &Getopt::Tabular::SetSpoofCodes
             (-read_file => sub { &read_file (@_[0,1], 1) });

       Even though this means a bigger and more complicated callback, you only need one such
       callback -- the alternative is to carry around both "read_file" and "spoof_read_file",
       which might do redundant processing of the argument list.

AUTHOR

       Greg Ward <greg@bic.mni.mcgill.ca>

       Started in July, 1995 as ParseArgs.pm, with John Ousterhout's Tk_ParseArgv.c as a loose
       inspiration.  Many many features added over the ensuing months; documentation written in a
       mad frenzy 16-18 April, 1996.  Renamed to Getopt::Tabular, revamped, reorganized, and
       documentation expanded 8-11 November, 1996.

       Copyright (c) 1995-97 Greg Ward. All rights reserved.  This is free software; you can
       redistribute it and/or modify it under the same terms as Perl itself.

BUGS

       The documentation is bigger than the code, and I still haven't covered option patterns or
       extending the type system (apart from pattern types).  Yow!

       No support for list-valued options, although you can roll your own with call options.
       (See the demo program included with the distribution for an example.)

       Error messages are hard-coded to English.