Perl Advent Calendar 2006-12-12½

Santa makes a list, and checks it twice. But he only makes one list.

by Jeff Lavallee

Getopt::Euclid will use the POD to deduce how to parse the program's command line options. This guarantees that your POD and the actual interface will always be in sync. Some words of warning though: there is, of course, a run-time cost associated with this, and it does require that your POD adhere to particular conventions. In addition the parsed options will be provided in %ARGV, you might not find this quite as convenient as the alternatives provided by Getopt::Long. Finally, Pod::Usage has the advantage of being part of the core distribution since Perl 5.6

What if we run the Getopt::Euclid version of our previous code sample without any options?

santa@northpole:~/ $ ./example_euclid.pl 
 Missing required argument:
         -f[ile] [=] <filename>
 (Try: example_euclid.pl --help)

Again, we get the usage information. However, notice that there's no explicit call in our script to do this. Getopt::Euclid does this because the -file argument was listed in the REQUIRED section of the POD.

Here's the help that's provided:

santa@northpole:~/ $ ./mod12B.pl --help
Usage:
    mod12B.pl -f <filename> [optional arguments]

Required arguments:
    -f[ile] [=] <filename>
            The filename to be used as input.

Optional arguments:
    -v[erbose]
            Print verbose output as the script runs. Can be used more than
            once to increase the verbosity.

And let's see what those options look like:

santa@northpole:~/ $ ./mod12B.pl -file foo -v
I got the following options:
$VAR1 = {
          '-file' => 'foo',
          '-verbose' => [
                          '1'
                        ],
          '-v' => [
                    '1'
                  ],
          '-f' => 'foo'
        };

Notice that Getopt::Euclid set both the long and short versions of the options (indicated in the POD with -f[ile], for example). Getopt::Euclid also provides a --man option by default, that will print the whole man page for the script.

mod12B.pl

  1 #!/usr/bin/perl
  2 
  3 =head1 NAME 
  4 
  5 my_script.pl
  6 
  7 =head1 REQUIRED ARGUMENTS
  8 
  9 =over 8
 10 
 11 =item -f[ile] [=]  
 12 
 13 The filename to be used as input. 
 14 
 15 =back
 16 
 17 =head1 OPTIONAL ARGUMENTS
 18 
 19 =over 8
 20 
 21 =item -v[erbose]
 22 
 23 Print verbose output as the script runs. 
 24 Can be used more than once to increase the verbosity.
 25 
 26 =for Euclid:
 27     repeatable
 28 
 29 =back
 30 
 31 =head1 BUGS
 32 
 33 None known at this time
 34 
 35 =cut
 36 
 37 use Getopt::Euclid;
 38 use Data::Dumper;
 39 
 40 print "I got the following options:
 41 @{[ Dumper \%ARGV ]}
 42 " if $ARGV{-verbose}->[0];