Joel's Blog

Adventures in Perl 6, part I

Pixelart Camelia

I did get the opportunity to work on and with Perl 6 during this year’s Google Summer of Code!

My project is the general improvement of the p6doc program.

The purpose of p6doc is to search and read documentation using the Perl 6 pod markup language, located inside .pod6 files, from the command line:

$ p6doc IO::Spec
$ p6doc Map.new

The original state of p6doc

First, let’s have a quick look at the original state of p6doc, as of May 2019:

p6doc is a program as part of the official Perl 6 standard Documentation perl6/doc. The two main features of p6doc are the search for classes/types and the routines/methods associated with them, and the search of routines without further specification inside the standard documentation.

The way it works at it’s core is via shell to run perl6 --doc on a .pod6 file through the system shell:

    my $doc-command-str = $*EXECUTABLE-NAME;
    if $section.defined {
        %*ENV<PERL6_POD_HEADING> = $section;
        my $i = findbin() ~ '../lib';
        $doc-command-str ~= " -I$i --doc=SectionFilter"
    } else {
        $doc-command-str ~= " --doc"
    }
    $doc-command-str ~= " $path ";
    if $package.DEFINITE {
        my $cs = ";";
        $cs = "&" if $*DISTRO.is-win;
        $package ~~ s/"Type::"//;
        $doc-command-str = "echo \"In {$package}\"$cs" ~ $doc-command-str;
    }
    $doc-command-str ~= " | $pager" if $pager;
    say "launching '$doc-command-str'" if DEBUG;
    shell $doc-command-str;

To achieve the search for single routines, it builds an index file with one entry per routine name and subentries to show which types/classes contain a routine (or method) with that name. POD6 files are inspected using regular expressions to retrieve the required information from them. This index file is saved as a raw Perl 6 data structure and to load it, EVAL is used which reads it as Perl 6 code.

 my %data = EVALFILE INDEX;

The code is also not documented, tested, basically uncommented and has a few bugs (e.g. not able to find certain entries in the documentation).

The story thus far

I began by extracting p6doc, as well as required parts to get it running, from the perl6/doc repository, split the code into it’s own module P6doc, added tests, and performed a bunch of refactoring to make the code a bit easier to follow and work with. The way the index file is built was changed to use json instead of raw Perl 6, removing the need for EVAL.

After that came the work to improve the way p6doc actually works behind the curtains, and I rewrote the backend almost from scratch, which now leverages benefits of the Perl6::Documentable module, shoutouts here to Antonio, who is a fellow GSoC student right now working on improving Perl6::Documentable.

A new p6doc. So what’s new?

Let’s distill it a bit:

What’s next?

There is still work to do, the next goal is however the release of the first version, 0.1.0. With this version it is my goal to have it in an installable and useable state for users, to search by type, and search by single routine.

Major parts missing for 0.1.0:

Follow me

I will continue to post weekly updates here to talk a bit more in detail about my progress and, of course, my struggles.

If you want to follow the development, you can do so here. Should you have any direct questions, you find me as noisegul on IRC Freenode.