GSoC – The podparser branch has landed

Just a few minutes ago, with a total count of 28 files changed, 1627 insertions and 41 deletions, the podparser branch in which I’ve been doing my GSoC work has been merged into nom, the current development branch of Rakudo and the soon-to-be master. So, what do we get?

  • Pod is now parsed, not ignored. The whole parse tree is available in runtime in the $=POD variable
  • A basic support for documenting classes and subroutines with #= comments, and the .WHY method on each object returning the attached documentation
  • A –doc switch, a not-really-replacement for perldoc
  • A simple Pod::To::Text output generator
  • and more, of course :)
So, how does it look like in action?
$=POD
All the Pod we have written in our code is now available in the $=POD variable. Example?
=begin pod
Some documentation
=end pod

say $=POD[0].content[0].content;
Results in

Some documentation

That’s not very useful per se, so how about this one:

=begin pod

=head1 NAME

A basic pod document

=head2 Running Perl programs

To run a Perl program from the Unix command line:

    perl progname.pl

=head2 Things on my desk

There are the following things on my desk right now:

=item A cup of tea
=item A couple of pens
=item A stereo
=item A couple of books
=item A laptop, obviously

=end pod

DOC INIT {
    use Pod::To::Text;
    say pod2text($=POD);
    exit;
}

say "I'm just a simple program";

Now what’s the DOC INIT thing? Let’s see. How about we run the above program:

$ perl6 foo.pl
I'm just a simple program

No suprises. Let’s introduce the –doc switch then:

$ perl6 --doc foo.pl
NAME

A basic pod document

  Running Perl programs

To run a Perl program from the Unix command line:

    perl progname.pl

  Things on my desk

There are the following things on my desk right now:

 * A cup of tea
 * A couple of pens
 * A stereo
 * A couple of books
 * A laptop, obviously

That’s right. The DOC blocks are executed only when the –doc command line option has been given. At the moment you have to write them yourself, but maybe even in the nearest few days there will be a default DOC INIT block doing What You mean all by itself. There we go, a perldoc-alike built-in :)

WHY

That’s probably the biggest killer feature in the whole project. Although it’s not yet fully implemented in Rakudo (suprise segfaults here and there, don’t worry, they’re not permanent :)), it looks pretty much like this:

#= our zebra class
class Zebra {
...
}

say Zebra.WHY # prints: "our zebra class"

Yes yes, a documentation inspection in runtime. See the potential?

# what was that sub again?
&sort.WHY.say # get the documentation for the sort() builtin

That opens a way for lots of awesome userspace tools too.

So, what’s still not quite there?

  • .WHY (some cases)
  • Formatting Codes (C<code>, B<bold> etc)
  • DOC use (that can be written as DOC INIT { use … } for now)
  • Default DOC INIT (as mentioned above)
  • A Pod::Parser as a standalone module
With that done, my GSoC project will be finished, and I’ll hopefully have time to hit some things I was planning to poke in some spare time, for example:
  • HTML output generator
  • Extending the parser so Synopse 26 can be fully parsed
  • Other fancy userspace tools; I don’t want to spoil the suprise :)

What can I say? Pull it, compile it, play with it, report bugs and have the appopriate amount of fun :)

About these ads


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.