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
        --man       Display documentation
    -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 also 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.

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

Mode options will be prepended to any 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 'name specification' is required):

[name specification, description, argument specification, destination]

name specification may be a scalar string, eg "length", or a reference to an array of alternate option names, eg [qw(l length)]. If an array of alternate names is used, the key to the option value as returned by the opts() method is the first long option (longer than one character) or the first character if all names are single characters. ie. [qw(l length height)] will use "length" as the option key.

The argument specification is passed directly to Getopt::Long, so any syntax 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
    !   Negatable option

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.

$go->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.

The following options may be automatically added by Getopt::Compact:

"This help message" (-h or --help)

A help option is automatically prepended to the list of available options if the usage constructor option is true (this is enabled by default).

"Display documentation" (--man)

This option is prepended to the list of available options unless an alternative --man option has been defined.

$go->pod2usage()

Displays the POD as a manpage. The POD will be altered to include a USAGE section containing the usage information, unless a USAGE section already exists. This is invoked automatically by the --man option.

$go->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.

$go->opts()

    $opt = $go->opts;

Returns a hashref of options keyed by 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 -h or --help option is given.

VERSION

$Revision: 4 $

AUTHOR

Andrew Stewart Williams

SEE ALSO

Getopt::Long