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.)
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
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.
1 2 3 4 5 6
So what does the source look like? One of Pod::Usage’s benefits is the simplicity in using it.
1 2 3 4
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?
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
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.
That’s it! Now, head over to Pod-Usage on metacpan.org and give it some ++ love.