3.7.13 %define Summary

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:

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.

variable is never defined.
In this case, Bison selects a default value.

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.

Directive: %define api.namespace{namespace}

Languages(s): C++

Purpose: Specify the namespace for the parser class.
For example, if you specify:

%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;
} }

Accepted Values:
Any absolute or relative C++ namespace reference without a trailing
"::". For example, "foo" or "::foo::bar".

Default Value:
The value specified by %name-prefix, which defaults to yy.
This usage of %name-prefix is for backward compatibility and can
be confusing since %name-prefix also specifies the textual prefix
for the lexical analyzer function. Thus, if you specify
%name-prefix, it is best to also specify ‘%define
api.namespace’ so that %name-prefixonly affects the
lexical analyzer function. For example, if you specify:

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:

Purpose: Request a pull parser, a push parser, or both.
See A Push Parser.
(The current push parsing interface is experimental and may evolve.
More user feedback will help to stabilize it.)

Accepted Values: pull, push, both

Default Value: pull

Directive: %define api.token.constructor

Language(s):
C++

Purpose:
When variant-based semantic values are enabled (see C++ Variants),
request that symbols be handled as a whole (type, value, and possibly
location) in the scanner. See Complete Symbols, for details.

Accepted Values:
Boolean.

Default Value:
false

History:
introduced in Bison 3.0

Directive: %define api.token.prefix{prefix}

Languages(s): all

Purpose:
Add a prefix to the token names when generating their definition in the
target language. For instance

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,
*.dot) are not modified by this prefix.

Accepted Values:
Any string. Should be a valid identifier prefix in the target language,
in other words, it should typically be an identifier itself (sequence of
letters, underscores, and —not at the beginning— digits).

Default Value:
empty

History:
introduced in Bison 3.0

Directive: %define api.value.typesupport

Directive: %define api.value.type{type}

Language(s):
all

Purpose:
The type for semantic values.

Accepted Values:

‘{}’

This grammar has no semantic value at all. This is not properly supported
yet.

‘union-directive’ (C, C++)

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:

History:
introduced in Bison 3.0. Was introduced for Java only in 2.3b as
stype.

Directive: %define api.value.union.namename

Language(s):
C

Purpose:
The tag of the generated 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.

Accepted Values:
Any valid identifier.

Default Value:
YYSTYPE.

History:
Introduced in Bison 3.0.3.

Directive: %define location_type

Obsoleted by api.location.type since Bison 2.7.

Directive: %define lr.default-reductionwhen

Language(s): all

Purpose: Specify the kind of states that are permitted to
contain default reductions. See Default Reductions. (The ability to
specify where default reductions should be used is experimental. More user
feedback will help to stabilize it.)

Accepted Values: most, consistent, accepting

Default Value:

accepting if lr.type is canonical-lr.

most otherwise.

History:
introduced as lr.default-reductions in 2.5, renamed as
lr.default-reduction in 3.0.

Directive: %define lr.keep-unreachable-state

Language(s): all

Purpose: Request that Bison allow unreachable parser states to
remain in the parser tables. See Unreachable States.

Accepted Values: Boolean

Default Value: false

History:
introduced as 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.

Directive: %define lr.typetype

Language(s): all

Purpose: Specify the type of parser tables within the
LR(1) family. See LR Table Construction. (This feature is experimental.
More user feedback will help to stabilize it.)

Accepted Values: lalr, ielr, canonical-lr

Default Value: lalr

Directive: %definenamespace {namespace}

Obsoleted by api.namespace

Directive: %define parse.assert

Languages(s): C++

Purpose: Issue runtime assertions to catch invalid uses.
In C++, when variants are used (see C++ Variants), symbols must be
constructed and
destroyed properly. This option checks these constraints.

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.