[Purdue-pm] Variables in POD docs

[Rick Westerman]

Found an interesting way to embed variables into pod.  You might want this so you could report the VERSION both inside pod plus as $VERSION.  But you could also do this for exported modules.  You could make a list of routines plus their descriptions to be shown in pod plus have them in the actual @EXPORT thus avoiding the need have the routine listed twice — and potentially missing the documentation when a new routine is added to the module.  Another use is to show a hash or array inside pod.


I’ll probably give a short talk on this at the next Mongers meeting.  Dave, in the meantime, could look at my recent PI.pm module for concrete examples.

The idea is to do a here-is capture of the POD comments and then parse out the Perl-runtime information from the captured doc.  There is a small run-time hit in doing the parsing but I do not think that the hit is significant and the ability to not have to have information in two places is powerful.  A short example:


=====

my $version_pod = <<'=cut';

=head1 VERSION 1.0

    Complete re-write to use database and to be more stable. 

=cut

our ($VERSION) = $version_pod =~ m/VERSION\s+(.*)/;

=====



--
Rick Westerman
westerman at purdue.edu