manpage

.\"	%W%	%R% (Berkeley) %E%
.\"
.TH BTYACC 1 "June\ 05,\ 2015"
.UC 6
.SH NAME
BTYacc \- an LALR(1) parser generator with backtracking
.SH SYNOPSIS
.B btyacc [ -dlrtvy ] [ -b
.I file-prefix
.B ] [ -p
.I identifier-prefix
.B ] [ -S
.I skeleton file
.B ] [ -D
.I macro
.B ]
.I filename
.SH DESCRIPTION
.I BTYacc
reads the grammar specification in the file
.I filename
and generates an LR(1) parser for it.
The parsers consist of a set of LALR(1) parsing tables and a driver routine
written in the C programming language.
.I Yacc
normally writes the parse tables and the driver routine to the file
.IR y.tab.c .
.SH OPTIONS
.TP
\fB-b \fIprefix\fR
The
.B -b
option changes the prefix prepended to the output file names to
the string denoted by
.IR prefix .
The default prefix is derived from the input filename.
.TP
\fB-p \fIprefix\fR
The
.B -p
option changes the prefix prepended to the global identifiers, such as
.IR parse ,
to the string denoted by
.IR prefix .
This allows multiple parsers to be linked together in the same executable.
The default prefix is
.IR yy .
.TP
.B -d
The \fB-d\fR option causes the header file
.IR y.tab.h
to be written.
.TP
.B -l
If the
.B -l
option is not specified,
.I btyacc
will insert \fB#line\fR directives in the generated code.
The \fB#line\fR directives let the C compiler relate errors in the
generated code to the user's original code.
If the \fB-l\fR option is specified,
.I btyacc
will not insert the \fB#line\fR directives.
\fB#line\fR directives specified by the user will be retained.
.TP
.B -r
The
.B -r
option causes
.I btyacc
to produce separate files for code and tables.  The code file
is named
.IR y.code.c ,
and the tables file is named
.IR y.tab.c .
.TP
.B -t
The
.B -t
option changes the preprocessor directives generated by
.I btyacc
so that debugging statements will be incorporated in the compiled code.
.TP
.B -v
The
.B -v
option causes a human-readable description of the generated parser to
be written to the file
.IR y.output .
.TP
.B -y
The
.B -y
option causes btyacc to use a fixed prefix of y for output files, for
compatibility with POSIX yacc
.TP
\fB-S \fIskeleton file\fR
The \fB-S\fR option causes a different skeleton file to be used.  The
default skeleton file is built in to \fIbtyacc\fR when it is built.
.TP
\fB-D\fIflag\fR
Define a conditional compilation flag
.SH GRAMMAR DESCRIPTION
The grammar specification read by \fIbtyacc\fR consists of three sections
separated by \fB%%\fR markers

.EX
    DECLARATIONS
    %%
    GRAMMAR RULES
    %%
    CODE
.EE

