1Tabular(3)            User Contributed Perl Documentation           Tabular(3)
2
3
4

NAME

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

SYNOPSIS

9           use Getopt::Tabular;
10
11       (or)
12
13           use Getopt::Tabular qw/GetOptions
14                                  SetHelp SetHelpOption
15                                  SetError GetError/;
16
17           ...
18
19           &Getopt::Tabular::SetHelp (long_help, usage_string);
20
21           @opt_table = (
22                         [section_description, "section"],
23                         [option, type, num_values, option_data, help_string],
24                         ...
25                        );
26           &GetOptions (\@opt_table, \@ARGV [, \@newARGV]) || exit 1;
27

DESCRIPTION

29       Getopt::Tabular is a Perl 5 module for table-driven argument parsing,
30       vaguely inspired by John Ousterhout's Tk_ParseArgv.  All you really
31       need to do to use the package is set up a table describing all your
32       command-line options, and call &GetOptions with three arguments: a
33       reference to your option table, a reference to @ARGV (or something like
34       it), and an optional third array reference (say, to @newARGV).
35       &GetOptions will process all arguments in @ARGV, and copy any leftover
36       arguments (i.e. those that are not options or arguments to some option)
37       to the @newARGV array.  (If the @newARGV argument is not supplied,
38       "GetOptions" will replace @ARGV with the stripped-down argument list.)
39       If there are any invalid options, "GetOptions" will print an error
40       message and return 0.
41
42       Before I tell you all about why Getopt::Tabular is a wonderful thing,
43       let me explain some of the terminology that will keep popping up here.
44
45       argument
46           any single word appearing on the command-line, i.e. one element of
47           the @ARGV array.
48
49       option
50           an argument that starts with a certain sequence of characters; the
51           default is "-".  (If you like GNU-style options, you can change
52           this to "--".)  In most Getopt::Tabular-based applications, options
53           can come anywhere on the command line, and their order is
54           unimportant (unless one option overrides a previous option).  Also,
55           Getopt::Tabular will allow any non-ambiguous abbreviation of
56           options.
57
58       option argument
59           (or value) an argument that immediately follows certain types of
60           options.  For instance, if "-foo" is a scalar-valued integer
61           option, and "-foo 3" appears on the command line, then 3 will be
62           the argument to "-foo".
63
64       option type
65           controls how "GetOptions" deals with an option and the arguments
66           that follow it.  (Actually, for most option types, the type
67           interacts with the "num_values" field, which determines whether the
68           option is scalar- or vector-valued.  This will be fully explained
69           in due course.)
70

FEATURES

72       Now for the advertising, i.e. why Getopt::Tabular is a good thing.
73
74       ·   Command-line arguments are carefully type-checked, both by pattern
75           and number---e.g. if an option requires two integers, GetOptions
76           makes sure that exactly two integers follow it!
77
78       ·   The valid command-line arguments are specified in a data structure
79           separate from the call to GetOptions; this makes it easier to have
80           very long lists of options, and to parse options from multiple
81           sources (e.g. the command line, an environment variable, and a
82           configuration file).
83
84       ·   Getopt::Tabular can intelligently generate help text based on your
85           option descriptions.
86
87       ·   The type system is extensible, and if you can define your desired
88           argument type using a single Perl regular expression then it's
89           particularly easy to extend.
90
91       ·   To make your program look smarter, options can be abbreviated and
92           come in any order.
93
94       ·
95
96
97            You can parse options in a "spoof" mode that has no side-effects -- this
98           is useful for making a validation pass over the command line without
99           actually doing anything.
100
101       In general, I have found that Getopt::Tabular tends to encourage
102       programs with long lists of sophisticated options, leading to great
103       flexibility, intelligent operation, and the potential for insanely long
104       command lines.
105

BASIC OPERATION

107       The basic operation of Getopt::Tabular is driven by an option table,
108       which is just a list of option descriptions (otherwise known as option
109       table entries, or just entries).  Each option description tells
110       "GetOptions" everything it needs to know when it encounters a
111       particular option on the command line.  For instance,
112
113           ["-foo", "integer", 2, \@Foo, "set the foo values"]
114
115       means that whenever "-foo" is seen on the command line, "GetOptions" is
116       to make sure that the next two arguments are integers, and copy them
117       into the caller's @Foo array.  (Well, really into the @Foo array where
118       the option table is defined.  This is almost always the same as
119       "GetOptions"' caller, though.)
120
121       Typically, you'll group a bunch of option descriptions together like
122       this:
123
124           @options =
125               (["-range", "integer", 2, \@Range,
126                 "set the range of allowed values"],
127                ["-file", "string", 1, \$File,
128                  "set the output file"],
129                ["-clobber", "boolean", 0, \$Clobber,
130                  "clobber existing files"],
131                ...
132               );
133
134       and then call "GetOptions" like this:
135
136           &GetOptions (\@options, \@ARGV) || exit 1;
137
138       which replaces @ARGV with a new array containing all the arguments
139       left-over after options and their arguments have been removed.  You can
140       also call "GetOptions" with three arguments, like this:
141
142           &GetOptions (\@options, \@ARGV, \@newARGV) || exit 1;
143
144       in which case @ARGV is untouched, and @newARGV gets the leftover
145       arguments.
146
147       In case of error, "GetOptions" prints enough information for the user
148       to figure out what's going wrong.  If you supply one, it'll even print
149       out a brief usage message in case of error.  Thus, it's enough to just
150       "exit 1" when "GetOptions" indicates an error by returning 0.
151
152       Detailed descriptions of the contents of an option table entry are
153       given next, followed by the complete run-down of available types, full
154       details on error handling, and how help text is generated.
155

