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:

Directive: %define variable

Directive: %define variable value

Directive: %define variable {value}

Directive: %define variable "value"

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:

1. value is true
2. value is omitted (or "" is specified). This is equivalent to true.
3. value is false.
4. 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-prefix only affects the lexical analyzer function. For example, if you specify:

  %define api.namespace {foo}
  %name-prefix "bar::"
  

  The parser namespace is foo and yylex is referenced as bar::lex.

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

• Language(s): C++, Java
• Purpose: Define the location type. See User Defined Location Type.
• Accepted Values: String
• Default Value: none
• History: Introduced in Bison 2.7 for C, C++ and Java. Introduced under the name location_type for C++ in Bison 2.5 and for Java in Bison 2.4.

Directive: %define api.prefix {prefix}

• Language(s): All
• Purpose: Rename exported symbols. See Multiple Parsers in the Same Program.
• Accepted Values: String
• Default Value: yy
• History: introduced in Bison 2.6

Directive: %define api.pure purity

• Language(s): C
• Purpose: Request a pure (reentrant) parser program. See A Pure (Reentrant) Parser.
• Accepted Values: 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);
  

  (see The Error Reporting Function yyerror)

• Default Value: false
• History: the full value was introduced in Bison 2.7

Directive: %define api.push-pull kind

• Language(s): C (deterministic parsers only)
• 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

  %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, *.dot) 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.

• 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.type support

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:

  %define api.value.type union-directive
  %union
  {
    int ival;
    char *sval;
  }
  %token <ival> INT "integer"
  %token <sval> STR "string"
  

  ‘union’ (C, C++)

  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"
  

  This feature needs user feedback to stabilize. Note that most C++ objects cannot be stored in a union.

  ‘variant’ (C++)

  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"
  

  This feature needs user feedback to stabilize. See C++ Variants.

  ‘{type}’

  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"
  

• Default Value:
  • - union-directive if %union is used, otherwise …
  • - int if type tags are used (i.e., ‘%token <type>…’ or ‘%type <type>…’ is used), otherwise …
  • - undefined.
• History: introduced in Bison 3.0. Was introduced for Java only in 2.3b as stype.

Directive: %define api.value.union.name name

• 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-reduction when

• 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.type type

• 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: %define namespace {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.
• Accepted Values: Boolean
• Default Value: false

Directive: %define parse.error verbosity

• Languages(s): all
• Purpose: Control the kind of error messages passed to the error reporting function. See The Error Reporting Function yyerror.
• Accepted Values:
  • 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).
• Default Value: simple

Directive: %define parse.lac when

• Languages(s): C (deterministic parsers only)
• Purpose: Enable LAC (lookahead correction) to improve syntax error handling. See LAC.
• Accepted Values: none, full
• Default Value: none

Directive: %define parse.trace

• Languages(s): C, C++, Java
• Purpose: Require parser instrumentation for tracing. See Tracing Your Parser.

  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.

• Accepted Values: Boolean
• Default Value: false