From CB conversation, it seems like you want this file to modify itself, generating the pod and methods. That is an evil desire.

Ok, here's an evil thought to go with it.

use Tie::File;
tie my @file, 'Tie::File', $0 or die $!;

splice @file, $begin_lineno, $begin_length, split $/, eval <<B_SUGAR;
# etc.
[download]

Every time I look at this, I see something more that needs doing to make it work. That's a bad sign. Take this a purely conceptual notion.

I don't really want to have the file modify itself. That'd suck because people wouldn't expect it. I'd just like it to expand itself when looked at like a BEGIN block can do for perl code or macros do for lisp code. From other responses in this thread it looks like I'll have to stick with a separate template that just generates the pod and perl. It's not as nice but not difficult either. I just wanted the nicest possible world.

⠤⠤ ⠙⠊⠕⠞⠁⠇⠑⠧⠊

That notion makes source filters look good, doesn't it? Quite an accomplishment, in a wicked kind of way ;-)

After Compline,
Zaxo

No, that won’t work. Generally, you have to generate your POD statically, else it won’t be understood by POD processors. So why not document them all once, instead of repetitively documenting each with the same boilerplate?

=head2 io( OBJ )

=head2 fm( OBJ )

=head2 cv( OBJ )

=head2 hv( OBJ )

=head2 pvlv( OBJ )

=head2 gv( OBJ )

=head2 av( OBJ )

=head2 bm( OBJ )

=head2 pvmg( OBJ )

=head2 pvnv( OBJ )

=head2 pviv( OBJ )

=head2 rv( OBJ )

=head2 nv( OBJ )

=head2 iv( OBJ )

=head2 pv( OBJ )

=head2 sv( OBJ )

Returns a boolean indicating whether OBJ is an instance of the B:: cla
+ss indicated by the method name, and respects any overridden C<-E<gt>
+isa> methods.
[download]

Granted, that’s not entirely DRY. For that, you could try turning your question on its head by parsing your own POD at load time in order to get the list of functions to generate. (I also enjoy Pod::Constants, but it doesn’t fit your use case.)

PS.: your use of eval is unnecessary:

for my $nm ( qw( io fm cv hv pvlv gv av bm pvmg pvnv pviv rv nv iv pv 
+sv ) ) {
    my $nm_pkg = "B::$nm";
    *{ $nm } = sub {
        my $op = shift @_;
        return blessed( $op ) and $op->isa( $nm_pkg );
    }
}
[download]

Makeshifts last the longest.

The eval means my functions have real names, not ANON in the __ANON__ package. I hadn't considered parsing my own pod to get the list of methods to generate but uh... that's possible I guess.

⠤⠤ ⠙⠊⠕⠞⠁⠇⠑⠧⠊

Ah, right.

for my $nm ( qw( io fm cv hv pvlv gv av bm pvmg pvnv pviv rv nv iv pv 
+sv ) ) {
    my $nm_pkg = "B::$nm";
    *{ $nm } = sub {
        local *__ANON__ = $nm;
        my $op = shift @_;
        return blessed( $op ) and $op->isa( $nm_pkg );
    }
}
[download]

As for the POD, think about it: the POD processor is just reading the file. How would it know where to look for what gets seen by the perl compiler at one stage or other when the file is compiled? (Short of solving the halting problem, anyway…) It would have to invoke the compiler on the file and then somehow hook into eval, which isn’t trivial, since CORE::eval has a variable prototype, and it certainly wouldn’t be very safe. So to cover such cases there would have to be some form of templating built into POD itself. And while it might be worthwhile to think about that, that won’t solve your problem.

Makeshifts last the longest.

The thing to remember is that Pod parsers don't execute code. Pod and Perl are just two languages that can live in the same file and each parser just ignores the other language. So you can't use Perl constructs or source filters to affect how Pod parsers see the file.

However, you might be able to take advantage of the fact that perldoc will prefer a .pod file to a .pm file. For an example of how that could work, consider Pod::WikiDoc.

Pod::WikiDoc parses a .pm file containing "wikidoc" Pod format blocks when the distribution tarball is created and creates a matching .pod file with the wikidoc blocks converted to Pod. On installation, the .pod are what perldoc finds and end-users never need to know or care that I used Pod::WikiDoc to write my Pod.

You could do something similar where some template Pod format block gets expanded into a separate .pod file. You just need to customize a Pod parser to pre-process the .pm file, process your templates, and stick the results into a .pod file.

I thought pod parsers executed some code. I remember getting warnings when running perldoc as root that it was allowed to execute code.

⠤⠤ ⠙⠊⠕⠞⠁⠇⠑⠧⠊

I thought pod parsers executed some code.

Well, perldoc, the program, allows you to specify an arbitrary Pod parser to use for formatting. Pod parsers can do anything they want, including running malicious code. So I suspect that was the restriction on running as root.

But I don't think that perlpodspec says anything about code execution -- that was my point about Pod and code being two separate languages.

-xdg

Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.