The Often Overlooked Perl Module Pod::Usage

Pod::Usage is one of those boring modules that doesn’t get the attention it deserves. Included in Perl core since 5.6.0, released fourteen years ago, it’s not a new kid on the block. It’s job isn’t sexy, so not lots of talks, blog posts, or tweets about it. There are only 5 ++s for the distribution on metacpan.org. It’s my goto module for all but the most trivial scripts, I probably use it second to only pragmas in scripts. (Haha, I made a funny.)

nn

Pod::Usage generates usage/help output for your scripts by extracting relevant bits from your POD. This means you write usage/help information once for the POD and you get both your man page and -h command line help. Let’s look at its usage by starting with the result. I’ll use otfile, a simple script for serving a file via HTTP from the command line for these examples.

nn

1n2n3n4n5n6n7n8n9n10n11n12n13n14n15n16n17n18n19n
$ otfile -hnUsage:n    $ otfile [-a -p 1234] nnOptions:n    --auto or -an            Auto port selection. Increments specified port until successful.nn    --port=N or -p Nn            Use specified port, defaults to 1234.nn    --multiple or -mn            Don't exit after serving the file the first time. To serve an            file to multiple people. Requires, CTL+C to exit.nn    --help or -hn            this help informationnn$

nnn

Nothing exceptional here, this is the style and content you would expect from any script on a POSIX like system. We get similarly unsurprising output for incorrect arguments.

nn

1n2n3n4n5n6n
$ otfile --invalid-arg-named-yaakovnUnknown option: invalid-arg-named-yaakovnUsage:n    $ otfile [-a -p 1234] nn$

nnn

So what does the source look like? One of Pod::Usage’s benefits is the simplicity in using it.

nn

1n2n3n4n
use Pod::Usage;nuse Getopt::Long;nnGetOptions( ..., 'help' => sub { pod2usage(1) } ) or pod2usage(2);n

nnn

That’s it in terms of code! You can substitute Getopt::Std or your other argument parser of choice just as easily. This was really cheating though since the real meat of it is in the POD. So anything special there?

nn

1n2n3n4n5n6n7n8n9n10n11n12n13n14n15n16n17n18n19n20n21n22n23n24n25n26n
=head1 SYNOPSISnn$ otfile [-a -p 1234] <file to serve>nn=head1 OPTIONSnn=over 8nn=item B<--auto> or B<-a>nnAuto port selection.  Increments specified port until successful.nn=item B<--port=N> or B<-p N>nnUse specified port, defaults to 1234.nn=item B<--multiple> or B<-m>nnDon't exit after serving the file the first time. To serve a file to multiplenpeople. Requires, CTL+C to exit.nn=item B<--help> or B<-h>nnthis help informationnn=backn

nnn

Nothing special in the POD. Pod::Usage with the source I used outputs either the POD’s SYNOPSIS section or the SYNOPSIS section and any section titled OPTIONS, ARGUMENTS or OPTIONS AND ARGUMENTS.

nn

That’s it! Now, head over to Pod-Usage on metacpan.org and give it some ++ love.

n