## $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 available.

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 http://www.python.org/download/.

You will also need to install a copy of the Parrot Virtual Machine available from http://www.parrot.org/download.

=head2 Building and invoking Pynie

To obtain the latest version of Pynie:

$ svn checkout http://pynie.googlecode.com/svn/trunk pynie

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

$ cd pynie $ python setup.py build

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

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

$ ./pynie foo.py

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 setup.py test

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

$ ./pynie --target=parse foo.py

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" compiler.

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

The F<Grammar/Grammar.pg> 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 <https://launchpad.net/pynie/+filebug>.


## vim: expandtab sw=4