Obtaining the Pod of a module without explicitly exporting it

129 views Asked by At

The documentation in Perl 6 programs, using the Pod 6 DSL, are actually parsed as part of the code; this makes that documentation available, inside the program, as the $=pod variable. However, I'd like to have access to that variable in order to process it from, say, tests. In this example I wrote for the Perl 6 Advent Calendar it's simply exported as a class (grammar, in this case) variable:

our $pod = $=pod[0];

I can then use it this way:

use Data::Dump;

use MONKEY-SEE-NO-EVAL;

sub MAIN( $module  ) {
    try require ::($module);
    say Dump( $::($module)::pod, :max-recursion(2) );

}

This works when called with the name of the class and the correct path; but it still needs the explicit export of the variable.

I have seen in some code that precomp stores can be used (sorry, no good single-source to explain these ones) for the same thing. Eventually, this line

 return nqp::atkey($handle.unit,'$=pod')[0];

Does the trick, accessing the Pod of a module that is represented by the precomp store and contained in $handle.unit. The thing is that this is actually lower level, using the nqp::atkey operator of NQP, not quite perl.

There are many ways of doing this, so I can think of two different possible questions. 1. Is there a way to access via a FQN (preceded by ::) the Pod of that required or used unit? 2. Do we have access to the precomp handle of a required or used unit so that we can call nqp::atkey directly?

1

There are 1 answers

0
dmaestro12 On

I used this technique (finding simpler ways to do it) to create Module::Pod (soon to be published). See my answer: https://stackoverflow.com/a/57247392/332359