Re: Using PerlPod Creatively

You can even do the reverse and use your POD as code:

my $str = <<=cut;

=head2 Some documentation

=cut
[download]

The above will assign the POD to $str but also render it when viewed with a POD viewer.

From time to time, I think this would be a cool way to store self-documenting configuration data, but other times I think this might be a far too clever approach.

Comment on Re: Using PerlPod Creatively Select or Download Code

Replies are listed 'Best First'.
Re^2: Using PerlPod Creatively by kcott (Archbishop) on Mar 25, 2017 at 06:32 UTC
G'day Corion, ++ For the technique. However, there is a problem with that code as written: `$ cat pm_1185726_heredoc_pod.pl my $str = <<=cut; =head2 Some documentation =cut $` [download] `$ perl -MO=Deparse pm_1185726_heredoc_pod.pl Use of bare << to mean <<"" is deprecated. Its use will be fatal in Pe +rl 5.28 at pm_1185726_heredoc_pod.pl line 1. Can't modify scalar in scalar assignment at pm_1185726_heredoc_pod.pl +line 1, near "cut;" pm_1185726_heredoc_pod.pl had compilation errors. my $str = "" = 'cut'; $` [download] Changing the `<<=cut;` to either `<<"=cut";` or `<<'=cut';` fixes the problem. `$ perl -MO=Deparse pm_1185726_heredoc_pod.pl my $str = "\n=head2 Some documentation\n\n"; pm_1185726_heredoc_pod.pl syntax OK` [download] [The POD is rendered fine in all cases with: `perldoc pm_1185726_heredoc_pod.pl`] You can't interpolate variables into the POD text, only the value being assigned to the variable: `$ cat pm_1185726_heredoc_pod.pl our $VERSION = '1.234'; my $str = <<"=cut"; =head2 Some documentation Doco for version: $VERSION =cut print $str;` [download] `$ perldoc pm_1185726_heredoc_pod.pl` [download] Some documentation Doco for version: $VERSION `$ perl -wMstrict pm_1185726_heredoc_pod.pl =head2 Some documentation Doco for version: 1.234` [download] Any sample code in the POD may well contain undeclared variables. These will generate "Global symbol "%s" requires explicit package name" compilation errors (when `strict` is in use) if the heredoc is interpolated. For these two reasons, I'd suggest `<<'=cut';` as the better default option (for code being used in the way shown). — Ken	[reply] [d/l] [select]

Replies are listed 'Best First'.

Re^2: Using PerlPod Creatively
by kcott (Archbishop) on Mar 25, 2017 at 06:32 UTC

G'day Corion,

++ For the technique.

However, there is a problem with that code as written:

$ cat pm_1185726_heredoc_pod.pl
my $str = <<=cut;

=head2 Some documentation

=cut
$
[download]

$ perl -MO=Deparse pm_1185726_heredoc_pod.pl
Use of bare << to mean <<"" is deprecated. Its use will be fatal in Pe
+rl 5.28 at pm_1185726_heredoc_pod.pl line 1.
Can't modify scalar in scalar assignment at pm_1185726_heredoc_pod.pl 
+line 1, near "cut;"
pm_1185726_heredoc_pod.pl had compilation errors.
my $str = "" = 'cut';
$
[download]

Changing the <<=cut; to either <<"=cut"; or <<'=cut'; fixes the problem.

$ perl -MO=Deparse pm_1185726_heredoc_pod.pl
my $str = "\n=head2 Some documentation\n\n";
pm_1185726_heredoc_pod.pl syntax OK
[download]

[The POD is rendered fine in all cases with: perldoc pm_1185726_heredoc_pod.pl]

You can't interpolate variables into the POD text, only the value being assigned to the variable:

$ cat pm_1185726_heredoc_pod.pl
our $VERSION = '1.234';

my $str = <<"=cut";

=head2 Some documentation

Doco for version: $VERSION

=cut

print $str;
[download]

$ perldoc pm_1185726_heredoc_pod.pl
[download]

  Some documentation
    Doco for version: $VERSION

$ perl -wMstrict pm_1185726_heredoc_pod.pl

=head2 Some documentation

Doco for version: 1.234
[download]

Any sample code in the POD may well contain undeclared variables. These will generate "Global symbol "%s" requires explicit package name" compilation errors (when strict is in use) if the heredoc is interpolated.

For these two reasons, I'd suggest <<'=cut'; as the better default option (for code being used in the way shown).

— Ken

[reply]
[d/l]
[select]