modulereview
danger
<p><b>Getopt::Declare</b> A quickie overview.</p>
<p>
[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.
</p>
<p> 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.</p>
<p> The basic mechanics of using the module are as follows:</p>
<code>
#!/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
</code>
<p> Obviously, it is the specification we are really interested in.
So let's look a very trivial greplike script using the module: </p>
<code>
#!/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__
</code>
<p> 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:</p>
<code>
-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.
</code>
<p> 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
<code>$re</code> and <code>$not</code> variables in the action blocks
so we can access those later rather than accessing those options via
the <code>$opts</code> 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.
</p>
<p> You can also restrict parameter types when specifying parameter
variables using a few predefined parameter types: </p>
<code>
-p <var:s> # accept strings
-n <var:n> # accept any real number
-i <var:i> # accept only integers
</code>
<p>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:</p>
<code>
-hw <hw:/\d+x\d+$/> HeightxWidth coordinates
#or
[pvtype: coord /\d+x\d+$]
-hw <hw:coord> HeightxWidth coordinates
</code>
<p>
This module also gives us a <code>-help</code> option for free, and
a <code>-v</code> option (if you've defined a <code>$VERSION</code>
variable). Here's what we get with those:
</p>
<code>
$ 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
</code>
<p> 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).
</p>
Declarative command line argument parser