Programming Perl, 3rd Edition

Writing Your Own Pod Tools

Pod was designed first and foremost to be easy to write. As an added benefit, pod's simplicity also lends itself to writing simple tools for processing pod. If you're looking for pod directives, just set your input record separator to paragraph mode (perhaps with the -00 switch), and only pay attention to paragraphs that look poddish.

For example, here's a simple olpod program to produce a pod outline:

#!/usr/bin/perl -l00n
# olpod - outline pod
next unless /^=head/;
s/^=head(\d)\s+/ ' ' x ($1 * 4 - 4)/e;
print $_, "\n";

If you run that on the current chapter of this book, you'll get something like this:

Plain Old Documentation
    Pod in a Nutshell
        Verbatim Paragraphs
        Pod Directives
        Pod Sequences
    Pod Translators and Modules
    Writing Your Own Pod Tools
    Pod Pitfalls
    Documenting Your Perl Programs

That pod outliner didn't really pay attention to whether it was in a valid pod block or not. Since pod and nonpod can intermingle in the same file, running general-purpose tools to search or analyze the whole file doesn't always make sense. But that's no problem, given how easy it is to write tools for pod. Here's a tool that is aware of the difference between pod and nonpod, and produces only the pod:

#!/usr/bin/perl -00
# catpod - cat out just the pods
while (<>) {
    if (! $inpod) { $inpod = /^=/;            }
    if ($inpod)   { $inpod = !/^=cut/; print; }
} continue {
    if (eof)      {  close ARGV; $inpod = ''; }
}

You could use that program on another Perl program or module, then pipe the output ...