NAME

Getopt::Compact - getopt processing in a compact statement with both long and short options, and usage functionality.

SYNOPSIS

inside foobar.pl:

    use Getopt::Compact;

    my $opt = new Getopt::Compact
        (name => 'foobar program', version => '1.0',
         modes => [qw(verbose test debug)],
         struct =>
         [[[qw(w wibble)], qq(specify a wibble parameter), ':s'],
          [[qw(f foobar)], qq(apply foobar algorithm)],
          [[qw(j joobies)], qq(jooby integer list), '=i', \@joobs],
         ]
        )->opts;

    print "applying foobar algorithm\n" if $opt->{foobar};
    print "joobs: @joobs\n" if @joobs;

running the command './foobar.pl -x' results in the following output:

    Unknown option: x
    foobar program v1.0
    usage: foobar.pl [options]
    options
    -h, --help      This help message
    -v, --verbose   Verbose mode
    -n, --test      Test mode
    -d, --debug     Debug mode
    -w, --wibble    Specify a wibble parameter
    -f, --foobar    Apply foobar algorithm
    -j, --joobies   Jooby integer list

DESCRIPTION

This is yet another Getopt related module. Getopt::Compact is geared towards compactly and yet quite powerfully describing an option syntax. Options can be parsed, returned as a hashref of values, and/or displayed as a usage string. Options can be retrieved in a single statement by instantiating a Getopt::Compact object and calling the opts() method (see SYNOPSIS).

PUBLIC METHODS

new()

    my $go = new Getopt::Compact(%options)

Instantiates a Getopt::Compact object. This will parse the command line arguments and store them for later retrieval (via the opts() method). On error a usage string is printed and exit() is called, unless you have set the 'usage' option to false.

The following constructor options are recognised:

name

The name of the program. This is printed at the start of the usage string.

cmd

The command used to execute this program. Defaults to $0. This will be printed as part of the usage string.

version

Program version. Can be an RCS Version string, or any other string. Displayed in usage information.

usage

'usage' is set to true by default. Set it to false (0) to disable the default behaviour of automatically printing a usage string and exiting when there are parse errors or the --help option is given. When set to true a help option (-h or --help) is automatically prepended to the list of available options.

args

A string describing mandatory arguments to display in the usage string. eg:

print new Getopt::Compact (args => 'foo', cmd => 'bar.pl)->usage;

displays:

usage: bar.pl [options] foo

modes

This is a shortcut for defining boolean mode options, such as verbose and test modes. Set it to an arrayref of mode names, eg [qw(verbose test)]. The following statements are equivalent:

    my $go = new Getopt::Compact
        (struct => [[[qw(v verbose)], qw(verbose mode)],
                    [[qw(n test)],    qw(test mode)],
                    [[qw(d debug)],   qw(debug mode)],
                    [[qw(f foobar)],  qw(activate foobar)],
                   ]);

and

    my $go = new Getopt::Compact
        (modes => [qw(verbose test debug)],
         struct => [[[qw(f foobar)], qq(activate foobar)]]);

modes will be prepended to options defined via the 'struct' option.

struct

This is where most of the option configuration is done. The format for a struct option is an arrayref of arrayrefs in the following form ([] denotes an arrayref):

struct => [arrayref, arrayref]

arrayref is of the form (only optref is required):

[optref, description, argument specification, destination]

optref is of the form:

[qw(x yyyyy)] where x is the short (single character) option and yyyyy is the long option.

The 'argument specification' is passed directly to Getopt::Long, so any argument specification recognised by Getopt::Long should also work here. Some argument specifications are:

    =s  Required string argument
    :s  Optional string argument
    =i  Required integer argument
    +   Value incrementing

Refer to Getopt::Long documentation for more details on argument specifications.

The 'destination' is an optional reference to a variable that will hold the option value. If destination is not specified it will be stored internally by Getopt::Compact and can be retrieved via the opts() method. This is useful if you want options to accept multiple values. The only way to achieve this is to use a destination that is a reference to a list (see the joobies option in SYNOPSIS by way of example).

configure

Optional configure arguments to pass to Getopt::Long::Configure in the form of a hashref of key, boolean value pairs. By default, the following configuration is used:

{ no_auto_abbrev => 1, bundling => 1 }

To disable bundling and have case insensitive single-character options you would do the following:

new Getopt::Compact (configure => { ignorecase_always => 1, bundling => 0 });

see Getopt::Long documentation for more information on configuration options.

usage()

    print $go->usage();

Returns a usage string. Normally the usage string will be printed automatically and the program will exit if the user supplies an unrecognised argument or if the -h or --help option is given. Automatic usage and exiting can be disabled by setting 'usage' to false (0) in the constructor (see new()). This method uses Text::Table internally to format the usage output.

status()

    print "getopt ".($go->status ? 'success' : 'error'),"\n";

The return value from Getopt::Long::Getoptions(). This is a true value if the command line was processed successfully. Otherwise it returns a false result.

opts()

    $opt = $go->opts;

Returns a hashref of options keyed by long option name. If the constructor usage option is true (on by default), then a usage string will be printed and the program will exit if it encounters an unrecognised option or the --help option is given.

AUTHOR

Andrew Stewart Williams <andrew.s.williams@adelaide.edu.au>

SEE ALSO

Getopt::Long