preccx.1

編譯器的辭法分析器工具

.TH PRECCX 1L "30 August 1994" "Oxford University" "LOCAL"
.SH NAME preccx \-
PREttier Compiler Compiler 2.42
.SH SYNOPSIS
.B preccx
[\fIoptions\fP] < \fIfile.y\fP > \fIfile.c\fP

.B preccx
[\fIoptions\fP] \fIfile.y\fP > \fIfile.c\fP

.B preccx
[\fIoptions\fP] \fIfile.y\fP  \fIfile.c\fP
.SH DESCRIPTION
.I Preccx
is a compiler compiler. It converts \fIpreccx\fP-style context-grammar
definition scripts (with a \fI.y\fP extension) into C code scripts
(with a \fI.c\fP extension). The output code compiles under ANSI C
compilers such as the GNU Software Foundation's \fIgcc\fP(1).
.PP
There is an easy-to-use hook for \fIlex\fP(1) tokenisers.
.PP
\fIPreccx\fP extends the UNIX \fIyacc\fP(1) utility by allowing:
.PP
[0] Contextual definitions. Each grammar definition may be
parameterized with contexts.  For example, some languages determine
whether a declaration is local (and to what) or global in scope
by relative indentation, and this can be encoded in \fIpreccx\fP
using the number of spaces indentation as a parameter, n:
.IP
 @ decl(n) = <' '>*n expr <'\\n'> decl(n+1)*
.PP
This definition is intended to mean that a "decl" indented by n
spaces consists of n spaces, an expression, and a newline, optionally
followed by one or several "decl"s indented still further.
.PP
[1] Infinite lookahead and backtracking in place of the \fIyacc\fP
1-token lookahead, This means that \fIpreccx\fP parsers distinguish
correctly between sentences of the form `foo bah gum' and `foo bah NAY'
on a single pass.
If you cannot imagine why one should want to decide between the two,
think about `if\0...\0then\0...' and `if\0...\0then\0...\0else\0...\0'.
.PP
[2] Arbitrarily complex expressions. This means that compound
definitions like
.IP
explain {{this | that} {several | no} times}+
.PP
are legal within \fIpreccx\fP definition scripts.
.PP
[3] \fIPreccx\fP has postfix operators `*' (zero or more times),
`*n' (exactly n times),
`+' (one or more times), and `!' (execute accumulated actions now)
built in, along with the `[\0]' (optionally) outfix operator. For
example, the following means `exactly n spaces':
.IP
 @ space(n) = <'\0'>*n
