Friends of Pythian Referral Program - Earn up to $5000!

Local POD browsing: using Pod::POM::Web via the CLI

Posted in: Technical Track

Half the time I want to peek at the doc of a module, I hit perldoc.  The rest of the time I type cpan Some::Module[1] in Firefox and read the POD straight out of CPAN.  And while it’s pretty and handy, it also feels kinda silly to go on a remote server to read documentation that is also sitting on my computer. Surely, I tell myself, there must be a better way.

Cue in the several Perl modules that act as local POD web servers.  After giving a few of them a quick test-run, I decided to give Pod::POM::Web a try. Being a CLI jockey, I wanted to be able to open the POD of a module from the command line.  Not a problem, I just had to create the script ‘pod’:



perl -MPod::POM::Web -e"Pod::POM::Web->server($POD_PORT)" 2> /dev/null &

PAGE=`perl -e's(::)(/)g for @ARGV; print @ARGV' $1`


kfmclient openURL "http://${HOSTNAME}:$POD_PORT/$PAGE";

There is not even a need to fire up the Pod::POM::Web server beforehand: the script will do it for us (if the server is already running, subsequent calls to pod will harmlessly try to start a new server on the same port and fail).  It should be noted that ‘kfmclient’ is KDE-specific — for any other desktop environment, you might want to change that to a direct call to firefox.

It’s already not too shabby, but wouldn’t it be even better with a little bit of auto-completeness magic?  To do that, we need a short script, pod_complete:


use 5.010;

use List::MoreUtils qw/ uniq /;

my ( $sofar ) = reverse split ' ', $ENV{COMP_LINE};

$sofar =~ s(::)(/)g;

my ( $path, $file ) = $sofar =~ m!^(.*/)?(.*)?$!;

my @dirs = map { $_.'/'.$path } @INC;

my @candidates;

for ( @dirs ) {
    opendir my $dir, $_;
    push @candidates, grep { /^\Q$file/ } grep { !/^\.\.?$/ } readdir $dir;

if ( $path ) {
    $_ = $path.'/'.$_ for @candidates;

s/\.pm$// for @candidates;
s(/+)(/)g for @candidates;

say for uniq @candidates;

All that is left is to add . . .

complete -C pod_complete pod

. . . to our bashrc, and it should all work (with the caveat that the modules must be entered as Some/Module instead of Some::Module).

$ pod XML/XPath
XML/XPath        XML/XPathScript

[1] If you don’t already know the trick: create a bookmark with keyword ‘cpan’ and location


Interested in working with Yanick? Schedule a tech call.

3 Comments. Leave new

For info, I just released a new version of Pod::POM::Web (v1.13), with a number of bug fixes and improvements. It also depends on a new version of Alien::GvaScript.

Yanick Champoux
January 18, 2010 12:48 pm

Excellent timing! Thanks.

So far, the only functionality that I’m missing from PPW is a regexp search on modules — e.g., give me all modules matching /CSV/. Having that last piece would really be the bee’s knee. :-)


UPDATE: Aristotle took a shine for my completion script and ran away with it. The result is a much, much cleaner and portable codebase.

Details at and, and the code itself is at


Leave a Reply

Your email address will not be published. Required fields are marked *