Author: kjs
Date: Sun Apr 1 10:25:40 2007
New Revision: 17930
Modified:
trunk/compilers/pirc/doc/design.pod
Log:
compilers/pirc:
* cleaned up doc/design.pod
* added small section on pirc's vtables.
Modified: trunk/compilers/pirc/doc/design.pod
==============================================================================
--- trunk/compilers/pirc/doc/design.pod (original)
+++ trunk/compilers/pirc/doc/design.pod Sun Apr 1 10:25:40 2007
@@ -8,12 +8,19 @@
=head1 OVERVIEW
-PIRC currently consists of only a PIR parser, together with a lexer.
+PIRC currently consists of a PIR parser, together with a lexer. It also has
+the beginning of semantic actions in the parser. Through the use of a vtable,
+several back-ends can be implemented, leaving the parser untouched.
+Documentation of the lexer and the parser can be generated by running:
+
+ pod2html src/pirlexer.c > doc/pirlexer.html
+ pod2html src/pirparser.c > doc/pirparser.html
+
+This document will only provide a high-level overview.
-=head1 THE LEXER
-=head2 OVERVIEW
+=head1 THE LEXER
The lexer is defined in C<pirlexer.c>. The header file lists all tokens that
may be returned by the lexer.
@@ -22,78 +29,10 @@
the individual words, or I<tokens>. A buffer is much faster than using
C<getc()>
for each character, as I/O is relatively slow.
-The lexer has three functions that may be invoked to receive the next token:
-
-=over 4
-
-=item C<token next_token()>
-
-C<next_token()> is used for the 'ordinary' case; it reads the next token from
-the current file.
-
-=item C<token read_heredoc(char *label)>
-
-C<read_heredoc()> reads all text up to the specified label. This label B<must>
-be at the start of a line. It returns the T_HEREDOC_STRING token on success, or
-T_EOF when the end of the file (buffer) is encountered.
-
-=item C<token read_macro()>
-
-C<read_macro()> is used to read a macro body. It reads up to the C<.endm> word,
-and then returns the T_ENDM token, which can then be matched by the parser.
-
-=back
-
-=head2 IMPLEMENTATION
-
-The lexer is represented by a structure called C<lexer_state>. It is
predeclared
-in the header file, and defined in the source file. This is to prevent direct
-access to its members.
-
-The structure looks like this:
-
- typedef struct lexer_state {
- struct file_buffer *curfile;
- char *token_chars;
- char *charptr;
-
- } lexer_state;
-
-It has three pointers: the first one is a pointer to a file_buffer structure,
which
-will be discussed shortly. The second is a pointer to the current token's
characters.
-This is a buffer in which the characters for the current token are stored.
-The field C<charptr> acts like an index to add and delete characters from
C<token_chars>.
-
-As mentioned, the lexer reads the source file and returns tokens. The source
file is
-represented by another structure, called C<file_buffer>. It looks like this:
-
- typedef struct file_buffer {
- char *filename;
- char *buffer;
- char *curchar;
- unsigned filesize;
- unsigned int line;
- unsigned short linepos;
- char lastchar;
- struct file_buffer *prevbuffer;
-
- } file_buffer;
-
-The first field C<filename> holds the name of the file that is being scanned.
-The second field C<buffer> is a pointer to the contents of the file. The field
-C<curchar> points into this buffer to the current position, and can be
considered
-the I<cursor>.
-Then, C<filesize> contains the length of the file; C<line> keeps track of what
line
-is being processed; linepos keeps track of the number of characters since the
last
-newline character (used for error messages). The field C<lastchar> stores the
-last character that is returned. This is used to check whether we're at the
beginning
-of a newline (which is necessary to parse heredoc delimiters).
=head1 THE PARSER
-=head2 OVERVIEW
-
The parser is defined in C<pirparser.c>. The header file only predeclares the
C<parser_state> structure, but its definition is written in the C file, to hide
the implementation details from other files. Access to specific fields is done
@@ -107,24 +46,16 @@
request these through C<find_keyword()>.
-=head2 IMPLEMENTATION
+=head1 SEMANTIC ACTIONS
+
+The parser calls at a number of places C<emit> functions. These are I<hooks> to
+which a function can be hooked, that will be called when the parser calls that
+function. This is implemented using vtables.
-The parser is represented by a structure called C<parser_state>. Its layout is
-shown below:
+Currently, there are two back-end targets: Parrot Abstract Syntax Tree (PAST),
+and simply PIR.
- typedef struct parser_state {
- struct lexer_state *lexer;
- token curtoken;
- char *heredoc_ids[10];
- int heredoc_index;
- unsigned parse_errors;
-
- } parser_state;
-
-It consists of the following fields: a pointer to a lexer_state object; the
current
-token as returned by the lexer; a list to store heredoc identifiers, which is
used
-when parsing heredocs as subroutine arguments; an index for this list; and
finally a
-counter to keep track of parse errors.
+See src/pirvtable.{c,h} for details.
=head1 AUTHOR
