Doc Mirages

Source: Dev.to

Introduction

This is part seven in the Cases of UPPER series, describing the Raku syntax elements that are completely in UPPERCASE. It discusses the final set of (non‑)existing phasers in the Raku Programming Language.

The --doc command‑line argument

--doc         extract documentation and print it as text
--doc=module  use Pod::To::[module] to render inline documentation

When --doc is used, the source of the program is processed as documentation and rendered in the requested form. Internally Raku loads the Pod::To::xxx module (defaulting to Text when no module is given) and installs an INIT phaser that does roughly:

INIT {
    say Pod::To::xxx.render($=pod);
    exit;
}

The Pod::To::Text module is shipped with the Rakudo distribution, while other renderers such as Pod::To::HTML, Pod::To::PDF, and Pod::To::Markdown must be installed from the ecosystem (e.g. zef install Pod::To::Markdown).

DOC phasers

There are three DOC phasers, each added only when --doc is specified:

Conceptually, a DOC phaser works like a conditional statement prefix:

# pseudo‑code for DOC BEGIN
if --doc is set {
    BEGIN …;
}

If --doc is not specified, the phasers are not executed. For example:

$ raku -e 'DOC BEGIN say "begin"; DOC CHECK say "check"; DOC INIT say "init"'
# (no output)

$ raku --doc -e 'DOC BEGIN say "begin"; DOC CHECK say "check"; DOC INIT say "init"'
begin
check
init

Even when --doc is absent, the code inside a DOC phaser must be syntactically valid:

$ raku -e 'DOC BEGIN +-+'
===SORRY!=== Error while compiling -e
Prefix + requires an argument, but no valid term found.
Did you mean + to be an opening bracket for a declarator block?
at -e:1

Practical use

The only widely useful application of DOC phasers is with the Pod::EOD module, which appends declarator documentation to the end of the generated POD ($=pod). No other correct usage has been identified.

TEMP phaser (a mirage)

The TEMP phaser was mentioned in early design documents (S06 – Temporization) but has never been implemented. The functionality that TEMP would have provided is already covered by the temp and let prefix operators, together with the KEEP and UNDO phasers.

The syntax for the TEMP phaser does exist:

$ raku -e 'TEMP say "temp"; say "alive";'
alive

However, it performs no action, and its support is expected to be removed.

COMPOSE phaser (another mirage)

The COMPOSE phaser appears only in the old S04 – Phasers design notes and has never been implemented. Its intended behavior—executing code when a role or class is composed—can already be achieved by placing code in the mainline of a role. That code runs each time the role is consumed at compile time.

role A {
    say "composing $?CLASS.^name()";
}
class B does A { }
class C does A { }
BEGIN say "begin";

Output:

composing B
composing C
begin

The compile‑time variable ?$CLASS holds the type object of the class being composed. As of August 2020, it became clear that a dedicated COMPOSE phaser is unnecessary.

Summary

• The DOC phasers (DOC BEGIN, DOC CHECK, DOC INIT) are activated only with --doc; otherwise they are no‑ops but must contain valid Raku code. Their practical use is limited to modules like Pod::EOD.
• The TEMP phaser was never implemented; its intended capabilities are provided by temp, let, KEEP, and UNDO.
• The COMPOSE phaser was also never implemented; the mainline of a role already offers the same functionality.

This concludes the seventh episode of Cases of UPPER and the overview of all phasers in Raku. The next topic will cover uppercase methods that users can provide to tweak language behaviour. Stay tuned!