# The following was supposedly scribed by # Randy W. Sims # on Thursday 24 June 2004 10:40 pm:
You'll want to subclass Pod::Text, override the proper method to add a new escape sequence (say $<variable_name>), then maybe override the constructor to take a hash with the values for the variables or possibly something more elaborate like evaling the variable name in the caller's context.
Yes. The trouble is that I don't want to have to manually re-generate the pods in any way, so I'll need a modified perldoc. (If you haven't chastised me for it before, I'm the guy who makes changes to the code directly on the production system:)
My concept is that the script does something like 'use Pod::Dynamic' and builds some pod sections (or defines some variables) by running up to some point when $Pod::Dynamic::pod_mode is true. This means that 'dynperldoc' can simply do() the file and have some variables defined for use in generating the fully-formed pod.
So, if the variables are changed to some other defaults, both 'dynperldoc <script>' and '<script> --help' show the same values without having to manually regenerate anything.
Integration with perldoc is something you'll have to run by Sean and P5P. Basically, this would require a change to the pod spec or at least a mechanism for arbitrarily extending it. I would avoid a personalized perldoc as this is problematic for all the reasons forked software is problematic. (I speak from experience, having created several customized spin-offs for private use.)
I've done similary on several occasions and it is fairly trivial. If you have trouble, I can probably dig up an example.
I may take you up on that. CPAN's results for 'dynamic pod' are depressing.
Below is an example that shows how you might go about creating a new pod escape sequence. Note that if you run the below script through perldoc, it will ignore the unknow sequence, printing nothing.
Another idea is to use a source filter. I wrote a small demo of that technique (using Filter::Simple), but I couldn't get it to filter within the POD section even though it is documented to do so with the correct arguments. It would still have the same problem as the above method though.
Andy mentioned Getopt::Declare. I've briefly taken a look at it a few times, and I did so again when he mentioned it. I guess I never really "got it". It doesn't seem to solve the problem, but since I've been thing about tighter perl/pod integration, it occurs to me that a natural extension of Getopt::Decare's functionality would be to have it get its specification from pod, so that something like the following would serve for the spec to getopt:
=head1 OPTIONS
=over
=item B<--option> <arg>
an option with a required argument
=item B<-v>
verbose output
=item B<--verbose>
[ditto]
=back
__END__
And, here is the example for extending POD
#!/usr/bin/perl
package Pod::X;
use strict;
use Pod::Text; our @ISA = qw(Pod::Text);
our $VERSION = 1.0;
sub interior_sequence {
my ($parser, $seq_command, $seq_argument) = @_; # Can create custom sequences using matching [A-Z]<...>
if ( $seq_command eq 'X' ) { # move up thru stack until we get the name of the calling package
my $stack_frame = 0;
++$stack_frame until (caller($stack_frame) !~ /^Pod::/);
my $calling_pkg = caller($stack_frame);# evaluate the variable as a package variable of the calling package
return eval "\$${calling_pkg}::${seq_argument}";
} else { # otherwise not a custom sequence, so delegate to SUPER
return $parser->SUPER::interior_sequence($seq_command, $seq_argument);
}
}1;
package main;
use strict; use warnings;
our $VERSION = 0.01;
my $parser = Pod::X->new(); $parser->parse_from_file($0);
=head1 NAME
pox - Pod eXtension Test
=head1 VERSION
pox X<VERSION>
__END__
Regards, Randy.
