Author: kjs
Date: Sun Apr 8 02:24:54 2007
New Revision: 18038
Modified:
trunk/compilers/pirc/README.pod
trunk/compilers/pirc/doc/design.pod
trunk/compilers/pirc/src/pastout.c
trunk/compilers/pirc/src/pirlexer.c
trunk/config/gen/makefiles/pirc.in
Log:
compilers/pirc:
* added more documentation to readme file
* added all source files to docs target (so foreach source file a html file is
generated)
* added documentation to lexer.
Modified: trunk/compilers/pirc/README.pod
==============================================================================
--- trunk/compilers/pirc/README.pod (original)
+++ trunk/compilers/pirc/README.pod Sun Apr 8 02:24:54 2007
@@ -1,7 +1,13 @@
-=head1 INTRODUCTION
+=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.
@@ -28,13 +34,69 @@
syntax has been implemented, and can be parsed successfully.
For more documentation, please run:
-
- pod2html src/pirparser.c > doc/pirparser.html
- pod2html src/pirlexer.c > doc/pirlexer.html
-
+
+ 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.
+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
@@ -54,6 +116,12 @@
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>
Modified: trunk/compilers/pirc/doc/design.pod
==============================================================================
--- trunk/compilers/pirc/doc/design.pod (original)
+++ trunk/compilers/pirc/doc/design.pod Sun Apr 8 02:24:54 2007
@@ -192,11 +192,13 @@
=item *
-src/pastout.{c,h} - back-end that implements the vtable methods to output PAST
(in Data::Dumper format)
+src/pastout.{c,h} - back-end that implements the vtable methods to output PAST
+(in Data::Dumper format)
=item *
-src/pbcout.{c,h} - dummy back-end for PBC. This file only creates a vtable,
but no implementation yet.
+src/pbcout.{c,h} - dummy back-end for PBC. This file only creates a vtable,
+but no implementation yet.
=item *
Modified: trunk/compilers/pirc/src/pastout.c
==============================================================================
--- trunk/compilers/pirc/src/pastout.c (original)
+++ trunk/compilers/pirc/src/pastout.c Sun Apr 8 02:24:54 2007
@@ -21,16 +21,21 @@
/* keep outputfile possibility easy */
#define OUT stderr
#define INDENT 4
+#define indent(D) D->indent += INDENT
+#define dedent(D) D->indent -= INDENT
-#define indent(D) D->indent += INDENT
-#define dedent(D) D->indent -= INDENT
+/*
+=head1 DATA STRUCTURE
-/* Private declaration of emit_data.
- *
- *
- */
+The PAST back-end implements the C<emit_data> data structure.
+Currently, only a single data member is used, to control the
+indention.
+
+=cut
+
+*/
typedef struct emit_data {
int indent;
@@ -109,7 +114,7 @@
/*
-=item past_init()
+=item past_stmts()
Opens a PAST::Stmts node.
@@ -122,7 +127,15 @@
indent(data);
}
+/*
+
+=item past_param()
+
+Generates a PAST::Var node and set its scope attribute to "parameter".
+
+=cut
+*/
static void
past_param(struct emit_data *data) {
fprintf(OUT, "%*sFIXTHIS => PMC 'PAST::Var' {\n", data->indent, " ");
@@ -130,11 +143,29 @@
fprintf(OUT, "%*s<scope> => \"parameter\"\n", data->indent, " ");
}
+/*
+
+=item past_type()
+
+
+
+=cut
+
+*/
static void
past_type(struct emit_data *data, char *type) {
fprintf(OUT, "%*s<type> => \"%s\"\n", data->indent, " ", type);
}
+/*
+
+=item past_subflag()
+
+
+
+=cut
+
+*/
static void
past_subflag(struct emit_data *data, int flag) {
/* fprintf(OUT, "%*s<???> => \"%s\"\n", data->indent, " ", type);
@@ -142,6 +173,15 @@
}
+/*
+
+=item past_op()
+
+
+
+=cut
+
+*/
static void
past_op(struct emit_data *data, char *op) {
fprintf(OUT, "%*sFIXME => PMC 'PAST::Op' {\n", data->indent, " ");
@@ -150,16 +190,43 @@
}
+/*
+
+=item past_expr()
+
+
+
+=cut
+
+*/
static void
past_expr(struct emit_data *data, char *expr) {
fprintf(OUT, "%*s[%d] => \"%s\"\n", data->indent, " ", 0, expr); /* fix
index */
}
+/*
+
+=item past_next()
+
+
+
+=cut
+
+*/
static void
past_next(struct emit_data *data) {
/* increment index */
}
+/*
+
+=item past_destroy()
+
+
+
+=cut
+
+*/
static void
past_destroy(emit_data *data) {
free(data);
Modified: trunk/compilers/pirc/src/pirlexer.c
==============================================================================
--- trunk/compilers/pirc/src/pirlexer.c (original)
+++ trunk/compilers/pirc/src/pirlexer.c Sun Apr 8 02:24:54 2007
@@ -29,7 +29,8 @@
=item *
-Check for 'correct' use of data types (unsigned etc.)
+Check for 'correct' use of data types (unsigned etc.) (should characters be
stored
+in C<char>s or C<int>s?
=back
@@ -260,25 +261,63 @@
=head2 file_buffer structure
-Structure that represents a file.
-It contains the filename, a buffer for the file contents,
-a read pointer, the filesize, the current line number,
-and a pointer to the previous buffer. If any, the
-prevbuffer points to the structure of the file that
-.include'd this file.
+Structure that represents a file. Its layout is shown below. First, it
contains the filename
+of the file that is represented by this buffer. Then, the buffer is an array
that holds the
+complete file contents. This is done for efficiency (instead of reading
character by character
+from disk). The C<curchar> acts like a cursor, that points to the current
character.
+The field C<filesize> contains the size of the file counted in bytes, C<line>
keeps track of
+the current line number, and C<linepos> counts the number of characters since
the last newline
+character. The field C<lastchar> stores the previous character (so the
character I<before> the
+character pointed to by C<curchar>. This field is used to decide whether the
previous character
+was a newline. If so, then C<curchar> is at the start of a line (needed for
Heredoc delimiters).
+
+The field C<prevbuffer> points to another file_buffer; if the current file was
C<.include>d,
+then C<prevbuffer> points to the file_buffer that represents the including
file. An example:
+
+ $ cat main.pir
+
+ .include "util.pir"
+
+ .sub main
+ # ...
+ .end
+
+ $ cat util.pir
+
+ .sub foo
+ # ...
+ .end
+
+In this case, when parsing the file C<main.pir>, C<prevbuffer> is NULL,
because this file was
+not included. Then, when the file C<util.pir> is included, a new file_buffer
is created for that
+file, and C<prevbuffer> is set to the file_buffer representing C<main.pir>.
+
+The file_buffer structure is shown below:
+
+ typedef struct file_buffer {
+ char *filename; -- the name of this file
+ char *buffer; -- buffer holding contents of this file
+ char *curchar; -- pointer to the current char.
+ unsigned filesize; -- size of this file in bytes
+ unsigned long line; -- line number
+ unsigned short linepos; -- position on the current line
+ char lastchar; -- the previous character that was read.
+ struct file_buffer *prevbuffer; -- pointer to 'including' file if any
+
+ } file_buffer;
=cut
*/
typedef struct file_buffer {
- char *filename; /* the name of this file
*/
- char *buffer; /* buffer holding contents of this file
*/
- char *curchar; /* pointer to the current char.
*/
- unsigned filesize; /* size of this file in bytes
*/
- unsigned long line; /* line number
*/
- unsigned short linepos; /* position on the current line
*/
- char lastchar; /* the previous character that was read.
*/
- struct file_buffer *prevbuffer; /* pointer to 'including' file if any
*/
+ char *filename;
+ char *buffer;
+ char *curchar;
+ unsigned filesize;
+ unsigned long line;
+ unsigned short linepos;
+ char lastchar;
+ struct file_buffer *prevbuffer;
} file_buffer;
Modified: trunk/config/gen/makefiles/pirc.in
==============================================================================
--- trunk/config/gen/makefiles/pirc.in (original)
+++ trunk/config/gen/makefiles/pirc.in Sun Apr 8 02:24:54 2007
@@ -30,17 +30,11 @@
SOURCES = src/pirmain.c \
src/pirparser.c \
- src/pirparser.h \
src/pirlexer.c \
- src/pirlexer.h \
src/pirout.c \
- src/pirout.h \
src/pastout.c \
- src/pastout.h \
src/pirvtable.c \
- src/pirvtable.h \
- src/jsonout.c \
- src/jsonout.h
+ src/jsonout.c
pirc: pirmain$(O) pirparser$(O) pirlexer$(O) pirout$(O) pastout$(O)
pirvtable$(O) jsonout$(O) pbcout$(O)
@@ -100,13 +94,18 @@
docs: src/pirlexer.c src/pirparser.c doc/design.pod
pod2html --css=http://www.parrotcode.org/css/perl.css src/pirlexer.c >
doc/pirlexer.html
pod2html --css=http://www.parrotcode.org/css/perl.css src/pirparser.c >
doc/pirparser.html
+ pod2html --css=http://www.parrotcode.org/css/perl.css src/pirvtable.c >
doc/pirvtable.html
+ pod2html --css=http://www.parrotcode.org/css/perl.css src/pirout.c >
doc/pirout.html
+ pod2html --css=http://www.parrotcode.org/css/perl.css src/jsonout.c >
doc/jsonout.html
+ pod2html --css=http://www.parrotcode.org/css/perl.css src/pastout.c >
doc/pastout.html
pod2html --css=http://www.parrotcode.org/css/perl.css doc/design.pod >
doc/design.html
+ pod2html --css=http://www.parrotcode.org/css/perl.css README.pod >
doc/README.html
test: all
cd t && prove && cd ..
- podchecker src/pirparser.c \
- src/pirlexer.c \
- doc/design.pod
+ podchecker $(SOURCES) \
+ doc/design.pod \
+ README.pod
testclean:
