## $Id: README 17096 2007-02-20 20:20:48Z paultcochrane $

=head1 Perl 6 parser/compiler

This is a Perl 6 parser/compiler, an early version (no version numbers
yet).  It's still very early, only simple expressions and functions are
available.  If you're in a hurry to write "real Perl 6" programs,
you might try looking at Pugs -- http://www.pugscode.org.  Or, you
can send patches and contributions to the one being built here!

However, even though this is not a complete compiler yet, you can
still see how Perl 6 programs are parsed, help us create test
cases, and extend/improve the grammar and runtime to cover more
of Perl 6.  Here's how the system currently works:

=head2 Compiling

The perl6 parser/compiler lives in the perl6.pbc file.
To create this file, simply issue the command

  $ make

To invoke perl6 from a shell prompt on a (Perl 6)
input file named "foo.p6", use:

  $ parrot perl6.pbc foo.p6

To run interactively, entering single-line statements:

  $ parrot perl6.pbc

To display the parse tree, add the "--target=parse" option:

  $ parrot perl6.pbc --target=parse foo.p6

Or, to display the abstract syntax tree, the opcode syntax tree,
or the generated PIR code, use "--target=PAST", "--target=POST",
or "--target=PIR".

To get a dump of the parser's operator precedence table,
use --dump-optable:

  $ parrot perl6.pbc --dump-optable

=head2 Files

The "top" file for the parser is F<perl6.pir> which is used to
create the F<perl6.pbc> file.  It initializes the overall
parsing system and registers the parser as a Parrot "Perl6" compiler.

The other files needed for the compiler are in the F<src/> subdirectory.

The F<src/grammar_rules.pg> file defines the "top-down" grammar used
for large Perl 6 program structures, defined using rules in
Perl 6 rules syntax.  The F<src/grammar_optok.pg> file defines
the operator tokens used for expression parsing with PGE's
operator-precedence parser.   The tokens in src/grammar_optok.pge
are defined using a pseudo-Perl6 syntax.  PGE's "pgc.pir"
compiler is then used to compile the two grammar files into
F<src/grammar_gen.pir>, which is included by F<perl6.pir>.
(See Synopsis 5 for more details on Perl 6 rules syntax,
and F<compilers/pge/> for more details about PGE.)

The F<src/parse.pir> file defines a few special-purpose
rules needed to support parsing that are better written
directly in PIR instead of using the rules or token syntax.
Currently this file defines the C<< <expression> >> rule,
which just calls into the operator precedence parser.

The file F<src/pge2past.tg> is a tree grammar that specifies
how to convert the parse tree into the abstract syntax tree (PAST),
and F<src/past2post.tg> generates POST from PAST.  

The F<src/main.pir> file controls what happens when the perl6.pbc
file is invoked directly from parrot (as opposed to being
loaded via the load_bytecode op).

The PIR files in F<src/> are included as part of compiling
F<perl6.pir> to produce F<perl6.pbc>.

The F<perl6.pbc> file can also be used to compile Perl 6 code
from PIR:

    load_bytecode "perl6.pbc"
    $S0 = 'say "hello world"'            # source code to compile
    $P0 = compreg("Perl6")               # obtain the compiler
    $P1 = $P0($S0)                       # compile source code
    $P1()                                # execute

One can also provide the "target" option to the compiler:

    $P1 = $P0($S0, 'target'=>'parse')    # obtain parse tree
    $P1 = $P0($S0, 'target'=>'PAST')     # get AST
    $P1 = $P0($S0, 'target'=>'POST')     # get OST
    $P1 = $P0($S0, 'target'=>'PIR')      # get PIR

=head1 AUTHOR

Patrick Michaud (pmichaud@pobox.com) is the author and maintainer.
Patches and suggestions should be sent to the Perl 6 compiler list
(perl6-compiler@perl.org).

=cut

## vim: expandtab sw=4
