In Today’s Post

I provide a simple template I use to start every command-line utility I write in Perl. We’ll also make command-line option parsing easy using Getopt::Long, as well as make encapsulated documentation using POD.

Perl, the Swiss Army Chainsaw

Perl is an excellent language for system scripting. There are those who criticize Perl for being “syntactically excessive.” However, as languages evolve expressive power they often become more complicated. Remaining backward compatible requires carrying around a certain amount of syntactic baggage.

I’m pragmatic in that I’d choose a language that was powerful with a few eccentricities over one that was perfect and less useful, or one that had stopped evolving. Languages are a living thing – they need to adapt to changes in the environment or they die.

Perl will always be alive and well because it’s just too damn useful. Larry Wall, the creator of Perl, has described his creation variously as “duct tape for the Web” and a “Swiss Army chainsaw”. Perl’s hallmark is flexibility, which is just what’s required to glue things together that weren’t necessarily designed to be glued together.

In a future post I’ll show you a style of Perl programming that works well for me and provides just the right amount of OOP without going overboard. This is actually simpler to do than you might think.

Unix Command Line Utilities Are Reusable, System-Level Building Blocks

1. One of the reasons Unix is so successful is the philosophy of “doing one thing really well.” Command-line utilities are designed to address a single problem well.
2. A second reason Unix is so successful is the “building block approach” – simple, well designed components can be connected together in various ways to solve a larger problem.
3. Unix command-line utilities should be thought of as reusable, system-level building blocks.
4. Write a command-line utility rather than a script. This is a conceptual task, which requires a few simple steps. One can often alter a script to turn it into a command-line utility.

Note, when I say Unix here, I mean “Unix and all it’s related descendants”, such as Linux (I’m old school, deal). I typically work with Linux (RHEL4, FC8) and FreeBSD (4 and 6).

I differentiate between scripts and command-line utilities. I think of a script as being designed for a single purpose, whereas a command-line utility was (should be) a building block. This is largely conceptual, and I realize it’s not a hard and fast rule, but it tends to be true.

I can’t count the number of times I’ve had to rewrite something someone wrote, just because they didn’t take the time to think of things from the perspective of reusability. The template below solves a few problems in this area.

Parsing Options

Command-line utilities often have a plethora of options that fine tune their behavior. For example the “ls” command has 36 “single character” options on OS X. The reason for having so many options is related to the design principles I’ve already mentioned: do one thing really well and make it so no one has to ever do it again (i.e. make it a building block). “ls” is designed to be used interactively, as well as produce output that is consumed by other programs, and so modifying it’s output via options is important (less so today since languages like perl have their own internal methods of listing files, like globbing).

One of the annoying parts of writing a command-line utility is parsing options. Options may have arguments, be different types, have valid and invalid ranges, and they need error checking. It’s also useful to be able to print a list of them from the program (using -h, or –help).

The perl library Getopt::Long solves the problems I’ve just described in an elegant way. In addition it’s got lots of extra bells and whistles for doing things like “repeated arguments”. The template below uses Getopt::Long and demonstrates it’s power.

What does this code do?

The code below is a “starting template”. I have a directory called “templates” which are simple program starting points for different purposes. When I want to write a command-line utility, I copy the template and make changes.

1. Command-line option parsing through Getopt::Long.
2. Internal documentation which can be programatically displayed, or formatted by other programs. This is done with Perl’s POD format (Plain Old Documentation).
3. Basic error handling.
4. As a template, its purpose is to jog my memory so I don’t have to try to remember how to use Getopt::Long, or the correct format for POD. Thus the code as-is doesn’t do too much (we’ll see how to use it below).

Starting Template: Unix Command Line Utility

#!/usr/bin/perl

# Use this "starter template" as a starting point for your
# own cmdline utilities.  Shows how to use Getopt::Long for
# option processing and POD for documentation.
#
# http://rogerbush.wordpress.com/2008/02/19/
# command-line-programs-and-perl-getoptlong/

use strict;
use warnings;

use Getopt::Long;
use Pod::Usage;

sub main
{
    my %options;

    GetOptions
        (\%options,
         'help|?',
         'length=i',
         'filename=s',
         'addr=s@',
         'man') or pod2usage (2);

    pod2usage (1) if $options{help};
    pod2usage (-exitstatus => 0, -verbose => 2)
        if $options{man};

    if ($options{length})
    {
        pod2usage ("--length must be > 0.")
            unless $options{length} > 0;

        print "length is $options{length}\n";
    }

    print "filename is $options{filename}\n"
        if $options{filename};

    if ($options{addr})
    {
        foreach my $a (@{${options{addr}}})
        {
            print "addr: $a\n";
        }
    }
}

