/ 
Getopt-Easy-0.1
River stage two • 2 direct dependents • 20 total dependents
/ Getopt::Easy

NAME

Getopt::Easy - parses command line options in a simple but capable way.

SYNOPSIS

use Getopt::Easy;

get_options "v-verbose  f-fname=  D-debug=uSX",
            "usage => "usage: prog [-v] [-f fname] [-D [uSX]] [-H]",
            "H";

print "reading $O{fname}\n" if $O{verbose};
print "SQL: $sql\n" if $O{debug} =~ /S/;

DESCRIPTION

Perl puts the command line parameters in the array @ARGV allowing the user to examine and manipulate it like any other array. There is a long tradition of putting optional single character flags (preceded by a dash) in front of other parameters like so:

% ls -ltr *.h *.c
% tar -tvf all.tar
% ps -ax -U jsmith

Many Getopt::* modules exist to help with the parsing of these flags out of @ARGV. For the author, Getopt::Std was visually too cryptic and Getopt::Long was too large and complex for most normal applications. Getopt::Easy is small, easy to understand, and provides a visual clarity.

There are two things exported: get_options() and %O.

get_options has 1 required parameter and 2 optional ones. The first is a string describing the kind of options that are expected. It is a space separated list of terms like this:

get_options "v-verbose   f-fname=";

If the -v option is given on the command line %O{verbose} will be set to 1 (true). If the -f option is given then another argument is expected which will be assigned to $O{fname}.

Before parsing @ARGV, $O{verbose} will be initialized to 0 (false) and $O{fname} to "" (unless they already have a value).

If you give an unknown option get_options() will complain and exit:

% prog -vX
unknown option: -X
%

These conventions are implemented by Getopt::Easy:

  • The options can come in any order.

  • Multiple boolean options can be bundled together.

  • A command line argument of '--' will cause argument parsing to stop so you can parse the rest of the options yourself.

  • Parsed arguments are removed from @ARGV.

These invocations are equivalent:

% prog -v -f infile
% prog -f infile -v     # different order
% prog -v -finfile
% prog -vf infile
% prog -vfinfile

This shows that the space between -f and infile is optional and that you can bundle -f with -v but -f must be the last option in the bundle.

The optional second parameter to get_options() is a usage message to be printed when an illegal option is given.

get_options "v-verbose   f-fname=",
            "usage: prog [-v] [-f fname]";

Now if an unknown option is given, the same error message will be printed, as above, followed by the usage message.

% prog -vX
unknown option: -X
usage: prog [-v] [-f fname]
%

HELP

Sometimes the usage message is not enough and the user needs more detailed and elaborate help. This is where the 3rd optional parameter comes in.

get_options "v-verbose   f-fname=",
            "usage: prog [-v] [-f fname] [-H]",
            "H";

Giving the -H option will cause the POD for the module to be echoed to STDOUT - as if the user had typed 'perldoc prog'. See 'perldoc perlpod'.

DEBUGGING

There are various ways to implement a debugging option:

GOOD:

get_options "d-debug";

print "val = $val\n" if $O{debug};

BETTER:

get_options "d-debug=";

print "SQL = $sql\n" if $O{debug} >= 2;
print "val = $val\n" if $O{debug} >= 3;

With this method there are various levels of debugging. Unfortunately, they often end up ranging from 'not enough' to 'too much' :(.

BEST:

 get_options "d-debug=eSvL";

 print "SQL = $sql\n" if $O{debug} =~ /S/;
 print "val = $val\n" if $O{debug }=~ /v/;

With this kind of term the letters after the equal sign '=' are the debugging options that are valid. Now the user can choose exactly what kind of debugging output they wish to see.

% prog -d SL

Giving an illegal debugging option will result in an error message:

% prog -deXSf
for -d: illegal options: Xf, valid ones are: eSvL
%

ACCESS ELSEWHERE

If you want access to the %O hash from other files simply put:

use Getopt::Easy;

at the top of those files; the %O hash will again be exported into the current package. You need to have:

get_options ...;

only once in the main file before anyone needs to look at the %O hash.

STRICT

It is easy to misspell a key for the %O hash. Tie::StrictHash can help with this:

use GetOpt::Easy;
use Tie::StrictHash;

get_options "v-verbose  f-fname=";
strict_hash %O;

print "file name is $O{filename}\n";

This will give a fatal error message:

key 'filename' does not exist at prog line 6

SEE ALSO

Config::Easy allows configuration file entries to be overidden with command line arguments.

Tie::StrictHash protects against misspelling of key names.

Date::Simple is an elegant way of dealing with dates.

AUTHOR

Jon Bjornstad <jon@icogitate.com>