pynie / README

## $Id: README 31241 2008-09-18 20:11:33Z pmichaud $

=head1 Pynie - A Python compiler for Parrot

This is a Pynie parser/compiler, an early version (no version numbers
yet).  It's still very early, only simple expressions and functions are

However, even though this is not a complete compiler yet, you can
still see how programs are parsed, help us create test cases, and
extend/improve the grammar and runtime to cover more of Python.

=head2 Prerequisites

To build Pynie you will need to install Python 2.5 or greater from 

You will also need to install a copy of the Parrot Virtual Machine 
available from

=head2 Building and invoking Pynie

To obtain the latest version of Pynie:

  $ svn checkout pynie

Once you have checked out a copy of pynie, build it as follows:

  $ cd pynie
  $ python build

This will create a "pynie.pbc" parrot bytecode executable in the
current directory.   Pynie doesn't currently have a "install"

To invoke pynie on a Python program from a shell prompt, use:

  $ ./pynie

To run interactively, entering single-line statements:

  $ ./pynie

Note that pynie's interactive mode is not yet up to spec
with Python's interactive mode (it doesn't handle blocks yet).

To run pynie's test suite:

  $ python test

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

  $ ./pynie --target=parse

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

=head2 Files

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

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

The F<Grammar/> file defines the tokens, rules,
and protos for Python.  Much of this has been taken from
the "Python Language Reference Manual (release 2.3)" by
Guido van Rossum (Fred L. Drake, Jr., editor).  PGE's "Perl6Grammar.pbc"
compiler is then used to compile the two grammar files into
F<include/gen_grammar.pir>, which is included by F<pynie.pir>.
(See Synopsis 5 for more details on Perl 6 rules syntax,
and F<compilers/pge/> for more details about PGE.)

The F<src/parser/indent.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.

The file F<Grammar/Actions.nqp> defines the actions that are
invoked during the parse. These actions construct the Parrot AST
(PAST) nodes. At the end of the parse, the whole PAST is constructed
and handed off to the next compilation phases (PAST->POST->PIR)

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

The F<pynie.pbc> file can also be used to compile Python code
from within PIR:

    load_bytecode 'pynie.pbc'
    $S0 = 'print "hello world"'          # source code to compile
    $P0 = compreg('Pynie')               # 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 Submitting Bugs/Patches

Patches/bugs/suggestions can be sent to


## vim: expandtab sw=4