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 %language, see %skeleton). 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 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 Exposing the Location Classes.
#include
.
parser
. In Java, YYParser
or
api.prefixParser
(see 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 Pure Calling), 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);
false
full
value was introduced in Bison 2.7
pull
, push
, both
pull
false
%token FILE for ERROR %define api.token.prefix {TOK_} %% 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 Generating the Semantic Value Type, for more details.
See Calc++ Parser and Calc++ Scanner, for a complete example.
When api.token.raw
is set, tokens are assigned their internal number,
which saves one table lookup per token to map them from the external to the
internal number, 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 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 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 C++ Variants), symbols must be constructed and destroyed properly. This option checks these constraints.
false
yyerror
.
simple
Error messages passed to yyerror
are simply "syntax error"
.
verbose
Error messages report the unexpected token, and possibly the expected ones.
However, this report can often be incorrect when LAC is not enabled
(see LAC).
simple
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]