The \fBCODE\fR section is optional, and is copied directly to the output code file without change.
.SH DECLARATIONS
.TP
.B %{
.TQ
.B %}
Copy text directly to the output code file without change.  This may be used
for any declarations or other initialization needed for other declarations or action code
.TP
\fB%define \fIflag\fR
Defines \fIflag\fR for future conditional inclusion
.TP
\fB%ifdef \fIflag\fR
.TQ
.B %endif
Tests \fIflag\fR, and include the code between the \fB%ifdef\fR and
\fB%endif\fR tags only if it has been set by a previous \fB%define\fR
declaration or \fB-D\fR option
.TP
\fB%include \fIfile\fR
Include the contents of \fIfile\fR in the grammar description at this point
.TP
\fB%start \fIsymbol\fR
Declare the start (top level) symbol in the grammar.  If there is no
\fB%start\fR declaration, the first grammar symbol mentioned in the
grammar section will be the start symbol
.TP
\fB%union {\fR ... \fB}\fR
Declares a union type used to hold semantic attributes used in the
actions of the grammar.  All code up to the matching \fB}\fR is included
in the union.  Each field of the union defines a semantic type that may
be used for inherited and synthesized attribures in the grammar
.TP
\fB%token\fR [\fB<\fItype\fB>\fR] \fIname\fR... [\fIvalue\fR]
.TQ
\fB%left\fR [\fB<\fItype\fB>\fR] \fIname\fR... [\fIvalue\fR]
.TQ
\fB%right\fR [\fB<\fItype\fB>\fR] \fIname\fR... [\fIvalue\fR]
.TQ
\fB%nonassoc\fR [\fB<\fItype\fB>\fR] \fIname\fR... [\fIvalue\fR]
Declare tokens (terminal symbols) for the grammar.  The \fItype\fR, if
present, defines the semantic type (union tag) of the attribute associated
with the symbol.  The \fIvalue\fR is an integer value for the token.  The
\fB%left\fR, \fB%right\fR, and \fB%nonassoc\fR directives also associate a
precedence and associativity with the terminal to resolve grammar conflicts.
.TP
\fB%type\fR \fB<\fItype\fB> \fIname\fR[\fB(<\fItype\fB>\fR, ...\fB)\fR]...
Declare types for synthesized and inherited attributes of non-terminal
symbols.  Each non-terminal symbol may have a single synthesized attribute
(the initial \fB<\fItype\fB>\fR) and zero or more inherited attributes
(the \fB<\fItype\fB>\fR in the parenthesis.)
.TP
\fB%destructor {\fR ... \fB}\fR \fB<\fItype\fB>\fR... \fIname\fR...
Declare a destructor for attributes of some type or token.  Whenever
attributes are discarded, a destructor function will be called to
clean up any resources that might be associated with the attribute.
For attributes associated with tokens and synthesized attributes of
non-terminals, a destructor for the symbol will be used in preference
to the one for the type if both are defined.  Inherited attributes are
destroyed based solely on the type.
.TP
\fB%location {\fR ... \fB}\fR
Define a location struct for tracking locations of symbols.  This struct
will be defined as the macro 
.B YYPOSN
in the generated code and is treated as an additional synthesized
attribute for every token and non-terminal in the grammar.
As such, it can actually be used for any information that should
be associated with every symbol.
.TP
\fB%ident\fR "\fIstring\fR"
produces an 
.B #ident
in the output code file, used by some source
management tools
.SH GRAMMAR RULES
Grammar rules take the form
.P
.RS
.I non-terminal\fR[\fB(\fIinherited-attrib\fR, ...\fB)\fR]\fB:\fR
[ \fIsymbol\fR | \fIaction\fR ]...
.br
.B |
[ \fIsymbol\fR | \fIaction\fR ]...
.br
[\fB ; \fR]
.RE
.P
Each rule describes a sequence of terminals and non-terminals that can
be matched and reduced to a single non-terminal, and the actions that should
be done when that occurs.  A \fB|\fR introduces a new rule that uses the same
left hand side non-terminal and inherited attributes as the previous rule.
.P
Each symbol is either the name of a declared terminal symbol, the name of a
non-terminal symbol, or character literal (terminal) in 
.B '
quotes.  If
it is the name of a non-terminal symbol with inherited attributes, it must
be followed by a parenthesized list of expressions with values for those
attributes to be used for further matching of the non-terminal.
.P
Actions come in two flavors -- \fB{}\fR-actions which run only when a rule
is reduced while not in
trial mode, and \fB[]\fR-actions which run regardless of trial mode.
.SH EXAMPLES
Inherited attributes can be used to pass context information about
the declaration specifiers that appear before a list of declarators to all
of the declarator actions:
.P
.nf
    declaration: decl_specs declarator_list($1)
    declarator_list($specs): declarator($specs)
	    | declarator_list($specs) ',' declarator($specs)
    declarator($specs): identifier { $$ = declare_name($specs, $1); }
.fi
.SH ENVIRONMENT
.TP
.B TMPDIR
If the environment variable \fBTMPDIR\fR is set,
it will be used as the name of the directory where the temporary
files are created instead of \fB/tmp\fR.
.TP
.B YYDEBUG
If the generated parser is compiled with
.B -DYYDEBUG
, the
.B YYDEBUG
environment variable can be used to set the debugging level of the parser.
.SH FILES
.IR filename\fB.code.c
.br
.IR filename\fB.tab.c
.br
.IR filename\fB.tab.h
.br
.IR filename\fB.output
.br
.BR /tmp/yacc.aXXXXXX
.br
.BR /tmp/yacc.tXXXXXX
.br
.BR /tmp/yacc.uXXXXXX
.SH DIAGNOSTICS
If there are rules that are never reduced, the number of such rules is
reported on standard error.
If there are any LALR(1) conflicts, the number of conflicts is reported
on standard error.