develooper Front page | perl.perl6.language | Postings from August 2009

S26 - The Next Generation

Thread Next
Damian Conway
August 16, 2009 13:26
S26 - The Next Generation
Message ID:
It's Sunday evening and, as promised, here's the new draft of S26.

It's not yet committed, as there will (no doubt) be much discussion
first. I apologize in advance: I am still travelling on my annual world
tour, so my ability to participate in this discussion will be limited
and erratic.

I'm posting the full synopsis, as there are so many changes that the
diff is not significantly shorter than the complete document (and *much*
harder to make sense of).

For those who are only interested in what's new, search for the following:

    =head2 General syntactic structure
    =head3 Declarator blocks
    =begin item :term<C<:margin>>
    =head3 Alias placements
    =head2 Aliases

Executive summary:

   * Pod is now just a set of specialized forms of Perl 6 comment

   * Hence it must always parsed using full Perl 6 grammar: perl6 -doc

   * The DOC statement prefix constrains any block to which it is applied
     (including BEGIN, CHECK, INIT and similar) to run only if -doc is
     specified on the commandline

   * You can tell if you're running under -doc by checking $?DOC

   * A final (automatically supplied) DOC INIT {...} block simply
     converts entire $=POD object to text

   * But you can pre-empt this default behaviour by putting something
     like this directly in your code (or in a module that you load from
     the commandline):

        DOC INIT { translate_pod_yourself(); exit; }

   * Or you can augment this default behaviour with other
(non-terminal) DOC statements:

        DOC use My::Extra::Pod::Features;

   * So developers can add their own documentation mechanisms simply by
     loading a module that installs a suitable DOC block to override or
     extend the documentation default behaviour, using code written in
     Perl that accesses $=POD and/or the .WHY and .WHEREFORE methods of
     introspected declarators (see below)

   * Pod directives all start with either: ^^ \s* =   (for normal Pod blocks)
                                       or: #=         (for the new Pod

   * This means Pod can be indented; the = is no longer tied to the
     first column. The indentation preceding the opening = (using the
     ($?TABSTOP // 8) rule, as for heredocs) now specifies the zeroth
     column of the Pod block.

   * In addition to delimited, paragraphed, and abbreviated Pod blocks,
     documentation can now be specified in a fourth form:

       my $declared_thing;   #= Pod here until end of line

       sub declared_thing () {   #=[ Pod here
                                     until matching
                                     closing bracket

   * This new declarator block form is special. During source code parsing,
     normal Pod blocks are simply appended into an array attribute of
     surrounding Comment object in the AST (which is just $=POD, at the
     top level). However declarator blocks are *also* appended to the
     .WHY attribute of the declarator at the start of the most recent
     (or immediately following) line.

  * Hence, they can be used to document code directly, which
    documentation can then be pulled out by introspecting either
    $=POD or the declarators themselves. Documented declarators
    look like this:

       #= Base class for comms necromancy hierarchy
       class Magic::Necrotelecomnicon {
           has $.elemental;  #= Source of all power
           has $!true_name;  #  Source of all self-protection (not documented)

           method cast(Spell $s)
           #= Initiate a specified spell normally

           #= Initiate a specified spell abnormally
           method kast(Spell $s) {
               do_raw_magic($s, :alternative);

   * In other words, Declarator blocks are assumed to document the
     declarator they immediately follow (i.e. without intervening blank
     lines), or if they don't immediately follow a declarator, to
     document the declarator they precede. This is intended to reflect
     common commenting/documenting practices.

   * A Pod object representing each such declarator block is still
     appended to the surrounding subelement of $=POD. But these Pod
     objects have a .WHEREFORE() method that returns the object or
     metaobject to which they are attached. When the default DOC INIT
     block converts these to text, it includes information about the
     declarator as well. For instance, the above example might produce
     something like:

           Name:  Magic::Necrotelecomnicon:
           Desc:  Base class for comms necromancy hierarchy

                .elemental       : Source of all power

                .cast(Spell $s)  : Initiate a specified spell normally
                .kast(Spell $s)  : Initiate a specified spell abnormally

    The exact translation used is implementation dependent or (more
    likely) will be explicitly specified by the documenter, such as:

        DOC BEGIN { use Pod6::Markovian }


I've tried hard to synthesize into a single coherent solution the many
good (but often mutually incompatible) suggestions and feature-requests
that the community has contributed over the past two years. Hopefully
this is something close to the final draft...and something that every
stakeholder and faction in this long discussion can dislike equally. ;-)

Of course, all comments, suggestions, and patches are most welcome.


PS: As usual, my free-time will self-destruct in 5...4...3...2...1...
    but we'll try hard to commit this as soon as we have general
    agreement (and, of course, the agreement of our General).

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About