.PP
The other built-ins are
.IP
`?' (any token)
.IP
`^' (beginning of line)
.IP
`$' (end of line)
.IP
`|' (or, placed between alternate phrases of the grammar)
.IP
`{\0}' (grouping brackets)
.IP
`<\0>' (around literals)
.IP
`>\0<' (to mean `not a particular literal')
.IP
`(\0)' around the name of a \fBBOOLEAN\fP valued predicate on tokens,
defined as an int 1 or 0 \-valued C function elsewhere in the script, and
.IP
`)\0(' (anti-brackets) round a C expression of BOOLEAN type, meaning
a logical test condition.
.IP
`]..[' anti-brackets hide an expression, causing it to be required but
ignored.
.PP
`]a[ b' means that input must satisfy both a and b, while
`a ]b[' means that b is trailing context.
.PP

`$!'  is a shorthand for matching end-of-line followed by execution
of pending actions (it also causes the input buffer to start being
overwritten). It is roughly  equivalent  to the  conjunction '! $',
but more efficient.
.PP
`a\0b\0c' (conjunction) is the term
denoting an expression consisting of an `a expression' followed by a `b
expression' followed by a `c expression'. An example of a \fIpreccx\fP
script follows in the section \fIUSAGE\fP.
.PP
[4] Modular output.  Parts of a script can be \fIpreccx\fP'ed
separately, compiled separately, and then linked together later, which
makes maintenance and version control easy.
.PP
[5] Speed. \fIPreccx\fP is fast, typically taking two to five seconds to
compile scripts of several hundred lines. And it builds fast parsers
too.
.PP
[6] Higher order behaviour. `Macros' may be defined in a script.
For example,
.IP
 @ optional(parser) = parser
.IP
 @ \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 | {}
.PP
may be defined (this particular example is an equivalent for the
built-in `[parser]' construct). After the definition, the construct
.IP
 @ ice_cream(flavour) = tub(flavour) optional(sauce)
.PP
may be used instead of the built-in:
.IP
 @ ice_cream(flavour) = tub(flavour) [sauce]
.PP
[7] Separate syntax to distinguish synthesised attributes
(without side-effects) from attached actions (with side-effects) in
2.40 and above. This is a break from yacc(1) style aimed at greater
transparancy and robustness. For example, the following synthesises a
total for a simple sum without using side-effecting actions or the
run-time value stack:
.IP
 @ sum   = summand\\x <'+'> summand\\y  {@ $x+$y @}
.PP
whereas the following uses \fIyacc\fP(1)-style references in an
attached action:
.IP
 @ sum   = summand <'+'> summand  {: total=$1+$3; :}
.PP
NOTE: From 2.41 onwards \fIyacc\fP(1)-style referencing is only supported with
the `-old' command line switch to preccx, and less efficient code is
generated.  Moreover, the scope of both kinds of dollar variables is now
strictly left to right so that `$0' can no longer be used to access a term
to the left.  In other words, the \fIyacc\fP(1) style of use is now restricted and
discouraged.
.PP
[8] Built-in error handling capability (2.40 and above).  The following
code sets the handler `foo' as the parser to use when the parse beyond
the `!{foo}' does not match:
.IP
 @ typical = okstuff !{foo} morestuff
.PP
Malformed parse input will be matched against the parse `okstuff foo',
and well-formed input will be matched against `okstuff morestuff'. The
definition in this instance is equivalent to
`okstuff ! {morestuff | foo}'.
.PP
\fIPreccx\fP is intended to be both easy and convenient to use, but a compiler
compiler cannot be understood in one minute.  Have a look at the example
*.y files in the \fIpreccx\fP directory to get more of the feel.  A more
complex line in a grammar definition script than those above may look
like:
.IP
 @ expr = var { <'+'> | <'-'> } expr
.IP
 @ \0\0\0\0 | <'('> expr <')'>
.PP
The `@' is an `attention mark'.  Every line which does not begin with an
`@' is passed through to the output unchanged, so arbitrary C code can
be embedded in a preccx script.  Intended comments must therefore be
surrounded by C comment marks, `/*' and `*/'.
.PP
A default do-nothing tokeniser is provided in the preccx library and
will be automatically linked in unless you specify a different yylex()
routine to the C compiler. There is nothing to worry about here. If you
do nothing yourself, you will get a working parser out of a \fIpreccx\fP
script immediately, but if you particularly want to put your own
tokeniser on the input, then you do that by naming it `yylex()' and
making it return TOKENs when called. It should write VALUE attributes
into `yylval', just like \fIlex\fP(1). Place its object module or source
code file ahead of the `-lcc' argument when you use the C compiler, and
it will be linked in instead of the default (NB. yylex() \fImust\fP
signal EOF to \fIpreccx\fP by setting `yytchar=EOF', which yylex()
routines generated by \fIlex\fP(1) do not seem to get right).
.PP
The way to compile a C source code file `foo.c' generated by
\fIpreccx\fP into an executable `foo' is to use an incantation like:
.IP
gcc\0\-Wall\0\-ansi\0\-o\0foo\0foo.c\0\-L\0<preccx\0dir>\0\-lcc
.PP
You can change the TOKEN type  by #defining it as a C macro in the *.y
script (you may want a wider range of TOKENs than the 256 possibilities
afforded by the default 8-bit char, and `#define TOKEN short int' is
sometimes useful). But it is  important that the appropriate \fIpreccx\fP
library is used at link time. The default libcc.a library will assume
TOKEN=char, but different versions of the library can be produced by
recompiling with TOKEN set to the desired data type.
.PP
The parser generated from a \fIpreccx\fP script will ordinarily
signal valid input by absorbing it silently, and signal invalid input by
rejecting it and spouting an error message. This is a standard style
for compiler-compilers. To get the parser to do anything else, you must
decorate the definition script with ACTIONs (see below for details).
.PP
The error handler may be redefined by #defining an ON_ERROR(x)
macro. An x=0 value should give the code to execute on a partial but
successful parse and x=1 should give the code to execute on an
unsuccessful parse. x=-1 should give code to execute when \fIpreccx\fP
attempts to backtrack across a `cut' (`!', see below). For example:
.IP
#define\0ON_ERROR(x)\0x?printf("ow!\\n"):printf("ouch!\\n")
.PP
The default error actions attempt to restart the parse on the next line
of input, using the parser p designated by `MAIN(p)' in the script.
.PP
You may likewise #define BEGIN and END for C code to be executed at
either end of a parse attempt.  This means that BEGIN will be
re-executed if the parse resyncs after an error, and your code should
take account of that (most likely by installing and using an invocation
counter).
.SH OPTIONS
.I Preccx
can be run as a \fIstdin\fP to \fIstdout\fP filter, taking no options or
arguments.  It is better practice, however, to use the command line
options:
.IP
        \fIpreccx\fP [options] infile outfile
.PP
because then there is no danger of \fIpreccx\fP misidentifying the console
or keyboard when you have redirected stdin and stdout.
.PP
The default sizes of various internal buffers can be changed by command
line options (version 2.40 and above only), as follows:
.IP
-rNNNN The read buffer size in Kb.  This determines the maximum
char length of a single production in a script readable by
\fIpreccx\fP.  Default 2Kb/ 2K chars.
.IP
-pNNNN The maximum size in Kb of the internal program (tables)
built by \fIpreccx\fP during the scan of a specification script.  It
correlates with the maximum number of symbols in a single
production rule.  Default 20Kb/4K instructions.
.IP
-vNNNN The maximum size in Kb of the attributed data built by \fIpreccx\fP
during the scan of the specification script.  Default 16Kb/4K
data items up to v2.41, 0Kb/0K in v2.42 and later (now handled by C and
the data is compiled instead of dynamically interpreted).
.IP
-fNNNN The maximal size in Kb of the area used by \fIpreccx\fP to store
backtrack points when scanning a script.  It correlates to the
maximal number of sequents in a production rule.  Default
16Kb/1K breakpoints.
.PP
The sizes need only be changed if \fIpreccx\fP fails to parse an input
script returning an error message that indicates an overflow of one of
these buffers.
.PP
The buffers are also used by utilities built by \fIpreccx\fP, and their
sizes in the utilities are set by the macros READBUFFERSIZE,
MAXPROGRAMSIZE, STACKSIZE and CONTEXTSTACKSIZE respectively (see below
and look in cc.h and ccx.h).
.PP
-old This flag (version 2.41 and above) supports the use of \fPyacc(1)\fI
style dollar variables in attached actions.  The support is limited
however: $0 and lower cannot be referenced and the variables should only
be read, not written. Writing to $1 still works as a way to assign the
attribute attached to an entire clause, but use the {@foo@} notation in
preference.
.SH ENVIRONMENT
The following macros must be set in the user's grammar definition
script, above the #include <cc.h> or <ccx.h> directive:
.TP 20
.BI #\0define\0TOKEN\0tokentype
.PP
(default char)
This defines the space reserved for each incoming token in the parser
which \fIpreccx\fP builds.  Note that a corresponding version of libcc.a
must be linked in at compile time.
.TP 20
.BI #\0define\0VALUE\0valuetype
.PP
(default char*)
This defines the space reserved for each value on the runtime stack
manipulated by the runtime program which \fIpreccx\fP attaches to the parser.
There is no good reason for changing this to a type which
is shorter than long int (or far *char), because the actual space used
will be a union type which is at least as long as these.
.PP
In version 2.41 and above, this stack is by dfault absent, but the VALUE
macro still has significance.
.TP 20
.BI #\0define\0PARAM\0parametertype
.PP
(default long)
This defines the space reserved for grammar parameters on
the C runtime call stack.  It may be worthwhile changing this to int on
systems where int is much shorter than long.  On such systems, integer
constants must be cast to PARAM before they can be used as grammar
parameters, viz: foo((PARAM)0).
.PP