NAME

Getopt::ExPar - Extended Parameters command line parser.

SYNOPSIS

  use Getopt::ExPar;

  my($opt) = new Getopt::ExPar();

ABSTRACT

  Method-based command line argument parser.

DESCRIPTION

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.

Introduction

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'.

Preferences

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,});

ooRoutines (method _ooRoutines) Very useful and possibly dangerous option. This creates OO methods named after your command line options. If you use more than one ExPar object in the same script, this could get tricky. Also, there are some Perl calls that you cannot duplicate: BEGIN, END, BLOCK, others? Also, if you happen to name one of your options the same as an internally-used routine, this could cause issues, but all the internal routines start with '_' so this can be easily avoided.

development_check (method _development_check) Set this to a 1 while you are developing your script. This does some checking to make sure there are no duplicate names used, etc.

abbreviations (method _abbreviations) Simply put, this allows the user to use an option only by specifying beginning of the option with enough characters to make it identifiable. For instance, if you have -xyz and -xvii options, the user could specify -xy or -xv but -x would give an error.

filelistpref (method _filelistpref) This determines how extra arguments are handled. Possible values are -1, 1, 0. -1 is default and means no files are expected. 0 means that files may be present. 1 means files must be present. By default, if 0 or 1 is used, any argument not found to be a match for a known option is considered the start of the filelist and all other options are considered files. So, it is possible for a user to give a bad option and the script to take it as the start of the fileilst.

intermingledFiles (method _intermingledFiles) This gives the option to allow files to be anywhere in the arguments. Any argument that does not match a specified option is added to the filelist. This overrides the aforementioned behavior of filelistpref and does not take the first non-matching parameter as the start of the file list.

switchglomming (method _switchglomming) This allows a group of switches to be specified as the first argument. For instance, if you have -x -y -z -p -d & -q switches, then the user can specify them in a single argument but it b<must> be the first argument: UNIX> script.pl -xyzpdq There is an exception. If the particular combinations of switches actually spells out another option or abbreviation or alias thereof, the switchglom will take precedence. This may or may not be what the user is expecting. Using the development_check preference can help alleviate this.

Methods

The 3 types of methods that deal with parameters are those that define, parse and access the command line data.

Defining Methods

_parameter (_p)

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' );

_multi_parameter (_mp)

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' } );

_special_parameter (_sp)

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>, );

_multi_special_parameter (_msp)

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>, }, );

_help (_h)

For declaring some help text for the specified argument.

  $opt->_help( <name>, <help_text> );

_help_option (_ho)

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.

_alias (_a)

  $opt->_alias( <name>, <alias>, <alias2>, <alias3>, ... );

More than one alias can be specified.

_default (_d)

  $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', ], );

_required (_r)

Used to designate that a parameter must be specified by the user.

  $opt->_required( <name>, <help_text> );

_keys (_k)

A way to give a list of possible values for an argument.

  $opt->_keys( <name>,  );

_mutually_exclusive (_mutex)

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>, );

_required_group (_rg)

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>, );

_unique (_u)

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.

Parsing Methods

_parse

This runs the parser on @ARGV once all the parameters have been defined.

Accessing Methods

_arg

Routine to return the *first* value for specified parameter, unless the parameter is a 'switch', then return the scalar value.

_arge

Routine to return 0/1 depending on existance of specified parameter. Or for special parameters, can check existance of a specific arg.

_argc

Routine to return number of arguments for specified parameter.

_args

Routine to return all values as an ARRAY ref for specified parameter. Or array of array refs if multiple arguments for specified parameter.

_argl

Routine to return the value (or the next value) of the specified parameter.

_arglprepare

Routine to prepare for calling _argl (it resets the internal counter).

_argh

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.

_filelist

Routine to return filelist if one exists.

EXAMPLE

PLANNED FEATURES

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...:)

Command Parameter Completion

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.

POSSIBLE FEATURES

User Requests

I will entertain any [sane] ideas that users may have...:)

NOTES

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.

VERSION HISTORY

1.00

Full initial release.

AUTHOR

Harlin L. Hamilton Jr., <harlinh@cadence.com>

COPYRIGHT AND LICENSE

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.

cpanm Getopt::ExPar

perl -MCPAN -e shell
install Getopt::ExPar