[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. Invoking Bison

The usual way to invoke Bison is as follows:

 
bison infile

Here infile is the grammar file name, which usually ends in `.y'. The parser file's name is made by replacing the `.y' with `.tab.c' and removing any leading directory. Thus, the `bison foo.y' file name yields `foo.tab.c', and the `bison hack/foo.y' file name yields `foo.tab.c'. It's also possible, in case you are writing C++ code instead of C in your grammar file, to name it `foo.ypp' or `foo.y++'. Then, the output files will take an extension like the given one as input (respectively `foo.tab.cpp' and `foo.tab.c++'). This feature takes effect with all options that manipulate file names like `-o' or `-d'.

For example :

 
bison -d infile.yxx

will produce `infile.tab.cxx' and `infile.tab.hxx', and

 
bison -d -o output.c++ infile.y

will produce `output.c++' and `outfile.h++'.

For compatibility with POSIX, the standard Bison distribution also contains a shell script called yacc that invokes Bison with the `-y' option.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 Bison Options

Bison supports both traditional single-letter options and mnemonic long option names. Long option names are indicated with `--' instead of `-'. Abbreviations for option names are allowed as long as they are unique. When a long option takes an argument, like `--file-prefix', connect the option name and the argument with `='.

Here is a list of options that can be used with Bison, alphabetized by short option. It is followed by a cross key alphabetized by long option.

Operations modes:

`-h'
`--help'

Print a summary of the command-line options to Bison and exit.

`-V'
`--version'

Print the version number of Bison and exit.

`--print-localedir'

Print the name of the directory containing locale-dependent data.

`--print-datadir'

Print the name of the directory containing skeletons and XSLT.

`-y'
`--yacc'

Act more like the traditional Yacc command. This can cause different diagnostics to be generated, and may change behavior in other minor ways. Most importantly, imitate Yacc's output file name conventions, so that the parser output file is called `y.tab.c', and the other outputs are called `y.output' and `y.tab.h'. Also, if generating an LALR(1) parser in C, generate #define statements in addition to an enum to associate token numbers with token names. Thus, the following shell script can substitute for Yacc, and the Bison distribution contains such a script for compatibility with POSIX:

 
#! /bin/sh
bison -y "$@"

The `-y'/`--yacc' option is intended for use with traditional Yacc grammars. If your grammar uses a Bison extension like `%glr-parser', Bison might not be Yacc-compatible even if this option is specified.

`-W'
`--warnings'

Output warnings falling in category. category can be one of:

midrule-values

Warn about mid-rule values that are set but not used within any of the actions of the parent rule. For example, warn about unused $2 in:

 
exp: '1' { $$ = 1; } '+' exp { $$ = $1 + $4; };

Also warn about mid-rule values that are used but not set. For example, warn about unset $$ in the mid-rule action in:

 
 exp: '1' { $1 = 1; } '+' exp { $$ = $2 + $4; };

These warnings are not enabled by default since they sometimes prove to be false alarms in existing grammars employing the Yacc constructs $0 or $-n (where n is some positive integer).

yacc

Incompatibilities with POSIX Yacc.

all

All the warnings.

none

Turn off all the warnings.

error

Treat warnings as errors.

A category can be turned off by prefixing its name with `no-'. For instance, `-Wno-syntax' will hide the warnings about unused variables.

Tuning the parser:

`-t'
`--debug'

In the parser file, define the macro YYDEBUG to 1 if it is not already defined, so that the debugging facilities are compiled. See section Tracing Your Parser.

`-L language'
`--language=language'

Specify the programming language for the generated parser, as if %language was specified (see section Bison Declaration Summary). Currently supported languages include C, C++, and Java. language is case-insensitive.

This option is experimental and its effect may be modified in future releases.

`--locations'

Pretend that %locations was specified. See section Bison Declaration Summary.

`-p prefix'
`--name-prefix=prefix'

Pretend that %name-prefix "prefix" was specified. See section Bison Declaration Summary.

`-l'
`--no-lines'

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 as an independent source file in its own right.

`-S file'
`--skeleton=file'

Specify the skeleton to use, similar to %skeleton (see section Bison Declaration Summary).

If file does not contain a /, file is the name of a skeleton file in the Bison installation directory. If it does, file is an absolute file name or a file name relative to the current working directory. This is similar to how most shells resolve commands.

`-k'
`--token-table'

Pretend that %token-table was specified. See section Bison Declaration Summary.

Adjust the output:

`--defines[=file]'

Pretend that %defines was specified, i.e., write an extra output file containing macro definitions for the token type names defined in the grammar, as well as a few other declarations. See section Bison Declaration Summary.

`-d'

This is the same as --defines except -d does not accept a file argument since POSIX Yacc requires that -d can be bundled with other short options.

`-b file-prefix'
`--file-prefix=prefix'

Pretend that %file-prefix was specified, i.e., specify prefix to use for all Bison output file names. See section Bison Declaration Summary.

`-r things'
`--report=things'

Write an extra output file containing verbose description of the comma separated list of things among:

state

Description of the grammar, conflicts (resolved and unresolved), and LALR automaton.

lookahead

Implies state and augments the description of the automaton with each rule's lookahead set.

itemset

Implies state and augments the description of the automaton with the full set of items for each state, instead of its core only.

`--report-file=file'

Specify the file for the verbose description.

`-v'
`--verbose'

Pretend that %verbose was specified, i.e., write an extra output file containing verbose descriptions of the grammar and parser. See section Bison Declaration Summary.

`-o file'
`--output=file'

Specify the file for the parser file.

The other output files' names are constructed from file as described under the `-v' and `-d' options.

`-g[file]'
`--graph[=file]'

Output a graphical representation of the LALR(1) grammar automaton computed by Bison, in Graphviz DOT format. file is optional. If omitted and the grammar file is `foo.y', the output file will be `foo.dot'.

`-x[file]'
`--xml[=file]'

Output an XML report of the LALR(1) automaton computed by Bison. file is optional. If omitted and the grammar file is `foo.y', the output file will be `foo.xml'. (The current XML schema is experimental and may evolve. More user feedback will help to stabilize it.)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2 Option Cross Key

Here is a list of options, alphabetized by long option, to help you find the corresponding short option.

Long Option

Short Option

`--debug'

`-t'

`--defines=[file]'

`--file-prefix=prefix'

`-b' prefix

`--graph=[file]'

`-g' [file]

`--help'

`-h'

`--language=language'

`-L' language

`--locations'

`--name-prefix=prefix'

`-p' prefix

`--no-lines'

`-l'

`--output=file'

`-o' file

`--print-datadir'

`--print-localedir'

`--report-file=file'

`--report=things'

`-r' things

`--skeleton=file'

`-S' file

`--token-table'

`-k'

`--verbose'

`-v'

`--version'

`-V'

`--warnings'

`-W'

`--xml=[file]'

`-x' [file]

`--yacc'

`-y'


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.3 Yacc Library

The Yacc library contains default implementations of the yyerror and main functions. These default implementations are normally not useful, but POSIX requires them. To use the Yacc library, link your program with the `-ly' option. Note that Bison's implementation of the Yacc library is distributed under the terms of the GNU General Public License (see section GNU GENERAL PUBLIC LICENSE).

If you use the Yacc library's yyerror function, you should declare yyerror as follows:

 
int yyerror (char const *);

Bison ignores the int value returned by this yyerror. If you use the Yacc library's main function, your yyparse function should have the following type signature:

 
int yyparse (void);

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on February, 15 2009 using texi2html 1.76.