This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Getopt/Mixed, Next: Getopt/Reference_Parser, Prev: Getopt/Long, Up: Module List getopt processing with both long and short options ************************************************** NAME ==== Getopt::Mixed - getopt processing with both long and short options SYNOPSIS ======== use Getopt::Mixed; Getopt::Mixed::getOptions(...option-descriptions...); ...examine $opt_* variables... or use Getopt::Mixed "nextOption"; Getopt::Mixed::init(...option-descriptions...); while (($option, $value) = nextOption()) { ...process option... } Getopt::Mixed::cleanup(); DESCRIPTION =========== This package is my response to the standard modules Getopt::Std and Getopt::Long. `Std' doesn't support long options, and Long doesn't support short options. I wanted both, since long options are easier to remember and short options are faster to type. This package is intended to be the "Getopt-to-end-all-Getop's". It combines (I hope) flexibility and simplicity. It supports both short options (introduced by -) and long options (introduced by -). Short options which do not take an argument can be grouped together. Short options which do take an argument must be the last option in their group, because everything following the option will be considered to be its argument. There are two methods for using Getopt::Mixed: the simple method and the flexible method. Both methods use the same format for option descriptions. Option Descriptions ------------------- The option-description arguments required by init and getOptions are strings composed of individual option descriptions. Several option descriptions can appear in the same string if they are separated by whitespace. Each description consists of the option name and an optional trailing argument specifier. Option names may consist of any characters but whitespace, =, :, and `>'. Values for argument specifiers are: option does not take an argument =s :s option takes a mandatory (=) or optional (:) string argument =i :i option takes a mandatory (=) or optional (:) integer argument =f :f option takes a mandatory (=) or optional (:) real number argument >new option is a synonym for option `new' The `>' specifier is not really an argument specifier. It defines an option as being a synonym for another option. For example, "a=i apples>a" would define -a as an option that requires an integer argument and *-apples* as a synonym for -a. Only one level of synonyms is supported, and the root option must be listed first. For example, "apples>a a=i" and "a=i apples>a oranges>apples" are illegal; use "a=i apples>a oranges>a" if that's what you want. For example, in the option description: "a b=i c:s apple baker>b charlie:s" -a and -apple do not take arguments -b takes a mandatory integer argument -baker is a synonym for -b -c and -charlie take an optional string argument If the first argument to init or getOptions is entirely non-alphanumeric characters with no whitespace, it represents the characters which can begin options. User Interface -------------- From the user's perspective, short options are introduced by a dash (-) and long options are introduced by a double dash (-). Short options may be combined ("-a -b" can be written "-ab"), but an option that takes an argument must be the last one in its group, because anything following it is considered part of the argument. A double dash by itself marks the end of the options; all arguments following it are treated as normal arguments, not options. A single dash by itself is treated as a normal argument, not an option. Long options may be abbreviated. An option *-all-the-time* could be abbreviated *-all*, *-a-tim*, or even *-a*. Note that *-time* would not work; the abbreviation must start at the beginning of the option name. If an abbreviation is ambiguous, an error message will be printed. In the following examples, -i and *-int* take integer arguments, -f and *-float* take floating point arguments, and -s and *-string* take string arguments. All other options do not take an argument. -i24 -f24.5 -sHello -i=24 --int=-27 -f=24.5 --float=0.27 -s=Hello --string=Hello If the argument is required, it can also be separated by whitespace: -i 24 --int -27 -f 24.5 --float 0.27 -s Hello --string Hello Note that if the option is followed by =, whatever follows the = *is* the argument, even if it's the null string. In the example -i= 24 -f= 24.5 -s= Hello -i and -f will cause an error, because the null string is not a number, but -s is perfectly legal; its argument is the null string, not "Hello". Remember that optional arguments *cannot* be separated from the option by whitespace. The Simple Method ----------------- The simple method is use Getopt::Mixed; Getopt::Mixed::getOptions(...option-descriptions...); You then examine the `$opt_*' variables to find out what options were specified and the `@ARGV' array to see what arguments are left. If -a is an option that doesn't take an argument, then `$opt_a' will be set to 1 if the option is present, or left undefined if the option is not present. If -b is an option that takes an argument, then `$opt_b' will be set to the value of the argument if the option is present, or left undefined if the option is not present. If the argument is optional but not supplied, `$opt_b' will be set to the null string. Note that even if you specify that an option requires a string argument, you can still get the null string (if the user specifically enters it). If the option requires a numeric argument, you will never get the null string (because it isn't a number). When converting the option name to a Perl identifier, any non-word characters in the name will be converted to underscores (_). If the same option occurs more than once, only the last occurrence will be recorded. If that's not acceptable, you'll have to use the flexible method instead. The Flexible Method ------------------- The flexible method is use Getopt::Mixed "nextOption"; Getopt::Mixed::init(...option-descriptions...); while (($option, $value, $pretty) = nextOption()) { ...process option... } Getopt::Mixed::cleanup(); This lets you process arguments one at a time. You can then handle repeated options any way you want to. It also lets you see option names with non-alphanumeric characters without any translation. This is also the only method that lets you find out what order the options and other arguments were in. First, you call Getopt::Mixed::init with the option descriptions. Then, you keep calling nextOption until it returns an empty list. Finally, you call Getopt::Mixed::cleanup when you're done. The remaining (non-option) arguments will be found in @ARGV. Each call to nextOption returns a list of the next option, its value, and the option as the user typed it. The value will be undefined if the option does not take an argument. The option is stripped of its starter (e.g., you get "a" and "foo", not "-a" or "-foo"). If you want to print an error message, use the third element, which does include the option starter. OTHER FUNCTIONS =============== Getopt::Mixed provides one other function you can use. `abortMsg' prints its arguments on STDERR, plus your program's name and a newline. It then exits with status 1. For example, if `foo.pl' calls `abortMsg' like this: Getopt::Mixed::abortMsg("Error"); The output will be: foo.pl: Error CUSTOMIZATION ============= There are several customization variables you can set. All of these variables should be set after calling Getopt::Mixed::init and before calling nextOption. If you set any of these variables, you must check the version number first. The easiest way to do this is like this: use Getopt::Mixed 1.006; If you are using the simple method, and you want to set these variables, you'll need to call init before calling getOptions, like this: use Getopt::Mixed 1.006; Getopt::Mixed::init(...option-descriptions...); ...set configuration variables... Getopt::Mixed::getOptions(); # IMPORTANT: no parameters $order $order can be set to $REQUIRE_ORDER, $PERMUTE, or $RETURN_IN_ORDER. The default is $REQUIRE_ORDER if the environment variable POSIXLY_CORRECT has been set, $PERMUTE otherwise. $REQUIRE_ORDER means that no options can follow the first argument which isn't an option. $PERMUTE means that all options are treated as if they preceded all other arguments. $RETURN_IN_ORDER means that all arguments maintain their ordering. When nextOption is called, and the next argument is not an option, it returns the null string as the option and the argument as the value. nextOption never returns the null list until all the arguments have been processed. $ignoreCase Ignore case when matching options. Default is 1 unless the option descriptions contain an upper-case letter. $optionStart A string of characters that can start options. Default is "-". $badOption A reference to a function that is called when an unrecognized option is encountered. The function receives three arguments. $_[0] is the position in @ARGV where the option came from. $_[1] is the option as the user typed it (including the option start character). $_[2] is either undef or a string describing the reason the option was not recognized (Currently, the only possible value is 'ambiguous', for a long option with several possible matches). The option has already been removed from @ARGV. To put it back, you can say: splice(@ARGV,$_[0],0,$_[1]); The function can do anything you want to @ARGV. It should return whatever you want nextOption to return. The default is a function that prints an error message and exits the program. $checkArg A reference to a function that is called to make sure the argument type is correct. The function receives four arguments. $_[0] is the position in @ARGV where the option came from. $_[1] is the text following the option, or undefined if there was no text following the option. $_[2] is the name of the option as the user typed it (including the option start character), suitable for error messages. $_[3] is the argument type specifier. The function can do anything you want to @ARGV. It should return the value for this option. The default is a function that prints an error message and exits the program if the argument is not the right type for the option. You can also adjust the behavior of the default function by changing $intRegexp or $floatRegexp. $intRegexp A regular expression that matches an integer. Default is '^[-+]?\d+$', which matches a string of digits preceded by an optional sign. Unlike the other configuration variables, this cannot be changed after nextOption is called, because the pattern is compiled only once. $floatRegexp A regular expression that matches a floating point number. Default is '^[-+]?(\d*\.?\d+|\d+\.)$', which matches the following formats: "123", "123.", "123.45", and ".123" (plus an optional sign). It does not match exponential notation. Unlike the other configuration variables, this cannot be changed after nextOption is called, because the pattern is compiled only once. $typeChars A string of the characters which are legal argument types. The default is 'sif', for String, Integer, and Floating point arguments. The string should consist only of letters. Upper case letters are discouraged, since this will hamper the case-folding of options. If you change this, you should set $checkType to a function that will check arguments of your new type. Unlike the other configuration variables, this must be set before calling init(), and cannot be changed afterwards. $checkType If you add new types to $typeChars, you should set this to a function which will check arguments of the new types. BUGS ==== * This document should be expanded. * A long option must be at least two characters long. Sorry. * The ! argument specifier of Getopt::Long is not supported, but you could have options *-foo* and *-nofoo* and then do something like: $opt_foo = 0 if $opt_nofoo; * The `@' argument specifier of Getopt::Long is not supported. If you want your values pushed into an array, you'll have to use nextOption and do it yourself. LICENSE ======= Getopt::Mixed is distributed under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This means it is distributed in the hope that it will be useful, but *without any warranty*; without even the implied warranty of *merchantability* or *fitness for a particular purpose*. See the GNU General Public License for more details. Since Perl scripts are only compiled at runtime, and simply calling Getopt::Mixed does not bring your program under the GPL, the only real restriction is that you can't use Getopt::Mixed in an binary-only distribution produced with dump (unless you also provide source code). AUTHOR ====== Christopher J. Madsen <`ac608@yfn.ysu.edu'> Thanks are also due to Andreas Koenig for helping Getopt::Mixed conform to the standards for Perl modules and for answering a bunch of questions. Any remaining deficiencies are my fault.  File: pm.info, Node: Getopt/Reference_Parser, Next: Getopt/Regex, Prev: Getopt/Mixed, Up: Module List Examples: 1) #Program: my($x) = { 'a' => { 'a' => [ 'a', 'b', 'c', ], 'b' => 9, 'c' => 10, }, 'b' => 'asdf', 'c' => [ 45, 56, 67, ], }; print "\$x->" . &reference_tree_string($x, "\$x->"); #Output: $x->{ 'a' => { 'a' => [ a, #0 b, #1 c, ], 'b' => 9, 'c' => 10, }, 'b' => asdf, 'c' => [ 45, #0 56, #1 67, ], } 2) #Program: my($x) = { 'a' => { 'a' => [ 'a', 'b', 'c', ], 'b' => 9, 'c' => 10, }, 'b' => 'asdf', 'c' => [ 45, 56, 67, ], }; print "\$x->" . &reference_tree_string($x); #Output: $x->{ 'a' => { 'a' => [ a, #0 b, #1 c, ], 'b' => 9, 'c' => 10, }, 'b' => asdf, 'c' => [ 45, #0 56, #1 67, ], }  File: pm.info, Node: Getopt/Regex, Next: Getopt/Simple, Prev: Getopt/Reference_Parser, Up: Module List handle command line options flexibly using regular expressions ************************************************************** NAME ==== Getopt::Regex - handle command line options flexibly using regular expressions SYNOPSIS ======== use Getopt::Regex; GetOptions(\@ARGV,[$regex,$ref,$takesarg],...); *\@ARGV* - reference to array of command line arguments *$regex* - regular expression for identifying the option $ref - reference to a variable to be set or a function which is passed the argument if it exists. *$takesarg* - if 1 subsequent command line argument is taken as its argument DESCRIPTION =========== This package provides a flexible yet simple method for handling command line options. It does not stamp over the callers namespace or, currently, inforce any particular standard for the options - the user can do this if they want. By using anonymous closures sophisticated option specifications can be constructed. The function GetOptions, exported from the package takes a reference to the argument list followed by a set of option specifications which are references to arrays containing at least a regular expression to match for the option and a reference to a variable to be set or a function to be called. A third optional argument for each option, if set to 1, pulles off the following command line argument as an argument for that option. The simplest use is to set a boolean variable if an argument is set GetOptions(\@ARGV,['-[v|V]',\$bool,0]); If the option `'-v'' or `'-V'' occurs $bool will be set to 1, otherwise it is left unchanged. A subsequent command line argument may be used as as an option argument as follows GetOptions(\@ARGV,['-f',\$fname,1]); will set $fname to fname if '-f fname' is specified on the command line. Processed arguments are removed from the argument list. Only the first occurance of an argument is processed, if a variable is being set as in the above examples More complex argument specifications are possible using anonymous functions as arguments. If the option takes an argument, the argument is passed to the function. Parts of the regular expression may also be used in the anonymous closure being executed. e.g. GetOptions(\@ARGV, ['-D(.+)=(.+)',sub { diagnostic $1,$2; } ,0], ['-D(.+)', sub { diagnostic $1; $_[0]; },1]); The first option specification will match options in the format '-DDIAGNOSTIC=VALUE',the second will match occurances of the format '-DDIAGNOSTIC VALUE'. As can be seen use of the regex matching variables can be made in handling the options. When GetOptions is called with a function reference the function is called for all matching occurances of the regular expression, and the proceesed options are removed from the argument list. Another useful example is GetOptions(\@ARGV,['-(no-)*optimization',0,sub { $optimization=!$1; }]); which identifies the option statements '-optimization' or '-no-optimization' setting $optimization true or false approptiately. The option '-' ends the search for matching options - further arguments are not searched. NOTE ==== Requires at least Perl 5.000 or Perl 5.001m if anonymous closures are used. HISTORY ======= $Log: Options.pm,v $ Revision 1.3 1995/12/16 09:48:28 willijar Rename package to be more consistant with guidlines Revision 1.2 1995/12/12 22:01:35 willijar Removed unnecessary default argument. Extended pod documentation. Revision 1.1 1995/12/10 15:57:06 willijar Initial revision BUGS ==== Please let me know. TODO ==== Possibly integrate default behaviour of other option functions in this package. AUTHOR ====== John A.R. Williams,  File: pm.info, Node: Getopt/Simple, Next: Getopt/Std, Prev: Getopt/Regex, Up: Module List Provide a simple wrapper around Getopt::Long. ********************************************* NAME ==== `Getopt::Simple' - Provide a simple wrapper around Getopt::Long. SYNOPSIS ======== use Getopt::Simple; # Or ... # use Getopt::Simple qw($switch); my($options) = { 'help' => { 'type' => '', 'env' => '-', 'default' => '', # 'verbose' => '', # Not needed on every key. 'order' => 1, }, 'username' => { 'type' => '=s', # As per Getopt::Long. 'env' => '$USER', # Help text. 'default' => $ENV{'USER'} || 'RonSavage', # In case $USER is undef. 'verbose' => 'Specify the username on the remote machine', 'order' => 3, # Help text sort order. }, 'password' => { 'type' => '=s', 'env' => '-', 'default' => 'password', 'verbose' => 'Specify the password on the remote machine', 'order' => 4, }, }; my($option) = new Getopt::Simple; if (! $option -> getOptions($options, "Usage: testSimple.pl [options]") ) { exit(-1); # Failure. } print "username: $option->{'switch'}{'username'}. \n"; print "password: $option->{'switch'}{'password'}. \n"; # Or, after 'use Getopt::Simple qw($switch);' ... # print "username: $switch->{'username'}. \n"; # print "password: $switch->{'password'}. \n"; DESCRIPTION =========== The `Getopt::Simple' module provides a simple way of specifying: * Command line switches * Type information for switch values * Default values for the switches * Help text per switch The `getOptions()' function =========================== The `getOptions()' function takes 4 parameters: * A hash defining the command line switches * A string to display as a help text heading * A Boolean. 0 = (Default) Use case-sensitive switch names. 1 = Ignore case * A Boolean. 0 = Return after displaying help. 1 = (Default) Terminate with exit(0) after displaying help The $classRef -> {'switch'} hash reference ========================================== Command line option values are accessed in your code by dereferencing the hash reference $classRef -> {'switch'}. Two examples are given above, under synopsis. Alternately, you can use the hash reference $switch. See below. The $switch hash reference ========================== Command line option values are accessed in your code by dereferencing the hash reference $switch. Two examples are given above, under synopsis. Alternately, you can use the hash reference $classRef -> {'switch'}. See above. The `dumpOptions()' function ============================ `dumpOptions()' prints all your option's keys and their current values. The `helpOptions()' function ============================ `helpOptions()' prints nicely formatted help text. INSTALLATION ============ You install `Getopt::Simple', as you would install any perl module library, by running these commands: perl Makefile.PL make make test make install If you want to install a private copy of `Getopt::Simple' in your home directory, then you should try to produce the initial Makefile with something like this command: perl Makefile.PL LIB=~/perl or perl Makefile.PL LIB=C:/Perl/Site/Lib If, like me, you don't have permission to write man pages into unix system directories, use: make pure_install instead of make install. This option is secreted in the middle of p 414 of the second edition of the dromedary book. WARNING re Perl bug =================== As always, be aware that these 2 lines mean the same thing, sometimes: * $self -> {'thing'} * $self->{'thing'} The problem is the spaces around the ->. Inside double quotes, "...", the first space stops the dereference taking place. Outside double quotes the scanner correctly associates the $self token with the {'thing'} token. I regard this as a bug. REQUIRED MODULES ================ * Exporter * Getopt::Long RETURN VALUES ============= * `dumpOptions()' returns nothing * `helpOptions()' returns nothing * `getOptions()' returns 0 for failure and 1 for success AUTHOR ====== `Getopt::Simple' was written by Ron Savage ** in 1997. LICENCE ======= This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Getopt/Std, Next: Getopt/Tabular, Prev: Getopt/Simple, Up: Module List Process single-character switches with switch clustering ******************************************************** NAME ==== getopt - Process single-character switches with switch clustering getopts - Process single-character switches with switch clustering SYNOPSIS ======== use Getopt::Std; getopt('oDI'); # -o, -D & -I take arg. Sets opt_* as a side effect. getopt('oDI', \%opts); # -o, -D & -I take arg. Values in %opts getopts('oif:'); # -o & -i are boolean flags, -f takes an argument # Sets opt_* as a side effect. getopts('oif:', \%opts); # options as above. Values in %opts DESCRIPTION =========== The getopt() functions processes single-character switches with switch clustering. Pass one argument which is a string containing all switches that take an argument. For each switch found, sets $opt_x (where x is the switch name) to the value of the argument, or 1 if no argument. Switches which take an argument don't care whether there is a space between the switch and the argument. Note that, if your code is running under the recommended `use strict 'vars'' pragma, you will need to declare these package variables with "our": our($opt_foo, $opt_bar); For those of you who don't like additional global variables being created, getopt() and getopts() will also accept a hash reference as an optional second argument. Hash keys will be x (where x is the switch name) with key values the value of the argument or 1 if no argument is specified. To allow programs to process arguments that look like switches, but aren't, both functions will stop processing switches when they see the argument -. The - will be removed from @ARGV.  File: pm.info, Node: Getopt/Tabular, Next: Getopt/Tiny, Prev: Getopt/Std, Up: Module List table-driven argument parsing for Perl 5 **************************************** 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"' in this node.) 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' in this node), 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"' in this node 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' in this node 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' in this node 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 = <"], ["-threshold", "float", 2, \@Threshold, "only consider values between and ", " "]); 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 specify the input file from which to read a large and sundry variety of data, to which many interesting operations will be applied -threshold only consider values between and [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 " 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", " "], ...); 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, ); 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, ); 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 I such callback -- the alternative is to carry around both C and C, which might do redundant processing of the argument list. AUTHOR ====== Greg Ward 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.