Hack 3. Browse Perl Docs Online


Hack 3. Browse Perl Docs Online

Host your own HTML documentation.

perldoc is a fine way to view the documentation for Perl and all your installed modules and to output them in the file format of your choice ("Put Perldoc to Work" [Hack #2]). perldoc's little brother, podwebserver, is an even handier way to browse documentationand bookmark it, and search it, and sometimes even hardcopy it, all through whatever web browser you're using this week.

The Hack

podwebserver provides basically perldoc-as-HTML over HTTP. Sure, you could always just browse the documentation at http://search.cpan.org/but using podwebserver means that you'll be seeing the documentation for exactly your system's Perl version and module versions.

podwebserver's HTML is compatible with fancy browsers as well as with more lightweight tools such as lynx, elinks, or even the w3m browser in Emacs. In fact, there have been persistent rumors of some users adventurously accessing podwebserver via cell phones, or even using something called "the Micro-Soft Internet Explorer." O'Reilly Media, Inc. can neither confirm nor deny these rumors.

If podwebserver isn't on your system, install the Pod::Webserver module from CPAN.

Running the Hack

To run podwebserver, just start it from the command line. You don't need root access:

$ podwebserver
            

Then start a web browser and browse to http://localhost:8020/. You'll see the index of the installed documentation (Figure 1-2).

Figure 1-2. An index of your Perl documentation


If you don't want to bind the web server to localhost, or if you have something already running on port 8020, use the -H and -p arguments to change the host and port.

$ podwebserver -H windwheel -p 8080
            

Hacking the Hack

Running a program and switching to your web browser to view a bookmark is too much work when you just want to check some documentation. Make your life easier with a little shell script ("Make the Most of Shell Aliases" [Hack #4]):

#!/bin/sh

podwebserver &
sleep 2
firefox -remote 'openurl( http://localhost:8020/, new-tab)'

Save the program as ~/bin/podweb, make it executable (chmod +x ~/bin/podweb), make sure ~/bin/podweb is in your $PATH, then run it:

$ podweb
            

If you have Mozilla Firefox open, this will pop up the index page in a new tab. Other web browsers have similar invocation schemes.


Hack 4. Make the Most of Shell Aliases

Make programming easier by programming your shell.

Perl is a language for people who type. It grew up from the shell to write all kinds of programs, but it still rewards people who don't mind launching programs from the command line.

If you spend your time writing Perl from the command line (whether you write short scripts or full-blown programs), spending a few minutes automating common tasks can save you lots of development timeand even more trouble.

Configuring Your Shell

The single most useful shell trick is the realias command. Normally creating a persistent alias means adding something to your .bashrc (or equivalent) file, starting a new shell, testing it, and then repeating the process until you get it right. Wouldn't it be nice to be able to edit and test a new alias in a single process?

Edit your .bashrc file and add a single line:

source ~/.aliases

Then create the file ~/.aliases, containing:

alias realias='$EDITOR ~/.aliases; source ~/.aliases'

If you prefer tcsh, edit your .cshrc file. Then replace the = sign with a single space in all of the alias declarations.


Launch a new shell. Type the command realias and your favorite editor (assuming you have the EDITOR environment variable set, and if you don't something is weird) will open with your ~/.aliases file. Add a line and save and quit:

alias reperl='perl -de0'

Now type reperl [2] at the command line:

[2] A pronounceable version of REPLRead, Evaluate, Print, and Loop.

$ reperl

Loading DB routines from perl5db.pl version 1.28
Editor support available.

Enter h or 'h h' for help, or 'man perldebug' for more help.

main::(-e:1):   0
  DB<1> q
            

Within a single shell session you've identified a useful command that may be difficult to remember, automated it, and have started to use it productively. Nifty.

Useful Shell Aliases

What makes a good shell alias for Perl programming? Obviously a command that's difficult to remember, such as the one to put the Perl debugger into pseudo-interactive mode. Another good approach is to alias commands that are lengthy or otherwise difficult to type. One final category is a series of chained commands you find yourself typing often.

Here are a few examples. Change the paths as necessary, of course, but have fun removing a little more of the tedium from your life every time you notice yourself repeating something you could automate away. That's the Perl way.

Juggle multiple Perl versions

Suppose you're in the midst of upgrading Perl versions while you still have to maintain an older installation. You might have multiple versions of Perl installed. Instead of typing different paths all the time and instead of relying on tab completion to differentiate between perl5.8.8 and perl5.6.2 and so on, make the names different at the start:

alias newperl='/usr/local/bin/perl5.8.8'
alias oldperl='/usr/local/bin/perl5.6.2'

This is especially handy if you have a system Perl installed and don't want to break things by overwriting it.

Juggle multiple module versions

Suppose that you also must test your code against multiple versions of a module or library. For example, you need to know if your code works against version 4.x and 5.x of a database. Alias away the different library paths:

alias newdbperl='perl -M/home/dev/newlib/'
alias olddbperl='perl -M/home/dev/oldlib/'

Don't forget multipart commands

If you're a rigorous tester, you've likely encountered Devel::Cover. Though it's easy to use, it takes multiple steps to write a new report. Alias that away!

alias testcover='cover -delete; ./Build testcover; cover'

Remember configuration options

Suppose that you decide to test the Pugs project (http://www.pugscode.org/) and want to embed both Perl 5 and Parrot. Because Pugs undergoes such rapid development, you might have to run its Makefile.PL several times a week. Why make yourself remember how to configure it with the correct options every time? Alias it!

alias makepugs='PARROT_PATH="/home/chromatic/dev/parrot" \\
    PUGS_EMBED="perl 5 parrot" \\
    perl Makefile.PL && make'

Find a module's version

Sometimes you really need to know the version of a moduleespecially when you're tracking down a bug across multiple machines or pondering an upgrade. Typing out:

$ perl -MCGI::Application -le 'print CGI::Application->VERSION'
4.03

every time is too much work. Stick a function instead in your .bashrc:

function pmver ( ) { perl -M$1 -le "print $1->VERSION"; }

You can also add more error checking and turn it into an alias:

alias pmver="perl -le '\\$m = shift; eval qq(require \\$m)
   or die qq(module \\"\\$m\\" is not installed\\\\n); print \\$m->VERSION'"

Either way, run it as pmver:

$ pmver CGI::Application
4.03

Change Unix paths to Windows paths and back

These aliases work on Windows under Cygwin too. Even though it's still Windows on one side and Unix on the other, there's no reason you can't make it work correctly. Here's an alias that translates a Unix path to a Windows path and executes the Windows version of gvim on the file:

alias gvim='perl -we "exec q{/cygdrive/c/Progra~1/Vim/vim63/gvim.exe},
  map { s/^(.*)$/(-f \\$1)?qx{cygpath -aw \\"\\$1\\"}:\\$1/e; chomp; \\$_; }
  (@ARGV); "'

Launching general Windows programs from bash requires a similar hack:

alias winrun='exec 'cmd', "/c", ((split '/',$0)[-1], map {
  s/^(.*)$/(-f $1)?qx{cygpath -w "$1"}:$1/e;chomp;$_; } (@ARGV));'

Now you can launch non-Cygwin programs with arguments.