|
Getopt::ExPar - Extended Parameters command line parser. |
Getopt::ExPar - Extended Parameters command line parser.
use Getopt::ExPar;
my(@PDT, @MM, %OPT); ExPar \@PDT, \@MM, $OPT;
use Getopt::ExPar exports the sub ExPar into your name space.
ExPar is a perl5 module used to parse command line parameters. This package uses the @PDT, Parameter Description Table, and the @MM, Message Module, to return %OPT which is a hash reference containing the command line option data. The function of Getopt::ExPar is based on Getopt::EvaP, created by Stephen O. Lidie.
The ExPar function parses a perl command line. Using the option definitions in the @PDT, argument types are checked and the arguments themselves may be checked against a specified range or pattern. By using both @PDT and @MM, several types of help may be retured to the user. ExPar handles command lines with this format:
command [-parameters] [file_list]
where any parameters and file_list are optional.
Here is the PDT syntax. Optional constructs are enclosed in [], and the | character separates possible values in a list.
PDT [program_name, alias]
[parameter_name[, alias]: type [pattern | range] [ = [default_variable,] default_value]]
PDTEND [flag_list]
flag_list is one or more of the following flags: optional_file_list | required_file_list | no_file_list: specifies condition of list of files at end of command line. (only one of these may be specified) abbreviations: allows for abbreviations of commands or aliases as long as enough of the command is given to make it distinguishable from all others. If not, a message is printed so the user may be more specific. switchglomming: allows for multiple single-letter switch options to be specified as single option (must be first option). pdt_warnings: for debugging a @PDT, it prints out messages that are not necessarily errors, like inconsistent number of default values in a list, etc.
The default_variable is an environment variable - see the section Usage Notes for complete details.
So, the simplest possible PDT would be:
PDT PDTEND
This PDT would simply define a -help switch for the command, but is rather useless.
A typical PDT would look more like this:
PDT frog
number, n: integer = 1
chars, c: string = "default_string"
PDTEND no_file_list
This PDT, for command frog, defines two parameters, number (or n), of type integer with a default value of 1, and chars (or c), of type string with a default value of ``default_string''. The PDTEND no_file_list indicator indicates that no trailing file_list can appear on the command line. Of course, the -help switch is defined automatically.
Each of these options may be further refined by using a range and a pattern, respectively:
PDT frog
number, n: integer (((#<5) and (#%2==1)), ((#<20) and (#%2==0)), >100) = 1
chars, c: string ('default_(optional_)?string') = "default_string"
PDTEND no_file_list
Here, a range is given for the number parameter. This is a list of perl conditional statements, separated with commas. Each element in the list is ORed together to construct a single condition with which the parameter value is tested. The '#' is substituted with the actual value, '1' in this instance. For simple conditions like '>100', the '#' is implied. Other simple conditions are '<' and '==' (a single '=' is accepted as '==', not an assignment). Ex: This condition: (#>10, #<-10, #==5, #=3, -5 < # <= 2) Can be reduced to: (>10, <-10, 5, 3, -5<#<=2) Notice that the compound condition, '-5<#<=2', MUST contain the '#'.
As for the 'number' parameter above, the range (or condition) is translated as: (Less than 5 AND odd) OR (Less than 20 AND even) OR (Greater than 100) So, '1' fits this condition. These conditions may be as complex as you wish. ENV variables may also be referenced within these range specifications.
The pattern is a perl regular expression with which the value, in this case ``default_string'', is tested.
Currently, both @PDT and @MM are required, as is a reference to a hash into which all parameter values are placed. A call to ExPar *must* have this form:
ExPar(\@PDT, \@MM, \%OPT);
An optional PDT flag can be included that tells ExPar whether or not trailing file names can appear on the command line after all the parameters. It can read no_file_list, optional_file_list or required_file_list and, if not specified, defaults to optional. Any flags *must* be on the PDTEND line, which is the last line of the @PDT array. Other flags include switchglomming and pdt_warnings.
The switchglomming flag allows multiple single-letter switch parameters to be specified as a single parameter. Either the option name or its alias must be a single letter to be used in the switch glom. Ex: script.pl -x -f -c -a arga ---> script.pl -xfc -a arga The switch glo *must* be the first option on the command line. Note: this can be changed if heavily requested.
Additionally a Message Module is declared that describes the command and provides examples. Following the main help text an optional series of help text messages can be specified for individual command line parameters. In the following sample program all the parameters have this additional text which describes that type of parameter. The leadin character is a dot in column one followed by the full spelling of the command line parameter. Use -full_help rather than -help to see this supplemental information. This sample program illustrates the various types and how to use ExPar(). The key type is a special type that enumerates valid values for the command line parameter. The boolean type may be specified as TRUE/FALSE, YES/NO, ON/OFF or 1/0. Parameters of type file have ~ and $HOME expanded, and default values stdin and stdout converted to '-' and '>-', respectively. Of special note is the default value $required: when specified, ExPar will ensure a value is specified for that command line parameter.
All types except switch may be list of, like the real70 parameter below. A list parameter can be specified multiple times on the command line. NOTE: in general you should ALWAYS quote components of your lists, even if they are not type string, since Evaluate Parameters uses eval to parse them. Doing this prevents eval from evaluating expressions that it should not, such as file name shortcuts like $HOME, and backticked items like `hostname`. Although the resulting PDT looks cluttered, Evaluate Parameters knows what to do and eliminates superfluous quotes appropriately.
Finally, you can specify a default value via an environment variable. If a command line parameter is not specified and there is a corresponding environment variable defined then Evaluate Parameters will use the value of the environment variable. Examine the command parameter for the syntax. With this feature users can easily customize command parameters to their liking. Although the name of the environment variable can be whatever you choose, the following scheme is suggested for consistency and to avoid conflicts in names:
@PDT = split /\n/, <<'end-of-PDT'; PDT expar_test switch01, sw01 : switch integer13, int13 : integer (5 < # <= 9) = 7 real70 : list of real = ENV:D_real70, (45, 54) boolean07, bo07 : list of boolean = (1, ``true'') string17 : list of string ('s(?:tring)?17') = ENV:D_string17, ('string17a', 'string17b') string20 : list of string (``s(?:tring)?20'') = \ ENV:D_string20, (ENV:D_string20a, 'string20b') string21, str21 : string (``^\\\d{2,3}\\\w\\\d{2,8}\$'') = ``333x29445'' name21, nm21 : name ('^\d{2,3}\w\d{2,8}') = $required file05, fl05 : file = ``~'' file06 : file = ``$HOME/bin'' file07, fl07 : file = '~other/bin' application08 : application = ENV:D_application08, `date` key13 : list of key ENV:D_keys13, keyend = ENV:D_key13, \ (``printer'', ENV:D_key13b, ENV:D_keys13c) set01, st01 : set of : integer (5 <= # <= 9) : real (5.0 <= # <= 9.0) : string ('pat01') : key ak, bk, ck, dk, keyend end set set02, st02 : list of set : integer (5 <= # <= 9) = (5, 7) : real (5.0 <= # <= 9.0) = (8.3, 5.0001) : string ('blah') = (``blah'', ``bbbbblahhhhh'') : key ak, bk, ck, dk, keyend = (``ak'', ``dk'') end set PDTEND end-of-PDT
@MM = split /\n/, <<'end-of-MM'; expar_test.pl
This script simply tests the ExPar option parsing package.
Examples:
expar_test.pl
expar_test.pl -usage_help
expar_test.pl -help
expar_test.pl -full_help
expar_test.pl -partial_help
.switch01
A switch type parameter is either off or on, returning a 0 or 1
in the B<%OPT>: $OPT{'switch01'}.
.integer13
An integer type with a specified range and a default value. Integers
are checked against the pattern '[-+]?\d+', and, in this case, would
check to make sure that any command line value is greater than 5 and
less than or equal to 9.
.real70
An option of type real, checked against the following pattern:
'[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?'. The default
values are 45 and 54. There are two default values because this
is a 'list of' type, which means that there may be multiple -real70
options in the command line. The value in B<%OPT> is an array
reference: $OPT{'real70'} = [45, 54].
Or, $OPT{'real70'}->[0] = 45, and
$OPT{'real70'}->[1] = 54.
.boolean07
A boolean type, also a list, can have be given one of the following
values: TRUE, FALSE, ON, OFF, 1, 0, YES, NO (case insensitive).
Returns either a 1 or 0.
.string17
A string type, also a list, with a pattern with which to check any
value specified in the command line. Any default values are also
checked against the specified pattern. In this case, D_string17 is
the default list, unless it does not exist, then the ending list
is assigned as the default. A string type is simply a string of
characters surrounded by quotes, either single or double quotes.
.string20
Another list of string type, showing an ENV variable, D_string20a, in
the default assignments. Also, a \ character, backslash, can be placed
at the end of a line in the B<@PDT> so that multiple lines may be used.
.string21
Still another string with a pattern surrounded by double-quotes. Notice
the use of multiple backslashes. Always be careful when pattern matching
on strings defined with single or double quotes.
.name21
The type name is treated identically to the type string. It is included
for backward compatibility with Getop::EvaP.
.file05
The type file is also the same as string type; however, $HOME and "~" are
expanded to $ENV{'HOME'}. Here the single '~' character is expanded.
Patterns are also allowed in file declaraions.
.file06
Here, $HOME is expanded to $ENV{'HOME'}.
.file07
In this case, the '~' is followed by a non-slash character. In UNIX, this
generally refers to the home directory of another user, and the '~' is
I<not> expanded.
.application08
Treated as strings, but if surrounded by backtick characters, '`', it is
assumed to be an application and the returned value of this application
is stored. In this case, if the ENV variable D_application08 is not
defined, the default value of $OPT{'application08'} is set to what is
returned from the 'date' command: 'Mon Nov 9 15:23:47 CST 1998'.
.key13
The type key is an enumerated type allowing the programmer to explicitly
defined the possible values. Although the key type is functionally
equivalent to a string with a speicified pattern, it is left in for
backward compatibility. In this case, it is a list of keys whose
key values are defined by the ENV variable D_keys13.
.set01
A new 'supertype'. This allows for having multiple parameters for
a single option. From B<%OPT>, a set is an array of arrays, where each
sub-array holds the value(s) of a sub-type.
Ex: script.pl -set01 6 6.5 'pppat011' ck
$OPT{'set01'} = [ [ 6 ], [ 6.5 ], [ 'pppat011' ], [ 'ck' ] ];
.set02
A list of set. Assuming to -set02 options specified on the command line:
$OPT{'set01'} = [ [ 5, 7 ], [8.3, 5.0001], ["blah", "bbbbblahhhhh"], ["ak", "dk"] ];
end-of-MM
ExPar \@PDT, \@MM, \%OPT; # evaluate parameters
There are several levels of help created from the @PDT and @MM. It is possible that the programmer may want to use one or more of these key options in his @PDT. If this is the case, the built in functions can be accessed by using two '-' characters instead of one. Built in help functions include:
-help (-h) -full_help (-fh) -usage_help (-uh) -partial_help (-ph)
Currently, with the 0.01 alpha version, there is not much variety in the help options. This author wanted to have a rudimentary help available, while getting the package to end users for evaluation. Using any one of these built in help options outputs the @PDT and @MM in a text format.
In development...
In development...
In development...
Here are a few ideas for future enhancements. Currently, there is no support for platforms other than UNIX and no support for languages other than Perl. (What else could there be...:)
A user may only want help with a specific option or subset of options. Using -partial_help, the user can view the help for only those options he/she wishes. This would be a subset of the -full_help.
Whereas currently, to define an option to be required by the user, '= $required' is placed at the end of a line in the PDT. However, this method is limited. A method of implementing a more explicit and elaborate definition of $required will be defined. This is the current thought:
In the PDT, a $required line may be placed in this manner: $required : ((opta and optb) or (opta and not optb and optc) or \ (optc and optd and not optz))
This line is simply a Perl condition statement containing the names (or aliases) of options defined in the PDT. Multiple $required lines may be ANDed together.
Some shells in UNIX allow for command completion where the first few letters of a command is typed in and a completion-key, ESC or TAB, is pressed and the shell determines if enough letters have been typed to distinguish from any other command. Some shells allow a refinement of this by completing command parameters. In tcsh, this is done with the complete command. For programs with a complex option set, the complete command can become near unmanagable. This author proposes that by using the @PDT, a complete command may be defined and returned to the user.
Perhaps by calling the perl script with a -complete (--complete) option only, a complete definition would be printed to STDOUT.
Although this would be fairly easy to do, it may not be necessary. User feedback is welcome. Entries in @PDT would resemble this: integer01, int01, i01, i1 : integer
I will entertain any [sane] ideas that users may have...:)
Currently, the help system is minimal, but I wanted to get this released to see who might use it.
This is currently alpha software. There are no doubt bugs and shortcomings. Please email me at hlhamilt@aud.alcatel.com with questions, comments, feature requests and bug reports.
First alpha release. Help funcions are minimal. Might be buggy...:)
Harlin L. Hamilton Jr.
mailto:hlhamilt@aud.alcatel.com
Copyright (C) 1998 Harlin L. Hamilton Jr.. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
|
Getopt::ExPar - Extended Parameters command line parser. |