Using pmless and pmdoc (pmman) to quickly view module’s source code & documentation on the CLI

Over the course of about a year, I’ve trained my muscle memory to use pmless instead of less to view source code and pmman instead of man to view documentation, when it comes to Perl modules. They come with the CPAN distribution App-PMUtils (along with a few other CLI utilities) and they offer some shortcuts and tab completion tricks to help you type less.

Installing

The requirement is that you use bash. In theory other shells like zsh and fish (and even tcsh) should work too, but I haven’t had the time to test those other shells.

First, install shcompgen. This utility will make it easier when you install all the other tab completion-aware utilities from CPAN in the future by instantly enabling tab completion right after installation.

% cpanm -n App::shcompgen

After installation, the distribution will install a file in ~/.config/shcompgen.bashrc. You have to run this script in your bash startup file (this is the only manual thing you need to do). For example, in your ~/.bashrc, put:

. ~/.config/shcompgen.bashrc

Now logout and login again. Or, just execute the above line in your shell prompt. Now you’re all set.

Install App::PMUtils:

% cpanm -n App::PMUtils

Now you have pmless, pmman (et al) with tab completion already (readily) activated.

Usage

From now on I’m only going to use pmman in the examples. You just substitute the command with another depending on what you want to do.

pmman accepts the name of Perl modules in the form of Foo::Bar or Foo/Bar, but Foo/Bar is recommended unless you customize your bash completion setting to exclude the : (colon) character from the word-breaking set.

To view documentation on a module:

% pmman HTTP/Request/Common

Of course, that’s not very lazy or convenient. First of all, tab completion is case-insensitive by default so you can type:

% pmman http[Tab]
% pmman HTTP/_

Also, tab completion completes intermediate paths for you by default, so you can also do:

% pmman h/r/com[Tab]
% pmman HTTP/Request/Common _

As long as the few first characters are unique, the tab completion will immediately complete the module name for you.

The tab completion is also fuzzy matching by default, so if you miss one or mistype one or two characters, don’t worry:

% pmman htp/r[Tab]
% pmman HTTP/Re_

You can increase the fuzziness setting if you want looser/more liberal correction, for example:

% EXPORT COMPLETE_OPT_FUZZY=5
% pmman proc/proctab[Tab]
% pmman Proc/ProcessTable_

Lastly, there are some shortcut prefixes to complete popular namespace prefixes for long/deep module names. By default this is (see Complete::Module):

        {
          dzb => "Dist/Zilla/PluginBundle/",
          dzp => "Dist/Zilla/Plugin/",
          dzr => "Dist/Zilla/Role/",
          pwb => "Pod/Weaver/PluginBundle/",
          pwp => "Pod/Weaver/Plugin/",
          pwr => "Pod/Weaver/Role/",
          pws => "Pod/Weaver/Section/",
        }

But they are configurable from the command-line.

So instead of:

% pmman d/z/p/test[Tab]
% pmman Dist/Zilla/Plugin/Test_

you can also type:

% pmman dzp/test[Tab]
% pmman Dist/Zilla/Plugin/Test_

Advertisement