=head1 NAME

README.pod - This is the readme file for PIRC, a PIR Compiler written in C.

=head1 DESCRIPTION

This is the readme file for PIRC, a PIR Compiler written in C.

=head1 INTRODUCTION

This is an attempt to implement Parrot Intermediate Representation (PIR)
using a top-down approach. This is still in its early phases, and only
the parser is being worked on.

As the current implementation of PIR (IMCC) is a bit messy, this is
an attempt to write a clean implementation to see what constructs should
be allowed, and which should be forbidden. It's also a nice experiment
to see whether a top-down parser has any advantages over a YACC implementation.
(For instance, it's much smaller).

This implementation is as complete as I can currently oversee. Of course,
things will be fixed as I encounter them.

More importantly, ops cannot be parsed yet, because the distinction between
an op and a plain identifiers can only be decided during runtime. This is
because Parrot allows for runtime loading of op-libraries. Currently,
I hardcoded the "print" op, so you can compile:

 .sub main :main
   print "Hello World"
 .end

On the other hand, most of the "sugar" that PIR adds to Parrot assembly
syntax has been implemented, and can be parsed successfully.

For more documentation, please run:

 make docs

This will generate the documentation in HTML format. The documentation of
pirparser.c contains the grammar that is accepted by PIRC. The documentation
of pirlexer.c contains the lexical specifiction as accepted by PIRC. See
the C<doc> directory for documentation, or run C<perldoc> on the source files.


=head1 FEATURES

Some highlights of PIRC:

=over 4

=item *

PIRC allows for multiple heredoc arguments:

 .sub main
   foo(<<'A, <<'B', <<'C', 10, "hello", <<'D')
 This is arugment A
 A
 This is argument B
 B
 This is argument C
 C
 This is argument D
 D

 .end

Unlike IMCC, this is accepted by PIRC.

=item *

A clean interface to the compiler back-end. The interface to the back-end of PIRC
is clean, and separates the parser completely from the back-end. The back-end does
not get to see details of the parser, unless these details are passed as parameters.
See the file C<doc/design.pod> for details.

=item *

PIRC is a top-down recursive descent parser. Although it is handwritten, the source
code is quite readable and simple, allowing for easy adjustments. While changing
IMCC's yacc input file may result in shift/reduce conflicts easily, changing and adding
syntax to PIRC is better isolated to a single point in the parser.

=item *

It correctly handles C<.include> directives.

=item *

Macro definitions are really parsed, not merely slurped. This means that errors in the
macro definition are found immediately, and not only when expanding a macro definition.

=item *

PIRC shows input context when reporting an error. This means that the last I<N> characters
are printed to the screen (where I<N> is #define'd in the source, currently set to 30).

=back


=head1 ISSUES

=over 4

=item *

Macros are not expanded at this point, but can be parsed.

=item *

Parrot ops cannot be parsed, except for C<print> and C<null>, as C<null> is
a PIR keyword (used in the C<if> and C<unless> statements).

=back

Comments, improvements etc. are most welcome and may be sent to the author.


=head1 REFERENCES

Run C<make docs> and see the generated files in the C<doc> directory.


=head1 AUTHOR

klaas-Jan stol <parrotcode at gmail dot com>

=cut

