## $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.
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 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"
To invoke pynie on a Python program from a shell prompt, use:
$ ./pynie foo.py
To run interactively, entering single-line statements:
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",
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/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:
$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