Specify an implementation neutral method for extracting pod

[finanalyst]

Any POD6 stanzas in the current CompUnit is available as $=pod.
Accessing the POD6 in another file, eg., a documentation file in a directory, is not specified. Consequently, extracting the POD6 array relies on implementation details, such as the Precompilation modules. …

All the Raku documentation is in pod6 files, eg., github.com/Raku/doc/doc/Language/containers.pod6 (eventually the extension will be '.rakudoc').

In order to access the information, the POD6 has to be compiled (because POD6 is a part of a Raku program), and then the pod is extracted from the precompilation store. This requires finding the id of the file in the store, which can be turned into a handle, which can then be accessed using nqp::atkey to get the pod array.

This process is highly implementation dependent, and uses subclasses that could be changed.

Suppose a syntax is agreed, for example, my @pod = EVALDOC "filename.rakudoc" (by analogy with `EVALFILE "some-program.raku"), then the mechanism by which the pod is extracted, eg from a Precompilation Store, can be hidden from the user.

[raiph]

Just an idea off the top of my head. It might be a bad one:

EVALFILE :doc($module), $file

behaves in a manner consistent with:

raku --doc(MODULE)

[finanalyst]

raku --doc(MODULE) program.raku is not the same as I was proposing.

It takes program.raku and renders the POD6 in that program with the renderer specified as MODULE (actually, it uses Pod::To::MODULE).

So raku --doc program.raku is the same as accessing $=pod inside program.raku.

EVALFILE :doc, $file maybe better because it does not increase the number of function names. However EVALFILE $file evaluates $file as a Raku program and returns the value of the final statement of the program. So the :doc changes the return value.

The suggestion EVALDOC $file returns the pod tree that results from evaluating $file.

[FCO]

Could it ignore any possible code (not pod6) inside the file?

[raiph]

Aiui:

Could it ignore any possible code (not pod6) inside the file?

Yes, but there will be associated (potentially major) risks.

A minor one is that it might mean a source file fails to compile (and the doc would not be generated).

A major one is that it might be a security hole, leading to a source file that would ordinarily just compile in a correct or at least benign way instead being malign in some respect.

(This is because the nature of Raku, like Perl, is that to correctly parse it you must execute a variety of constructs as you go during the compilation phase. These constructs have statically unknowable consequences in terms of side effects. These side effects include altering Raku's syntax, which alters the parsing of code after such a side effect has occurred. Which alteration can alter the meaning of code from one thing to another depending on whether you process or skip some earlier code.)

The biggest risk would be trashing Raku's reputation. Someone's system is hosed because they tried to pull up some doc.

We run that risk anyway due to Raku's design, but introducing deliberate ignoring of code amplifies that risk and the consequences of falling afoul of that risk.

[raiph]

EVALFILE $file evaluates $file as a Raku program

So does this new feature, right?

and returns the value of the final statement of the program.

Yes. That's the difference.

One can imagine other reasons to EVALFILE such as running the type checker (-c, so perhaps EVALFILE :c, $file).

So the :doc changes the return value.

Yes. If there were ever an EVALFILE :c, $file, then presumably that would also change the return value.

More generally, I was thinking EVALFILE might be a principled way to selectively introduce access to some things that Rakudo does, with one principle being to use a named argument that matches the Rakudo command line argument to keep things clean and relatively easy to remember and document.

Maybe EVALFILE :M<foo> $file to evaluate $file after loading module M? And so on.

Anyhoo, 'tis just an idea.

[finanalyst]

My original suggestion of EVALDOC is not so different from EVALFILE :doc, and personally I think it is a consistent extension to have EVALFILE :c or EVALFILE :M(module) file.

@FCO

Could it ignore any possible code (not pod6) inside the file?

If you write a raku program with a whole load of embedded Pod::Blocks, and then inspect a variable called $=pod (it could be eg. $=documention-in-this-file), you will see that it is an array of Pod::Blocks. This data structure is created by the Raku compiler.

The specification of POD6 refers to the ambient and to POD6. The ambient is the code part of a program. The ambient is not included in the Pod::Block array. However, it is possible to have sections of code inside the POD6 using either the FormattingCode C<> or a code block bracketted by =begin code and =end code.

So it is possible to have code inside the POD6, but unless you are playing significant compiler tricks, this code is not the ambient code written to be evaluated as a program.

My suggestion is to have a simple way implementation-neutral to get hold of the POD array associated with another program or module, or just a documentation file in a directory.