1Tabular(3) User Contributed Perl Documentation Tabular(3)
2
6 Getopt::Tabular - table-driven argument parsing for Perl 5
7
9 use Getopt::Tabular;
10 (or)
12 use Getopt::Tabular qw/GetOptions
14 SetHelp SetHelpOption
15 SetError GetError/;
16 ...
18 &Getopt::Tabular::SetHelp (long_help, usage_string);
20 @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
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 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 argument
46 any single word appearing on the command-line, i.e. one element of
47 the @ARGV array.
48 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 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 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
72 Now for the advertising, i.e. why Getopt::Tabular is a good thing.
73 · 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 · 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 · Getopt::Tabular can intelligently generate help text based on your
85 option descriptions.
86 · 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 · To make your program look smarter, options can be abbreviated and
92 come in any order.
93 ·
95 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 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
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 ["-foo", "integer", 2, \@Foo, "set the foo values"]
114 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 Typically, you'll group a bunch of option descriptions together like
122 this:
123 @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 and then call "GetOptions" like this:
135 &GetOptions (\@options, \@ARGV) || exit 1;
137 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 &GetOptions (\@options, \@ARGV, \@newARGV) || exit 1;
143 in which case @ARGV is untouched, and @newARGV gets the leftover
145 arguments.
146 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 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
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 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 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 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 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 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 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 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 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 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
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 As mentioned above, there are three main classes of argument types:
263 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 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 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 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 ["-foo", "string", 1, \$Foo]
292 (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 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 ["-foo", "string", 3, \@Foo]
308 would result in the @Foo array being set to the three strings
310 immediately following any "-foo" option on the command line.
311 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 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 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 &Getopt::Tabular::AddPatternType
344 ("upperstring", "[A-Z]+", "uppercase string")
345 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 ["-zap", "upperstring", 1, \$Zap]
351 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 &Getopt::Tabular::AddPatternType
364 ("upperstring", "[A-Z]+",
365 ["string of uppercase letters", "strings of uppercase letters"])
366 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 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 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 For example, the above two examples might be specified as
404 ["-clobber", "boolean", undef, \$Clobber],
406 ["-verbose|-quiet", "boolean", undef, \$Verbose],...);
407 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 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 ["-foo", "const", "hello there", \$Foo]
418 On encountering "-foo", "GetOptions" will copy "hello there" to
420 $Foo.
421 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 ["-foo", "arrayconst", [3, 6, 2], \@Foo]
428 On encountering "-foo", "GetOptions" will copy the array "(3,6,2)"
430 into @Foo.
431 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 ["-foo", "hashconst", { "Perl" => "Larry Wall",
438 "C" => "Dennis Ritchie",
439 "Pascal" => "Niklaus Wirth" },
440 \%Inventors]
441 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 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 ["-foo", "copy", undef, \$Foo,
457 "run prog2 with the -foo option"]
458 and later on, you would run prog2 like this:
460 system ("prog2 $Foo ...");
462 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 If num_values is anything other than "undef", then copy options
468 behave just like constant options.
469 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 sub process_foo
483 {
484 my ($opt, $args, $dest) = @_;
485 $$dest = shift @$args; # not quite right! (see below)
487 }
488 with a corresponding option table entry:
490 ["-foo", "call", [\$Foo], \&process_foo]
492 and then "-foo" would act just like a scalar-valued string option
494 that copies into $Foo. (Well, almost ... read on.)
495 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 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 sub process_foo
516 {
517 my ($opt, $args, $dest) = @_;
518 $$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 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 use Getopt::Tabular qw/GetOptions SetError/;
534 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 ["-foo", "eval", undef,
542 'print "-foo seen on command line\n"']
543 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 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 section
561 section options are just used to help formatting the help text.
562 See "HELP TEXT" below for more details.
563
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 ($err_class, $err_msg) = &Getopt::Tabular::GetError ();
572 (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 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 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 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 bad_eval
595 set when the code evaluted for an eval option has an error in it.
596 help
598 set when the user requests help
599 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
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 &Getopt::Tabular::SetOptionPatterns qw|(--)([\w-]+) (-)(\w+)|;
626 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 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 $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 $Usage = <<USAGE;
645 usage: foo [options]
646 foo -help to list options
647 USAGE
648 &Getopt::Tabular::SetHelp ($Help, $Usage)
650 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 As an example of the help display generated by a typical option table,
662 let's take a look at the following:
663 $Verbose = 1;
665 $Clobber = 0;
666 undef $InFile;
667 @Threshold = (0, 1);
668 @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 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 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 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 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 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 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 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 @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 results in the following chunk of help text:
754 -foo f set the foo value
756 -enterfoomode enter foo mode
757 -- Non-foo related options ---------------------------------
759 -bar b1 b2 set the bar strings (which have nothing
760 whatsoever to do with foo
761 (This example also illustrates a slightly different style of argument
763 placeholder. Take your pick, or invent your own!)
764
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 use Getopt::Tabular qw(SpoofGetOptions GetOptions);
775 .
776 .
777 .
778 &SpoofGetOptions (\@options, \@ARGV, \@newARGV) || exit 1;
779 and then later on, you would call "GetOptions" with the original @ARGV
781 (so it can do what "SpoofGetOptions" merely pretended to do):
782 &GetOptions (\@options, \@ARGV, \@newARGV) || exit 1;
784 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 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 @filedata = ();
809 sub read_file
811 {
812 my ($opt, $args) = @_;
813 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 @options =
824 (['-read_file', 'call', undef, \&read_file]);
825 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 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 Then, you have to tell "Getopt::Tabular" about this alternate callback
843 with no side-effects (apart from eating that one argument):
844 &Getopt::Tabular::SetSpoofCodes (-read_file => \&spoof_read_file);
846 ("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 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 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 Finally, you can frequently merge the "real" and "spoof" callback into
871 one subroutine:
872 sub read_file
874 {
875 my ($opt, $args, $spoof) = @_;
876 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 And then, when specifying the replacement callback to "SetSpoofCodes",
890 just create an anonymous sub that calls "read_file" with $spoof true:
891 &Getopt::Tabular::SetSpoofCodes
893 (-read_file => sub { &read_file (@_[0,1], 1) });
894 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
901 Greg Ward <greg@bic.mni.mcgill.ca>
902 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 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
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 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 Error messages are hard-coded to English.
923perl v5.30.0 2019-07-26 Tabular(3)