Really update refcard.tex...

[bison.git] / doc / bison.rnh

.!
.!	RUNOFF source file for BISON.HLP 
.!
.!	This is a RUNOFF input file which will produce a VMS help file
.!	for the VMS HELP library.
.!
.!	Eric Youngdale and Wilfred J. Hansen (wjh+@cmu.edu).
.!
.literal
.end literal
.no paging
.no flags all
.right margin 70
.left margin 1

.indent -1
1 BISON
.skip
 The BISON command invokes the GNU BISON parser generator.
.skip
.literal
      BISON file-spec
.end literal
.skip
.indent -1
2 Parameters
.skip
 file-spec
.skip
Here file-spec is the grammar file name, which usually ends in
.y.  The parser file's name is made by replacing the .y
with _tab.c.  Thus, the command bison foo.y yields
foo_tab.c.

.skip
.indent -1
2 Qualifiers
.skip
 The following is the list of available qualifiers for BISON:
.literal
	/DEBUG
	/DEFINES
	/FILE_PREFIX=prefix
	/FIXED_OUTFILES
	/NAME_PREFIX=prefix
	/NOLINES
	/NOPARSER
	/OUTPUT=outfilefile
	/RAW
	/TOKEN_TABLE
	/VERBOSE
	/VERSION
	/YACC
.end literal
.skip
.indent -1
2 /DEBUG
.skip
Output a definition of the macro YYDEBUG into the parser file,
so that the debugging facilities are compiled.
.skip
.indent -1
2 /DEFINES
.skip
Write an extra output file containing macro definitions for the token
type names defined in the grammar and the semantic value type
YYSTYPE, as well as a extern variable declarations.
.skip
If the parser output file is named "name.c" then this file
is named "name.h".
.skip
This output file is essential if you wish to put the definition of
yylex in a separate source file, because yylex needs to
be able to refer to token type codes and the variable
yylval.
.skip
.indent -1
2 /FILE_PREFIX
.skip
.literal
  /FILIE_PREFIX=prefix
.end literal
.skip
	Specify a prefix to use for all Bison output file names.  The names are
chosen as if the input file were named prefix.c

.skip
.indent -1
2 /FIXED_OUTFILES
.skip
Equivalent to /OUTPUT=y_tab.c; the parser output file is called
y_tab.c, and the other outputs are called y.output and
y_tab.h.  The purpose of this switch is to imitate Yacc's output
file name conventions.  The /YACC qualifier is functionally equivalent
to /FIXED_OUTFILES.  The following command definition will
work as a substitute for Yacc:

.literal
$YACC:==BISON/FIXED_OUTFILES
.end literal
.skip
.indent -1
2 /NAME_PREFIX
.skip
.literal
  /NAME_PREFIX=prefix
.end literal
.skip
Rename the external symbols used in the parser so that they start with
"prefix" instead of "yy".  The precise list of symbols renamed
is yyparse, yylex, yyerror, yylval, yychar and yydebug.

For example, if you use /NAME_PREFIX="c", the names become cparse,
clex, and so on.

.skip
.indent -1
2 /NOLINES
.skip
Don't put any "#line" preprocessor commands in the parser file.
Ordinarily Bison puts them in the parser file so that the C compiler
and debuggers will associate errors with your source file, the
grammar file.  This option causes them to associate errors with the
parser file, treating it an independent source file in its own right.
.skip
.indent -1
2 /NOPARSER
.skip
Do not generate the parser code into the output;  generate only
declarations.  The generated name_tab.c file will have only 
constant declarations.  In addition, a name.act file is
generated containing a switch statement body containing all the
translated actions. 
.skip
.indent -1
2 /OUTPUT
.skip
.literal
  /OUTPUT=outfile
.end literal
.skip
Specify the name "outfile" for the parser file.
.skip
.indent -1
2 /RAW
.skip
When this switch is specified, the .tab.h file defines the tokens to
have the bison token numbers rather than the yacc compatible numbers.
To employ this switch you would have to have your own parser.
.skip
.indent -1
2 /TOKEN_TABLE
.skip
This switch causes the name_tab.c output to include a list of 
token names in order by their token numbers;  this is defined in the array 
yytname.  Also generated are #defines for YYNTOKENS, YYNNTS, YYNRULES,
and YYNSTATES.

.skip
.indent -1
2 /VERBOSE
.skip
Write an extra output file containing verbose descriptions of the
parser states and what is done for each type of look-ahead token in
that state.
.skip
This file also describes all the conflicts, both those resolved by
operator precedence and the unresolved ones.
.skip
The file's name is made by removing _tab.c or .c from
the parser output file name, and adding .output instead.
.skip
Therefore, if the input file is foo.y, then the parser file is
called foo_tab.c by default.  As a consequence, the verbose
output file is called foo.output.
.skip
.indent -1
2 /VERSION
.skip
Print the version number of Bison.

.skip
.indent -1
2 /YACC
.skip
See /FIXED_OUTFILES.
.skip
.indent -1