Next: %code Summary, Previous: Decl Summary, Up: Declarations [Contents][Index]
There are many features of Bison’s behavior that can be controlled by
assigning the feature a single value. For historical reasons, some such
features are assigned values by dedicated directives, such as %start
,
which assigns the start symbol. However, newer such features are associated
with variables, which are assigned by the %define
directive:
Define variable to value.
The type of the values depend on the syntax. Braces denote value in the target language (e.g., a namespace, a type, etc.). Keyword values (no delimiters) denote finite choice (e.g., a variation of a feature). String values denote remaining cases (e.g., a file name).
It is an error if a variable is defined by %define
multiple
times, but see -D name[=value].
The rest of this section summarizes variables and values that %define
accepts.
Some variables take Boolean values. In this case, Bison will complain if the variable definition does not meet one of the following four conditions:
value
is true
value
is omitted (or ""
is specified).
This is equivalent to true
.
value
is false
.
What variables are accepted, as well as their meanings and default values, depend on the selected target language and/or the parser skeleton (see section Bison Declaration Summary, see section Bison Declaration Summary). Unaccepted variables produce an error. Some of the accepted variables are described below.
%define api.namespace {foo::bar}
Bison uses foo::bar
verbatim in references such as:
foo::bar::parser::semantic_type
However, to open a namespace, Bison removes any leading ::
and then
splits on any remaining occurrences:
namespace foo { namespace bar { class position; class location; } }
"::"
. For example, "foo"
or "::foo::bar"
.
yy
, unless you used the obsolete ‘%name-prefix "prefix"’
directive.
none
none
If locations are enabled, generate the definition of the position
and
location
classes in the header file if %defines
, otherwise in
the parser implementation.
Generate the definition of the position
and location
classes
in file. This file name can be relative (to where the parser file is
output) or absolute.
api.location.type
). Otherwise, Bison’s
location
is generated in location.hh (see section C++ location
).
position
and
location
classes is included. This makes sense when the
location
class is exposed to the rest of your application/library in
another directory. See section Exposing the Location Classes.
#include
.
parser
. In Java, YYParser
or
api.prefixParser
(see section Java Bison Interface).
parser_class_name
.
YY
for Java, yy
otherwise.
true
, false
, full
The value may be omitted: this is equivalent to specifying true
, as is
the case for Boolean values.
When %define api.pure full
is used, the parser is made reentrant. This
changes the signature for yylex
(see section Calling Conventions for Pure Parsers), and also that of
yyerror
when the tracking of locations has been activated, as shown
below.
The true
value is very similar to the full
value, the only
difference is in the signature of yyerror
on Yacc parsers without
%parse-param
, for historical reasons.
I.e., if ‘%locations %define api.pure’ is passed then the prototypes for
yyerror
are:
void yyerror (char const *msg); // Yacc parsers. void yyerror (YYLTYPE *locp, char const *msg); // GLR parsers.
But if ‘%locations %define api.pure %parse-param {int *nastiness}’ is used, then both parsers have the same signature:
void yyerror (YYLTYPE *llocp, int *nastiness, char const *msg);
(see section The Error Reporting Function yyerror
)
false
full
value was introduced in Bison 2.7
pull
, push
, both
pull
%define api.symbol.prefix {S_} %token FILE for ERROR %% start: FILE for ERROR;
generates this definition in C:
/* Symbol kind. */ enum yysymbol_kind_t { S_YYEMPTY = -2, /* No symbol. */ S_YYEOF = 0, /* $end */ S_YYERROR = 1, /* error */ S_YYUNDEF = 2, /* $undefined */ S_FILE = 3, /* FILE */ S_for = 4, /* for */ S_ERROR = 5, /* ERROR */ S_YYACCEPT = 6, /* $accept */ S_start = 7 /* start */ };
The empty prefix is invalid:
YYERROR
macro, and
potentially token kind definitions and symbol kind definitions would
collide;
SymbolKind
class.
YYSYMBOL_
in C. S_
in C++, D and Java.
false
%define api.token.prefix {TOK_} %token FILE for ERROR %% start: FILE for ERROR;
generates the definition of the symbols TOK_FILE
, TOK_for
, and
TOK_ERROR
in the generated source files. In particular, the scanner
must use these prefixed token names, while the grammar itself may still use
the short names (as in the sample rule given above). The generated
informational files (*.output, *.xml, *.gv) are not
modified by this prefix.
Bison also prefixes the generated member names of the semantic value union. See section Generating the Semantic Value Type, for more details.
See Calc++ Parser and Calc++ Scanner, for a complete example.
When api.token.raw
is set, the code of the token kinds are forced to
coincide with the symbol kind. This saves one table lookup per token to map
them from the token kind to the symbol kind, and also saves the generation
of the mapping table. The gain is typically moderate, but in extreme cases
(very simple user actions), a 10% improvement can be observed.
When api.token.raw
is set, the grammar cannot use character literals
(such as ‘'a'’).
false
exp: "number" { $$ = make_number ($1); } | exp "+" exp { $$ = make_binary (add, $1, $3); } | "(" exp ")" { $$ = $2; }
is actually compiled as if you had written:
exp: "number" { $$ = make_number (std::move ($1)); } | exp "+" exp { $$ = make_binary (add, std::move ($1), std::move ($3)); } | "(" exp ")" { $$ = std::move ($2); }
Using a value several times with automove enabled is typically an error. For instance, instead of:
exp: "twice" exp { $$ = make_binary (add, $2, $2); }
write:
exp: "twice" exp { auto v = $2; $$ = make_binary (add, v, v); }
It is tempting to use std::move
on one of the v
, but the
argument evaluation order in C++ is unspecified.
false
This grammar has no semantic value at all. This is not properly supported yet.
The type is defined thanks to the %union
directive. You don’t have
to define api.value.type
in that case, using %union
suffices.
See section The Union Declaration.
For instance:
%define api.value.type union-directive %union { int ival; char *sval; } %token <ival> INT "integer" %token <sval> STR "string"
The symbols are defined with type names, from which Bison will generate a
union
. For instance:
%define api.value.type union %token <int> INT "integer" %token <char *> STR "string"
Most C++ objects cannot be stored in a union
, use ‘variant’
instead.
This is similar to union
, but special storage techniques are used to
allow any kind of C++ object to be used. For instance:
%define api.value.type variant %token <int> INT "integer" %token <std::string> STR "string"
See section C++ Variants.
Use this type as semantic value.
%code requires { struct my_value { enum { is_int, is_str } kind; union { int ival; char *sval; } u; }; } %define api.value.type {struct my_value} %token <u.ival> INT "integer" %token <u.sval> STR "string"
union-directive
if %union
is used, otherwise …
int
if type tags are used (i.e., ‘%token <type>…’ or
‘%nterm <type>…’ is used), otherwise …
stype
.
union
(not the name of the
typedef
). This variable is set to id
when ‘%union
id’ is used. There is no clear reason to give this union a name.
YYSTYPE
.
Obsoleted by api.location.type
since Bison 2.7.
most
, consistent
, accepting
accepting
if lr.type
is canonical-lr
.
most
otherwise.
lr.default-reductions
in 2.5, renamed as
lr.default-reduction
in 3.0.
false
lr.keep_unreachable_states
in 2.3b, renamed as
lr.keep-unreachable-states
in 2.5, and as
lr.keep-unreachable-state
in 3.0.
lalr
, ielr
, canonical-lr
lalr
Obsoleted by api.namespace
In C++, when variants are used (see section C++ Variants), symbols must be constructed and destroyed properly. This option checks these constraints.
false
simple
Error messages passed to yyerror
are simply "syntax error"
.
detailed
Error messages report the unexpected token, and possibly the expected ones.
However, this report can often be incorrect when LAC is not enabled
(see section LAC). Token name internationalization is supported.
verbose
Similar (but inferior) to detailed
.
Error messages report the unexpected token, and possibly the expected ones. However, this report can often be incorrect when LAC is not enabled (see section LAC).
Does not support token internationalization. Using non-ASCII characters in token aliases is not portable.
custom
The user is in charge of generating the syntax error message by defining the
yyreport_syntax_error
function. See section The Syntax Error Reporting Function yyreport_syntax_error
.
simple
simple
and verbose
. Values
custom
and detailed
were introduced in 3.6.
none
, full
none
In C/C++, define the macro YYDEBUG
(or prefixDEBUG
with
‘%define api.prefix {prefix}’), see Multiple Parsers in the Same Program) to
1 in the parser implementation file if it is not already defined, so that
the debugging facilities are compiled.
false
Obsoleted by api.parser.class
Next: %code Summary, Previous: Decl Summary, Up: Declarations [Contents][Index]