[Purdue-pm] Variables in POD docs
Rick Westerman
westerman at purdue.edu
Wed Dec 3 05:19:47 PST 2014
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
More information about the Purdue-pm
mailing list