Getopt::ExPar - Extended Parameters command line parser.
use Getopt::ExPar; my($opt) = new Getopt::ExPar();
Method-based command line argument parser.
This is a method-based command line argument handling package. ExPar was originally based on EvaP but was eventually rewritten from scratch. I have tested it and refined it over the course of around 6 years. I have been using it for internal projects for several years and now it is time to release it.
Because of the near-infinite combinations of command line arguments, this package may seem burdensome to use. I hope that is not the case. In fact, I hope that its feature set will prove invaluable.
A quick list of features: - Perl OO interface - allows multiple arguments per option: -starship Federation Constitution "USS Enterprise" NCC-1701 - allows options to be specified as patterns so plusargs can be handled: +plusarg+x=y asdf - has some convenience functions like specifying parameter groups and mutually exclusive parameters
A few things to note. Since this package can create routines on the fly based on the option names, all the internal routines of ExPar begin with '_'. So, the 'new' method is really '_new'.
There are several preferences that can be specified when invoking the _new() method. These can also be set through their own methods. Values are set to 0 or 1 unless specified otherwise.
my($opt) = Getopt::ExPar::_new({ 'ooRoutines' => 1, 'development_check' => 1,});
The 3 types of methods that deal with parameters are those that define, parse and access the command line data.
The main method for defining parameters. It can be called in several ways, but the primary way is:
$opt->_parameter( <name>, <type>, <alias> ); $opt->_parameter( <name>, <type> ); $opt->_parameter( <name>, );
Currently suppoted types are integer, natural, real, string, file, switch & argumentFile. If type is not specified, then 'switch' is assumed.
$opt->_parameter( 'affiliation', 'string', 'aff' );
For declaring a parameter that has multiple arguments: -starship Constitution "USS Enterprise" NCC-1701 The declaration syntax for this is a bit tedious and will be expanded in the future:
$opt->_multi_parameter( <name>, { <arg1_name> => <type>, }, { <arg2_name> => <type>, }, { <arg3_name> => <type>, }, );
Example with 4 arguments where the names of the different arguments are affiliation, class, name, desgination:
$opt->_multi_parameter( 'starship', { 'affiliation' => 'string' }, { 'class' => 'string' }, { 'name' => 'string' }, { 'designation' => 'string' } );
For declaring a parameter in terms of a perl regular expression. Was originally created to handle 'plusargs'.
$opt->_special_parameter( <name>, <pattern>, <type> ); $opt->_special_parameter( <name>, <pattern>, );
Finally, for declaring a parameter as a regular expression that has multiple arguments.
$opt->_multi_special_parameter( <name>, <pattern>, { <arg1_name> => <type>, }, { <arg2_name> => <type>, }, { <arg3_name> => <type>, }, );
For declaring some help text for the specified argument.
$opt->_help( <name>, <help_text> );
Since regular expressions do not make for good descriptions unless you understand them, _help_option b<must> be specified for every _special and _multi_special parameters declared.
_help_option( <name>, <help_option> );
Example: $opt->_special( 'mySpecialOption', '\+xyz\+\d+=\S+' ); $opt->_help_option( 'mySpecialOption', '+xyz+<count>=<description>' );
Basically, _help_option is shown when the help is output for this option. Where '\+xyz\+\d+=\S+' does not really tell the user anything, '+xyz+<count>=<description>' is a human-readable description.
$opt->_alias( <name>, <alias>, <alias2>, <alias3>, ... );
More than one alias can be specified.
$opt->_default( <name>, <default> );
For normal parameters, <default> is a list of scalars:
$opt->_default( 'affiliation', 'Federation', 'Klingon', );
For multi_parameters, <default> is a list of array references.
$opt->_default( 'starship', [ 'Federation', 'Constitution', 'USS Enterprise', 'NCC-1701', ], );
Used to designate that a parameter must be specified by the user.
$opt->_required( <name>, <help_text> );
A way to give a list of possible values for an argument.
$opt->_keys( <name>, );
A list of options that are mutually exclusive. If one is used, then none of the others may be used. If this happens, the user is given an appropriate message.
$opt->_mutually_exclusiev( <opt1>, <opt2>, <opt3>, );
A list of options that must be specified together. If any are used, all must be used. If not, the user is given an appropriate error message.
$opt->_required_group( <opt1>, <opt2>, <opt3>, );
This simply checks to make sure that no arguments are duplicated for the specified parameter.
$opt->_unique( 'starship' );
This works for any type of parameter and for multi-parameters it will check all arguments. If an argument is duplicated, the user is given an appropriate error message.
This runs the parser on @ARGV once all the parameters have been defined.
Routine to return the *first* value for specified parameter, unless the parameter is a 'switch', then return the scalar value.
Routine to return 0/1 depending on existance of specified parameter. Or for special parameters, can check existance of a specific arg.
Routine to return number of arguments for specified parameter.
Routine to return all values as an ARRAY ref for specified parameter. Or array of array refs if multiple arguments for specified parameter.
Routine to return the value (or the next value) of the specified parameter.
Routine to prepare for calling _argl (it resets the internal counter).
Routine to return all values as a HASH ref for specified parameter. Hash keys are numeric preserving order of parameters. If multi_parameter, returns all args as hash of hashes where subhashes are name/value pairs.
Routine to return filelist if one exists.
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...:)
Some shells in UNIX allow for command completion where the first few letters of a command is typed in and a completion-key, usually 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 unmanagable.
Perhaps by calling the perl script with a -complete (--complete) option only, a complete definition would be printed to STDOUT.
I will entertain any [sane] ideas that users may have...:)
This is currently Release 1.00. There are undoubtedly bugs and shortcomings. Please email me at harlinh@cadence.com with questions, comments, feature requests and bug reports.
Full initial release.
Repackaging of tar file.
Harlin L. Hamilton Jr., <harlinh@cadence.com>
Copyright (C) 1998-2008 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.
To install Getopt::ExPar, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::ExPar
CPAN shell
perl -MCPAN -e shell install Getopt::ExPar
For more information on module installation, please visit the detailed CPAN module installation guide.