Item Description: Declarative command line argument parser

Review Synopsis:

Getopt::Declare A quickie overview.

Getopt::Declare is a module for parsing command line options -- and like many of Damian Conway's modules, this one has obviously been eating its wheaties with large doses of steroids (and it arrives with circa 1,500 lines of documentation to prove it). In short, this is not your mother's command line parser.

Not satisfied with giving us yet another command line parser, Damian has given us a declarative language to specify not only command line options, but descriptions, parameter types, and actions as well. But don't let the size of the docs intimidate you, it is surprisingly simple to use.

The basic mechanics of using the module are as follows:

#!/usr/bin/perl -w
use strict;
use Getopt::Declare;
my $spec = <<'SPEC';
    # put your specification here
SPEC

my $ops = Getopt::Declare->new($spec);

# rest of your program
[download]

Obviously, it is the specification we are really interested in. So let's look a very trivial greplike script using the module:

#!/usr/bin/perl -w
use strict;
use Getopt::Declare;
use vars qw/$not $re/;
$::VERSION = 0.01;

my $spec = <<'EOS';

    -p <pattern>    pattern [required]
                        { $re = $pattern }

    -f <INFILE>...    input filename(s)  [required]
                        { defer{process(@INFILE)} }

    -not        print out non-matches
                        { $not = 1 }
EOS

my $opts = Getopt::Declare->new($spec);

sub process {
    @ARGV = @_;
    while(<>){
        if($::not){
            print unless /$::re/;
        } else {
            print if /$::re/;
        }
    }
}
__END__

[download]

An option declaration is comprised of a few components: the option specification itself (followed by one or more tabs); the option description (with optional directives); and an optional action block to be executed if the option is found. Let's break out the -f option above and look at each component:

    -f <INFILE>...
    # So we specify an option that looks like '-f' which takes one or
    # more arguments (that's the ... part) that will be stored in the
    # variable @INFILE for the action block
    
    input filename(s) [required]
    # This is the description of the option followed by the
    # [required] directive which means this option must be present on
    # the command line
    
    { defer{process(@INFILE)} }
    # This is the action block. The defer() function is from
    # Getopt::Declare and takes a code block which will not be
    # executed until all the command line options have been parsed.
    # Here we merely provide our own function and pass it the files
    # from the -f option as arguments.
[download]

The option variable is available as a lexical variable within the action block, and you may set or access any globals that are available at the time of parsing. In our example above we set the global $re and $not variables in the action blocks so we can access those later rather than accessing those options via the $opts object. We deferred our file processing action because we want to ensure all options have been parsed (and all globals set) before we start grepping our files.

You can also restrict parameter types when specifying parameter variables using a few predefined parameter types:

    -p <var:s> # accept strings
    -n <var:n> # accept any real number
    -i <var:i> # accept only integers
[download]

And, because this is Perl, you can also specify your own regex to limit the types of things a parameter should accept or define new types:

    -hw <hw:/\d+x\d+$/>        HeightxWidth coordinates
#or
    [pvtype: coord /\d+x\d+$]
    -hw <hw:coord>        HeightxWidth coordinates
[download]

This module also gives us a -help option for free, and a -v option (if you've defined a $VERSION variable). Here's what we get with those:

$ perl dopt.pl -v

        dopt.pl: version 0.01  (Fri Feb  2 09:30:34 2001)

$ perl dopt.pl -help

Usage: dopt.pl [options]  -p <pattern>  -f <INFILE>... 
       dopt.pl -help
       dopt.pl -version

Options:

        -p <pattern>            pattern 

        -f <INFILE>...          input filename(s)  

        -not                    print out non-matches
[download]

And, with 1,500 lines of documentation I've clearly only scratched the surface in this little overview. Go ahead and grab it, read the docs, and play around (and, if you're feeling brave, read the code too).