Programming Perl, 4th 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
    Command Paragraphs
    Flowed Text
  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 ...