Getopt::ExPar 0.01

Getopt::ExPar contains extended parameters command line parser.

SYNOPSIS

use Getopt::ExPar;

my(@PDT, @MM, %OPT);
ExPar @PDT, @MM, $OPT;

EXPORT

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.

Introduction

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.

Parameter Description Table (PDT) Syntax

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.

Usage Notes

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.