OPTION TABLE ENTRIES

157       The fields in the option table control how arguments are parsed, so
158       it's important to understand each one in turn.  First, the format of
159       entries in the table is fairly rigid, even though this isn't really
160       necessary with Perl.  It's done that way to make the Getopt::Tabular
161       code a little easier; the drawback is that some entries will have
162       unused values (e.g. the "num_values" field is never used for boolean
163       options, but you still have to put something there as a place-holder).
164       The fields are as follows:
165
166       option
167           This is the option name, e.g. "-verbose" or "-some_value".  For
168           most option types, this is simply an option prefix followed by
169           text; for boolean options, however, it can be a little more
170           complicated.  (The exact rules are discussed under "OPTION TYPES".)
171           And yes, even though you tell Getopt::Tabular the valid option
172           prefixes, you still have to put one onto the option names in the
173           table.
174
175       type
176           The option type decides what action will be taken when this option
177           is seen on the command line, and (if applicable) what sort of
178           values will be accepted for this option.  There are three broad
179           classes of types: those that imply copying data from the command
180           line into some variable in the caller's space; those that imply
181           copying constant data into the caller's space without taking any
182           more arguments from the command line; and those that imply some
183           other action to be taken.  The available option types are covered
184           in greater detail below (see "OPTION TYPES"), but briefly:
185           "string", "integer", and "float" all imply copying values from the
186           command line to a variable; "constant", "boolean", "copy",
187           "arrayconst", and "hashconst" all imply copying some pre-defined
188           data into a variable; "call" and "eval" allow the execution of some
189           arbitrary subroutine or chunk of code; and "help" options will
190           cause "GetOptions" to print out all available help text and return
191           0.
192
193       num_values
194           for "string", "integer", and "float" options, this determines
195           whether the option is a scalar (num_values = 1) or vector
196           (num_values > 1) option.  (Note that whether the option is scalar-
197           or vector-valued has an important influence on what you must supply
198           in the option_data field!)  For "constant", "copy", "arrayconst",
199           and "hashconst" option types, num_values is a bit of a misnomer: it
200           actually contains the value (or a reference to it, if array or
201           hash) to be copied when the option is encountered.  For "call"
202           options, num_values can be used to supply extra arguments to the
203           called subroutine.  In any case, though, you can think of
204           num_values as an input value.  For "boolean" and "eval" options,
205           num_values is ignored and should be "undef" or 0.
206
207       option_data
208           For "string", "integer", "float", "boolean", "constant", "copy",
209           "arrayconst", and "hashconst" types, this must be a reference to
210           the variable into which you want "GetOptions" to copy the
211           appropriate thing.  The "appropriate thing" is either the
212           argument(s) following the option, the constant supplied as
213           num_values, or 1 or 0 (for boolean options).
214
215           For "boolean", "constant", "copy", and scalar-valued "string",
216           "integer", and "float" options, this must be a scalar reference.
217           For vector-valued "string", "integer", and "float" options
218           (num_values > 1), and for "arrayconst" options, this must be an
219           array reference.  For "hashconst" options, this must be a hash
220           reference.
221
222           Finally, option_data is also used as an input value for "call" and
223           "eval" options: for "call", it should be a subroutine reference,
224           and for "eval" options, it should be a string containing valid Perl
225           code to evaluate when the option is seen.  The subroutine called by
226           a "call" option should take at least two arguments: a string, which
227           is the actual option that triggered the call (because the same
228           subroutine could be tied to many options), and an array reference,
229           which contains all command line arguments after that option.
230           (Further arguments can be supplied in the num_values field.)  The
231           subroutine may freely modify this array, and those modifications
232           will affect the behaviour of "GetOptions" afterwards.
233
234           The chunk of code passed to an "eval" option is evaluated in the
235           package from which "GetOptions" is called, and does not have access
236           to any internal Getopt::Tabular data.
237
238       help_string
239           (optional) a brief description of the option.  Don't worry about
240           formatting this in any way; when "GetOptions" has to print out your
241           help, it will do so quite nicely without any intervention.  If the
242           help string is not defined, then that option will not be included
243           in the option help text.  (However, you could supply an empty
244           string -- which is defined -- to make "GetOptions" just print out
245           the option name, but nothing else.)
246
247       arg_desc
248           (optional) an even briefer description of the values that you
249           expect to follow your option.  This is mainly used to supply place-
250           holders in the help string, and is specified separately so that
251           "GetOptions" can act fairly intelligently when formatting a help
252           message.  See "HELP TEXT" for more information.
253