main ();
__END__

=head1 NAME

perlcmdline - A do nothing, starter template for implementing
command-line utilities.

=head1 SYNOPSIS

perlcmdline [options]

"perlcmdline --help" will list options.  "perlcmdline --man"
will show docs.

=head1 OPTIONS

=over 4

=item B<--help>

Print a brief help message and exits.

=item B<--man>

Prints the manual page and exits.

=item B<--length positive-integer>

A "do nothing" length value which must be an int > 0.

=item B<--filename input-filename>

A "do nothing" string value.

=item B<--addr hostname-or-ip>

An internet address.  This option may be used multiple
times in a single command to specify multiple addresses.

=back

=head1 AUTHOR

Roger Bush, rogerbush8 at yahoo dot com

=head1 COPYRIGHT

Copyright (c) 2007 Roger Bush. All rights reserved. This
program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut

1. Getopt takes many forms.  In the form I'm using, I pass
   in a hash to hold all of the variables rather than assigning
   values to loose variables.
2. Getopt allows other types of inputs, such as hashes,
   flags, and several other types.  For a full list see the
   reference at the end of this post.
3. If a value is not specified, it will not be defined in the
   options hash (e.g. if ( ! defined $options{foo})).
4. The expression @{$options{addr}} evaluates to an array
   (it dereferences the array ref at $options{addr}.  Similarly
   %{hash_ref} would dereference a hash.
5. __END__ tells perl where the code has ended.  This always
   precedes the docs at the end which are called "POD" (Plain
   Old Documentation).  Perl's POD has special directives which
   start a new line with a "=name-of-directive".  See ref on
   POD at end of blog for more.
6. =over, and =back are POD indenting commands.  over
   indents the given number of spaces, and back goes back
   to the indenting setup prior to the over statement.
7. pod2usage prints out the SYNOPSIS and potentially
   the options in the POD section, when given a single
   numeric argument (1 is Usage, 2 is Options).  It can also
   be provided a hash of options affecting its behavior.

Time to give the program a try. Let’s try an unknown option to see how it handles it:

$ ./perlcmdline --foo
Unknown option: foo
Usage:
    perlcmdline [options]

    "perlcmdline --help" will list options. "perlcmdline --man"
    will show docs.

It told us that “foo” was an “Unknown option” and then it printed out usage from the SYNOPSIS (POD) section. This is the behavior of “pod2usage(2)”. Note the helpful “–help” and “–man” info we added to SYNOPSIS.

Now let’s try the “–length” option without the argument (it requires a number):

$ ./perlcmdline --length
Option length requires an argument
Usage:
    perlcmdline [options]

    "perlcmdline --help" will list options. "perlcmdline --man"
    will show docs.

Now let’s try a length that is equal to zero (we explicitly check for this and exit from the command-line):

$ ./perlcmdline --length 0
--length must be > 0.
Usage:
    perlcmdline [options]

    "perlcmdline --help" will list options. "perlcmdline --man"
    will show docs.

Now let’s try misspelling length (we’ll truncate it):

$ ./perlcmdline --len 5
length is 5

Whoa, what happened there? It turns out that Getopt automatically supports abbreviation. It will use the string to match the longest match possible.

Let’s try “–help”:

./perlcmdline --help
Usage:
    perlcmdline [options]

    "perlcmdline --help" will list options. "perlcmdline --man"
    will show docs.

Options:
    --help
        Print a brief help message and exits.

    --man
        Prints the manual page and exits.

    --length positive-integer
        A "do nothing" length value which must be an int > 0.

    --filename input-filename
        A "do nothing" string value.

    --addr hostname-or-ip
        An internet address.  This option may be used multiple
        times in a single command to specify multiple addresses.

Very cool. The options listed under (POD) OPTIONS got printed this time, due to pod2usage(1). Try “–man” on your own.

Now, let’s try some legitimate options.

$ ./perlcmdline --filename bar --length 2 --addr 127.0.0.1
--addr 192.168.0.1
length is 2
filename is bar
addr: 127.0.0.1
addr: 192.168.0.1

Note that the multiple options specified using –addr worked properly, as well as the other options.

Conclusion

Now you’ve got a template for creating command-line utilities that have embedded documentation and handle options with ease. You should copy it and use it as a starting point whenever you want to write a script or command-line utility. We’ve alsoseen the basics of using Getopt::Long, as well as basic POD, and pod2usage.

There are a few more important aspects to writing good command-line utilities that I’ll save for other posts.

References

1. Getopt::Long docs at perldoc.perl.org
2. pod2usage docs at perldoc.perl.org
3. POD docs at perldoc.perl.org