Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot

Interpolate Perl variables in POD

by repellent (Priest)
on Oct 01, 2008 at 00:00 UTC ( #714673=perlquestion: print w/replies, xml ) Need Help??
repellent has asked for the wisdom of the Perl Monks concerning the following question:

Just curious here -- this may have been asked before:

Is there a way to interpolate (read: substitute) variables in POD such that it will apply to all Pod::* modules? Perhaps something like:
=head1 Imaginary Interpolation This was defined previously: X<$my_perl_variable> =cut

Basic scalar-lookup substitution would be nice. I use pod2usage() and would like some dynamic capability in POD.

Replies are listed 'Best First'.
Re: Interpolate Perl variables in POD
by toolic (Bishop) on Oct 01, 2008 at 01:46 UTC
Re: Interpolate Perl variables in POD
by JavaFan (Canon) on Oct 01, 2008 at 00:14 UTC
    No, you cannot. POD code is skipped over by the perl compiler, and the Pod::* modules typically don't run the code at all.
Re: Interpolate Perl variables in POD
by GrandFather (Sage) on Oct 01, 2008 at 00:17 UTC

    POD is not processed by the Perl interpreter in a fashion where interpolation makes sense (the interpreter parses POD just enough to ignore it).

    Programs that process POD do not parse Perl (except enough to ignore it) so don't have values for Perl variables.

    Perl reduces RSI - it saves typing
      OK. But could there be a way to instruct the POD modules with a directive to substitute when it sees X<subst:keyword123> in POD? Maybe up front:
      use Pod::Subst qw(keyword123 replacement456)

      so that pod2usage() knows what to do. No Perl parsing need be involved.

      Thanks for the replies!

        You could post process the output from pod2usage() to do the substitutions. It would be smart to use a form of markup that is unlikely to be changed by the pod2usage() processing.

        Alternatively, you could preprocess the input to pod2usage() with the same caveat.

        Perl reduces RSI - it saves typing
Re: Interpolate Perl variables in POD
by jhourcle (Prior) on Oct 01, 2008 at 01:00 UTC

    As JavaFan and GrandFather have already mentioned, no, you can't directly. However, there's nothing to stop you from generating a POD document from a perl script:

    open (my $pod, '>', 'filename.pod') or die "Can't write pod file: $!"; my $my_perl_variable = 'something'; print $pod <<EOF; =head1 Imaginary Interpolation This was defined previously: C<$my_perl_variable> =cut EOF

    Of course, this would mean that you'd have to trigger the re-writing process somehow ... if you were to give an interface for updating whatever your variables were, you could regenerate the pod afterwards. I personally couldn't see the advantage of doing this, but I don't know what your full intentions are.

      Upon writing a USAGE for a script, I would like for pod2usage to be updated dynamically as I maintain & update my code in the long term.

      A static USAGE means I would have to do manually update the POD when my code changes.

        I run a script from within my editor to generate 'man pages' from the POD in the current buffer.

        Perl reduces RSI - it saves typing
      Just as an aside. Embedded pod-like text in here-docs can accidentally be extracted from the source file as POD.

      This happens for me with the above code sample:

      714680(1) User Contributed Perl Documentation 7 +14680(1) Imaginary Interpolation This was defined previously: $my_perl_variable perl v5.8.8 2008&#8208;10&#8208;01 + 714680(1)

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://714673]
Approved by GrandFather
Front-paged by Tanktalus
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (3)
As of 2018-06-22 04:02 GMT
Find Nodes?
    Voting Booth?
    Should cpanminus be part of the standard Perl release?

    Results (121 votes). Check out past polls.