OPTION TYPES

255       The option type field is the single-most important field in the table,
256       as the type for an option "-foo" determines (along with num_values)
257       what action "GetOptions" takes when it sees "-foo" on the command line:
258       how many following arguments become "-foo"'s arguments, what regular
259       expression those arguments must conform to, or whether some other
260       action should be taken.
261
262       As mentioned above, there are three main classes of argument types:
263
264       argument-driven options
265           These are options that imply taking one or more option arguments
266           from the command line after the option itself is taken.  The
267           arguments are then copied into some variable supplied (by
268           reference) in the option table entry.
269
270       constant-valued options
271           These are options that have a constant value associated with them;
272           when the option is seen on the command line, that constant is
273           copied to some variable in the caller's space.  (Both the constant
274           and the value are supplied in the option table entry.)  Constants
275           can be scalars, arrays, or hashes.
276
277       other options
278           These imply some other action to be taken, usually supplied as a
279           string to "eval" or a subroutine to call.
280
281   Argument-driven option types
282       string, integer, float
283           These are the option types that imply "option arguments", i.e.
284           arguments after the option that will be consumed when that option
285           is encountered on the command line and copied into the caller's
286           space via some reference.  For instance, if you want an option
287           "-foo" to take a single string as an argument, with that string
288           being copied to the scalar variable $Foo, then you would have this
289           entry in your option table:
290
291               ["-foo", "string", 1, \$Foo]
292
293           (For conciseness, I've omitted the help_string and argdesc entries
294           in all of the example entries in this section.  In reality, you
295           should religiously supply help text in order to make your programs
296           easier to use and easier to maintain.)
297
298           If num_values is some n greater than one, then the option_data
299           field must be an array reference, and n arguments are copied from
300           the command line into that array.  (The array is clobbered each
301           time "-foo" is encountered, not appended to.)  In this case, "-foo"
302           is referred to as a vector-valued option, as it must be followed by
303           a fixed number of arguments.  (Eventually, I plan to add list-
304           valued options, which take a variable number of arguments.)  For
305           example an option table like
306
307               ["-foo", "string", 3, \@Foo]
308
309           would result in the @Foo array being set to the three strings
310           immediately following any "-foo" option on the command line.
311
312           The only difference between string, integer, and float options is
313           how picky "GetOptions" is about the value(s) it will accept.  For
314           string options, anything is OK; for integer options, the values
315           must look like integers (i.e., they must match "/[+-]?\d+/"); for
316           float options, the values must look like C floating point numbers
317           (trust me, you don't want to see the regexp for this).  Note that
318           since string options will accept anything, they might accidentally
319           slurp up arguments that are meant to be further options, if the
320           user forgets to put the correct string.  For instance, if "-foo"
321           and "-bar" are both scalar-valued string options, and the arguments
322           "-foo -bar" are seen on the command-line, then "-bar" will become
323           the argument to "-foo", and never be processed as an option itself.
324           (This could be construed as either a bug or a feature.  If you feel
325           really strongly that it's a bug, then complain and I'll consider
326           doing something about it.)
327
328           If not enough arguments are found that match the required regular
329           expression, "GetOptions" prints to standard error a clear and
330           useful error message, followed by the usage summary (if you
331           supplied one), and returns 0.  The error messages look something
332           like "-foo option must be followed by an integer", or "-foo option
333           must be followed by 3 strings", so it really is enough for your
334           program to "exit 1" without printing any further message.
335
336       User-defined patterns
337           Since the three option types described above are defined by nothing
338           more than a regular expression, it's easy to define your own option
339           types.  For instance, let's say you want an option to accept only
340           strings of upper-case letters.  You could then call
341           &Getopt::Tabular::AddPatternType as follows:
342
343               &Getopt::Tabular::AddPatternType
344                 ("upperstring", "[A-Z]+", "uppercase string")
345
346           Note that the third parameter is optional, and is only supplied to
347           make error messages clearer.  For instance, if you now have a
348           scalar-valued option "-zap" of type "upperstring":
349
350              ["-zap", "upperstring", 1, \$Zap]
351
352           and the user gets it wrong and puts an argument that doesn't
353           consist of all uppercase letters after "-zap", then "GetOptions"
354           will complain that "-zap option must be followed by an uppercase
355           string".  If you hadn't supplied the third argument to &AddType,
356           then the error message would have been the slightly less helpful
357           "-zap option must be followed by an upperstring".  Also, you might
358           have to worry about how "GetOptions" pluralizes your description:
359           in this case, it will simply add an "s", which works fine much of
360           the time, but not always.  Alternately, you could supply a two-
361           element list containing the singular and plural forms:
362
363               &Getopt::Tabular::AddPatternType
364                 ("upperstring", "[A-Z]+",
365                   ["string of uppercase letters", "strings of uppercase letters"])
366
367           So, if "-zap" instead expects three "upperstring"s, and the user
368           goofs, then the error message would be (in the first example) "-zap
369           option must be followed by 3 uppercase strings" or "-zap option
370           must be followed by three strings of uppercase letters" (second
371           example).
372
373           Of course, if you don't intend to have vector-valued options of
374           your new type, pluralization hardly matters.  Also, while it might
375           seem that this is a nice stab in the direction of multi-lingual
376           support, the error messages are still hard-coded to English in
377           other places.  Maybe in the next version...
378
379   Constant-valued option types
380       boolean
381           For boolean options, option_data must be a scalar reference;
382           num_values is ignored (you can just set it to "undef" or 0).
383           Booleans are slightly weird in that every boolean option implies
384           two possible arguments that will be accepted on the command line,
385           called the positive and negative alternatives.  The positive
386           alternative (which is what you specify as the option name) results
387           in a true value, while the negative alternative results in false.
388           Most of the time, you can let "GetOptions" pick the negative
389           alternative for you: it just inserts "no" after the option prefix,
390           so "-clobber" becomes "-noclobber".  (More precisely, "GetOptions"
391           tests all option prefixes until one of them matches at the
392           beginning of the option name.  It then inserts "no" between this
393           prefix and the rest of the string.  So, if you want to support both
394           GNU-style options (like "--clobber") and one-hyphen options ("-c"),
395           be sure to give "--" first when setting the option patterns with
396           &SetOptionPatterns.  Otherwise, the negative alternative to
397           "--clobber" will be "-no-clobber", which might not be what you
398           wanted.)  Sometimes, though, you want to explicitly specify the
399           negative alternative.  This is done by putting both alternatives in
400           the option name, separated by a vertical bar, e.g.
401           "-verbose|-quiet".
402
403           For example, the above two examples might be specified as
404
405               ["-clobber", "boolean", undef, \$Clobber],
406               ["-verbose|-quiet", "boolean", undef, \$Verbose],...);
407
408           If "-clobber" is seen on the command line, $Clobber will be set to
409           1; if "-noclobber" is seen, then $Clobber will be set to 0.
410           Likewise, "-verbose" results in $Verbose being set to 1, and
411           "-quiet" will set $Verbose to 0.
412
413       const
414           For const options, put a scalar value (not reference) in
415           num_values, and a scalar reference in option_data.  For example:
416
417               ["-foo", "const", "hello there", \$Foo]
418
419           On encountering "-foo", "GetOptions" will copy "hello there" to
420           $Foo.
421
422       arrayconst
423           For arrayconst options, put an array reference (input) (not an
424           array value) in num_values, and another array reference (output) in
425           option_data.  For example:
426
427               ["-foo", "arrayconst", [3, 6, 2], \@Foo]
428
429           On encountering "-foo", "GetOptions" will copy the array "(3,6,2)"
430           into @Foo.
431
432       hashconst
433           For hashconst options, put a hash reference (input) (not a hash
434           value) in num_values, and another hash reference (output) in
435           option_data.  For example:
436
437               ["-foo", "hashconst", { "Perl"   => "Larry Wall",
438                                       "C"      => "Dennis Ritchie",
439                                       "Pascal" => "Niklaus Wirth" },
440                \%Inventors]
441
442           On encountering "-foo", "GetOptions" will copy into %Inventors a
443           hash relating various programming languages to the culprits
444           primarily responsible for their invention.
445
446       copy
447           copy options act just like const options, except when num_values is
448           undefined.  In that case, the option name itself will be copied to
449           the scalar referenced by option_data, rather than the "undef" value
450           that would be copied under these circumstances with a const option.
451           This is useful when one program accepts options that it simply
452           passes to a sub-program; for instance, if prog1 calls prog2, and
453           prog2 might be run with the -foo option, then prog1's argument
454           table might have this option:
455
456               ["-foo", "copy", undef, \$Foo,
457                "run prog2 with the -foo option"]
458
459           and later on, you would run prog2 like this:
460
461               system ("prog2 $Foo ...");
462
463           That way, if "-foo" is never seen on prog1's command line, $Foo
464           will be untouched, and will expand to the empty string when
465           building the command line for prog2.
466
467           If num_values is anything other than "undef", then copy options
468           behave just like constant options.
469
470   Other option types
471       call
472           For call options, option_data must be a reference to a subroutine.
473           The subroutine will be called with at least two arguments: a string
474           containing the option that triggered the call (because the same
475           subroutine might be activated by many options), a reference to an
476           array containing all remaining command-line arguments after the
477           option, and other arguments specified using the num_values field.
478           (To be used for this purpose, num_values must be an array
479           reference; otherwise, it is ignored.)  For example, you might
480           define a subroutine
481
482               sub process_foo
483               {
484                  my ($opt, $args, $dest) = @_;
485
486                  $$dest = shift @$args;    # not quite right! (see below)
487               }
488
489           with a corresponding option table entry:
490
491               ["-foo", "call", [\$Foo], \&process_foo]
492
493           and then "-foo" would act just like a scalar-valued string option
494           that copies into $Foo.  (Well, almost ... read on.)
495
496           A subtle point that might be missed from the above code: the value
497           returned by &process_foo does matter: if it is false, then
498           "GetOptions" will return 0 to its caller, indicating failure.  To
499           make sure that the user gets a useful error message, you should
500           supply one by calling "SetError"; doing so will prevent
501           "GetOptions" from printing out a rather mysterious (to the end
502           user, at least) message along the lines of "subroutine call
503           failed".  The above example has two subtle problems: first, if the
504           argument following "-foo" is an empty string, then "process_foo"
505           will return the empty string---a false value---thus causing
506           "GetOptions" to fail confusingly.  Second, if there no arguments
507           after "-foo", then "process_foo" will return "undef"---again, a
508           false value, causing "GetOptions" to fail.
509
510           To solve these problems, we have to define the requirements for the
511           "-foo" option a little more rigorously.  Let's say that any string
512           (including the empty string) is valid, but that there must be
513           something there.  Then "process_foo" is written as follows:
514
515               sub process_foo
516               {
517                  my ($opt, $args, $dest) = @_;
518
519                  $$dest = shift @$args;
520                  (defined $$dest) && return 1;
521                  &Getopt::Tabular::SetError
522                    ("bad_foo", "$opt option must be followed by a string");
523                  return 0;
524               }
525
526           The "SetError" routine actually takes two arguments: an error class
527           and an error message.  This is explained fully in the "ERROR
528           HANDLING" section, below.  And, if you find yourself writing a lot
529           of routines like this, "SetError" is optionally exported from
530           "Getopt::Tabular", so you can of course import it into your main
531           package like this:
532
533               use Getopt::Tabular qw/GetOptions SetError/;
534
535       eval
536           An eval option specifies a chunk of Perl code to be executed
537           ("eval"'d) when the option is encountered on the command line.  The
538           code is supplied (as a string) in the option_data field; again,
539           num_values is ignored.  For example:
540
541               ["-foo", "eval", undef,
542                'print "-foo seen on command line\n"']
543
544           will cause "GetOptions" to print out (via an "eval") the string
545           "-foo seen on the command line\n" when -foo is seen.  No other
546           action is taken apart from what you include in the eval string.
547           The code is evaluated in the package from which "GetOptions" was
548           called, so you can access variables and subroutines in your program
549           easily.  If any error occurs in the "eval", "GetOptions" complains
550           loudly and returns 0.
551
552           Note that the supplied code is always evaluated in a "no strict"
553           environment---that's because Getopt::Tabular is itself "use
554           strict"-compliant, and I didn't want to force strictness on every
555           quick hack that uses the module.  (Especially since eval options
556           seem to be used mostly in quick hacks.)  (Anyone who knows how to
557           fetch the strictness state for another package or scope is welcome
558           to send me hints!)  However, the -w state is untouched.
559
560       section
561           section options are just used to help formatting the help text.
562           See "HELP TEXT" below for more details.
563

ERROR HANDLING

565       Generally, handling errors in the argument list is pretty transparent:
566       "GetOptions" (or one of its minions) generates an error message and
567       assigns an error class, "GetOptions" prints the message to the standard
568       error, and returns 0.  You can access the error class and error message
569       using the "GetError" routine:
570
571           ($err_class, $err_msg) = &Getopt::Tabular::GetError ();
572
573       (Like "SetError", "GetError" can also be exported from
574       Getopt::Tabular.)  The error message is pretty simple---it is an
575       explanation for the end user of what went wrong, which is why
576       "GetOptions" just prints it out and forgets about it.  The error class
577       is further information that might be useful for your program; the
578       current values are:
579
580       bad_option
581           set when something that looks like an option is found on the
582           command line, but it's either unknown or an ambiguous abbreviation.
583
584       bad_value
585           set when an option is followed by an invalid argument (i.e., one
586           that doesn't match the regexp for that type), or the wrong number
587           of arguments.
588
589       bad_call
590           set when a subroutine called via a call option or the code
591           evaluated for an eval option returns a false value.  The subroutine
592           or eval'd code can override this by calling "SetError" itself.
593
594       bad_eval
595           set when the code evaluted for an eval option has an error in it.
596
597       help
598           set when the user requests help
599
600       Note that most of these are errors on the end user's part, such as bad
601       or missing arguments.  There are also errors that can be caused by you,
602       the programmer, such as bad or missing values in the option table;
603       these generally result in "GetOptions" croaking so that your program
604       dies immediately with enough information that you can figure out where
605       the mistake is.  bad_eval is a borderline case; there are conceivably
606       cases where the end user's input can result in bogus code to evaluate,
607       so I grouped this one in the "user errors" class.  Finally, asking for
608       help isn't really an error, but the assumption is that you probably
609       shouldn't continue normal processing after printing out the help---so
610       "GetOptions" returns 0 in this case.  You can always fetch the error
611       class with "GetError" if you want to treat real errors differently from
612       help requests.
613

HELP TEXT

615       One of Getopt::Tabular's niftier features is the ability to generate
616       and format a pile of useful help text from the snippets of help you
617       include in your option table.  The best way to illustrate this is with
618       a couple of brief examples.  First, it's helpful to know how the user
619       can trigger a help display.  This is quite simple: by default,
620       "GetOptions" always has a "-help" option, presence of which on the
621       command line triggers a help display.  (Actually, the help option is
622       really your preferred option prefix plus "help".  So, if you like to
623       make GNU-style options to take precedence as follows:
624
625           &Getopt::Tabular::SetOptionPatterns qw|(--)([\w-]+) (-)(\w+)|;
626
627       then the help option will be "--help".  There is only one help option
628       available, and you can set it by calling &SetHelpOption (another
629       optional export).
630
631       Note that in addition to the option help embedded in the option table,
632       "GetOptions" can optionally print out two other messages: a descriptive
633       text (usually a short paragraph giving a rough overview of what your
634       program does, possibly referring the user to the fine manual page), and
635       a usage text.  These are both supplied by calling &SetHelp, e.g.
636
637           $Help = <<HELP;
638           This is the foo program.  It reads one file (specified by -infile),
639           operates on it some unspecified way (possibly modified by
640           -threshold), and does absolutely nothing with the results.
641           (The utility of the -clobber option has yet to be established.)
642           HELP
643
644           $Usage = <<USAGE;
645           usage: foo [options]
646                  foo -help to list options
647           USAGE
648
649           &Getopt::Tabular::SetHelp ($Help, $Usage)
650
651       Note that either of the long help or usage strings may be empty, in
652       which case "GetOptions" simply won't print them.  In the case where
653       both are supplied, the long help message is printed first, followed by
654       the option help summary, followed by the usage.  "GetOptions" inserts
655       enough blank lines to make the output look just fine on its own, so you
656       shouldn't pad either the long help or usage message with blanks.  (It
657       looks best if each ends with a newline, though, so setting the help
658       strings with here-documents---as in this example---is the recommended
659       approach.)
660
661       As an example of the help display generated by a typical option table,
662       let's take a look at the following:
663
664           $Verbose = 1;
665           $Clobber = 0;
666           undef $InFile;
667           @Threshold = (0, 1);
668
669           @argtbl = (["-verbose|-quiet", "boolean", 0, \$Verbose,
670                       "be noisy"],
671                      ["-clobber", "boolean", 0, \$Clobber,
672                       "overwrite existing files"],
673                      ["-infile", "string", 1, \$InFile,
674                       "specify the input file from which to read a large " .
675                       "and sundry variety of data, to which many " .
676                       "interesting operations will be applied", "<f>"],
677                      ["-threshold", "float", 2, \@Threshold,
678                       "only consider values between <v1> and <v2>",
679                       "<v1> <v2>"]);
680
681       Assuming you haven't supplied long help or usage strings, then when
682       "GetOptions" encounters the help option, it will immediately stop
683       parsing arguments and print out the following option summary:
684
685           Summary of options:
686              -verbose    be noisy [default]
687              -quiet      opposite of -verbose
688              -clobber    overwrite existing files
689              -noclobber  opposite of -clobber [default]
690              -infile <f> specify the input file from which to read a large and
691                          sundry variety of data, to which many interesting
692                          operations will be applied
693              -threshold <v1> <v2>
694                          only consider values between <v1> and <v2> [default: 0 1]
695
696       There are a number of interesting things to note here.  First, there
697       are three option table fields that affect the generation of help text:
698       option, help_string, and argdesc.  Note how the argdesc strings are
699       simply option placeholders, usually used to 1) indicate how many values
700       are expected to follow an option, 2) (possibly) imply what form they
701       take (although that's not really shown here), and 3) explain the exact
702       meaning of the values in the help text.  argdesc is just a string like
703       the help string; you can put whatever you like in it.  What I've shown
704       above is just my personal preference (which may well evolve).
705
706       A new feature with version 0.3 of Getopt::Tabular is the inclusion of
707       default values with the help for certain options.  A number of
708       conditions must be fulfilled for this to happen for a given option:
709       first, the option type must be one of the "argument-driven" types, such
710       as "integer", "float", "string", or a user-defined type.  Second, the
711       option data field must refer either to a defined scalar value (for
712       scalar-valued options) or to a list of one or more defined values (for
713       vector-valued options).  Thus, in the above example, the "-infile"
714       option doesn't have its default printed because the $InFile scalar is
715       undefined.  Likewise, if the @Threshold array were the empty list "()",
716       or a list of undefined values "(undef,undef)", then the default value
717       for "-threshold" also would not have been printed.
718
719       The formatting is done as follows: enough room is made on the right
720       hand side for the longest option name, initially omitting the argument
721       placeholders.  Then, if an option has placeholders, and there is room
722       for them in between the option and the help string, everything (option,
723       placeholders, help string) is printed together.  An example of this is
724       the "-infile" option: here, "-infile <f>" is just small enough to fit
725       in the 12-character column (10 characters because that is the length of
726       the longest option, and 2 blanks), so the help text is placed right
727       after it on the same line.  However, the "-threshold" option becomes
728       too long when its argument placeholders are appended to it, so the help
729       text is pushed onto the next line.
730
731       In any event, the help string supplied by the caller starts at the same
732       column, and is filled to make a nice paragraph of help.  "GetOptions"
733       will fill to the width of the terminal (or 80 columns if it fails to
734       find the terminal width).
735
736       Finally, you can have pseudo entries of type section, which are
737       important to make long option lists readable (and one consequence of
738       using Getopt::Tabular is programs with ridiculously long option lists
739       -- not altogether a bad thing, I suppose).  For example, this table
740       fragment:
741
742           @argtbl = (...,
743                      ["-foo", "integer", 1, \$Foo,
744                       "set the foo value", "f"],
745                      ["-enterfoomode", "call", 0, \&enter_foo_mode,
746                       "enter foo mode"],
747                      ["Non-foo related options", "section"],
748                      ["-bar", "string", 2, \@Bar,
749                       "set the bar strings (which have nothing whatsoever " .
750                       "to do with foo", "<bar1> <bar2>"],
751                      ...);
752
753       results in the following chunk of help text:
754
755              -foo f         set the foo value
756              -enterfoomode  enter foo mode
757
758           -- Non-foo related options ---------------------------------
759              -bar b1 b2     set the bar strings (which have nothing
760                             whatsoever to do with foo
761
762       (This example also illustrates a slightly different style of argument
763       placeholder.  Take your pick, or invent your own!)
764

SPOOF MODE

766       Since callbacks from the command line ("call" and "eval" options) can
767       do anything, they might be quite expensive.  In certain cases, then,
768       you might want to make an initial pass over the command line to ensure
769       that everything is OK before parsing it "for real" and incurring all
770       those expensive callbacks.  Thus, "Getopt::Tabular" provides a "spoof"
771       mode for parsing a command line without side-effects.  In the simplest
772       case, you can access spoof mode like this:
773
774          use Getopt::Tabular qw(SpoofGetOptions GetOptions);
775            .
776            .
777            .
778          &SpoofGetOptions (\@options, \@ARGV, \@newARGV) || exit 1;
779
780       and then later on, you would call "GetOptions" with the original @ARGV
781       (so it can do what "SpoofGetOptions" merely pretended to do):
782
783          &GetOptions (\@options, \@ARGV, \@newARGV) || exit 1;
784
785       For most option types, any errors that "GetOptions" would catch should
786       also be caught by "SpoofGetOptions" -- so you might initially think
787       that you can get away without that "|| exit 1" after calling
788       "GetOptions".  However, it's a good idea for a couple of reasons.
789       First, you might inadvertently changed @ARGV -- this is usually a bug
790       and a silly thing to do, so you'd probably want your program to crash
791       loudly rather than fail mysteriously later on.  Second, and more
792       likely, some of those expensive operations that you're initially
793       avoiding by using "SpoofGetOptions" might themselves fail -- which
794       would cause "GetOptions" to return false where "SpoofGetOption"
795       completes without a problem.  (Finally, there's the faint possiblity of
796       bugs in "Getopt::Tabular" that would cause different behaviour in spoof
797       mode and real mode -- this really shouldn't happen, though.)
798
799       In reality, using spoof mode requires a bit more work.  In particular,
800       the whole reason for spoof argument parsing is to avoid expensive
801       callbacks, but since callbacks can eat any number of command line
802       arguments, you have to emulate them in some way.  It's not possible for
803       "SpoofGetOptions" to do this for you, so you have to help out by
804       supplying "spoof" callbacks.  As an example, let's say you have a
805       callback option that eats one argument (a filename) and immediately
806       reads that file:
807
808          @filedata = ();
809
810          sub read_file
811          {
812             my ($opt, $args) = @_;
813
814             warn ("$opt option requires an argument\n"), return 0 unless @$args;
815             my $file = shift @$args;
816             open (FILE, $file) ||
817                (warn ("$file: $!\n"), return 0);
818             push (@filedata, <FILE>);
819             close (FILE);
820             return 1;
821          }
822
823          @options =
824             (['-read_file', 'call', undef, \&read_file]);
825
826       Since "-read_file" could occur any number of times on the command line,
827       we might end up reading an awful lot of files, and thus it might be a
828       long time before we catch errors late in the command line.  Thus, we'd
829       like to do a "spoof" pass over the command line to catch all errors.  A
830       simplistic approach would be to supply a spoof callback that just eats
831       one argument and returns success:
832
833          sub spoof_read_file
834          {
835             my ($opt, $args) = @_;
836             (warn ("$opt option requires an argument\n"), return 0)
837                unless @$args;
838             shift @$args;
839             return 1;
840          }
841
842       Then, you have to tell "Getopt::Tabular" about this alternate callback
843       with no side-effects (apart from eating that one argument):
844
845          &Getopt::Tabular::SetSpoofCodes (-read_file => \&spoof_read_file);
846
847       ("SetSpoofCodes" just takes a list of key/value pairs, where the keys
848       are "call" or "eval" options, and the values are the "no side-effects"
849       callbacks.  Naturally, the replacement callback for an "eval" option
850       should be a string, and for a "call" option it should be a code
851       reference.  This is not actually checked, however, until you call
852       "SpoofGetOptions", because "SetSpoofCodes" doesn't know whether options
853       are "call" or "eval" or what.)
854
855       A more useful "spoof_read_file", however, would actually check if the
856       requested file exists -- i.e., we should try to catch as many errors as
857       possible, as early as possible:
858
859          sub spoof_read_file
860          {
861             my ($opt, $args) = @_;
862             warn ("$opt option requires an argument\n"), return 0
863                unless @$args;
864             my $file = shift @$args;
865             warn ("$file does not exist or is not readable\n"), return 0
866                unless -r $file;
867             return 1;
868          }
869
870       Finally, you can frequently merge the "real" and "spoof" callback into
871       one subroutine:
872
873          sub read_file
874          {
875             my ($opt, $args, $spoof) = @_;
876
877             warn ("$opt option requires an argument\n"), return 0 unless @$args;
878             my $file = shift @$args;
879             warn ("$file does not exist or is not readable\n"), return 0
880                unless -r $file;
881             return 1 if $spoof;
882             open (FILE, $file) ||
883                (warn ("$file: $!\n"), return 0);
884             push (@filedata, <FILE>);
885             close (FILE);
886             return 1;
887          }
888
889       And then, when specifying the replacement callback to "SetSpoofCodes",
890       just create an anonymous sub that calls "read_file" with $spoof true:
891
892          &Getopt::Tabular::SetSpoofCodes
893             (-read_file => sub { &read_file (@_[0,1], 1) });
894
895       Even though this means a bigger and more complicated callback, you only
896       need one such callback -- the alternative is to carry around both
897       "read_file" and "spoof_read_file", which might do redundant processing
898       of the argument list.
899

AUTHOR

901       Greg Ward <greg@bic.mni.mcgill.ca>
902
903       Started in July, 1995 as ParseArgs.pm, with John Ousterhout's
904       Tk_ParseArgv.c as a loose inspiration.  Many many features added over
905       the ensuing months; documentation written in a mad frenzy 16-18 April,
906       1996.  Renamed to Getopt::Tabular, revamped, reorganized, and
907       documentation expanded 8-11 November, 1996.
908
909       Copyright (c) 1995-97 Greg Ward. All rights reserved.  This is free
910       software; you can redistribute it and/or modify it under the same terms
911       as Perl itself.
912

BUGS

914       The documentation is bigger than the code, and I still haven't covered
915       option patterns or extending the type system (apart from pattern
916       types).  Yow!
917
918       No support for list-valued options, although you can roll your own with
919       call options.  (See the demo program included with the distribution for
920       an example.)
921
922       Error messages are hard-coded to English.
923
924
925
926perl v5.30.1                      2020-01-30                        Tabular(3)
Impressum