Hacking Thy Fearful Symmetry

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’:

#!/bin/bash

POD_PORT=8787

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

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

HOSTNAME=`hostname`

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:

#!/usr/bin/perl

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 http://search.cpan.org/search?query=%s.