3.7.14 %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: yy, unless you used the obsolete ‘%name-prefix "prefix"’ directive.

Directive: %define api.location.file "file"

Directive: %define api.location.file none

• Language(s): C++
• Purpose: Define the name of the file in which Bison’s default location and position types are generated. See Exposing the Location Classes.
• Accepted Values:

  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.

  "file"

  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.

• Default Value: Not applicable if locations are not enabled, or if a user location type is specified (see api.location.type). Otherwise, Bison’s location is generated in location.hh (see C++ location).
• History: Introduced in Bison 3.2.

Directive: %define api.location.include {"file"}

Directive: %define api.location.include {<file>}

• Language(s): C++
• Purpose: Specify how the generated file that defines the 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.
• Accepted Values: Argument for #include.
• Default Value: ‘"dir/location.hh"’ where dir is the directory part of the output. For instance src/parse if --output=src/parse/parser.cc was given.
• History: Introduced in Bison 3.2.

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

• Language(s): C, 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++ and Java, in Bison 3.4 for C.

Directive: %define api.parser.class {name}

• Language(s): C++, Java
• Purpose: The name of the parser class.
• Accepted Values: Any valid identifier.
• Default Value: In C++, parser. In Java, YYParser or api.prefixParser (see Java Bison Interface).
• History: Introduced in Bison 3.3 to replace parser_class_name.

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 for Java, yy otherwise.
• 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.
• 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, *.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.

• 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.token.raw

• Language(s): all
• Purpose: The output files normally define the tokens with Yacc-compatible token numbers: sequential numbers starting at 257 except for single character tokens which stand for themselves (e.g., in ASCII, ‘'a'’ is numbered 65). The parser however uses symbol numbers assigned sequentially starting at 3. Therefore each time the scanner returns an (external) token number, it must be mapped to the (internal) symbol number.

  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'’).

• Accepted Values: Boolean.
• Default Value: false
• History: introduced in Bison 3.5. Was initially introduced in Bison 1.25 as ‘%raw’, but never worked and was removed in Bison 1.29.

Directive: %define api.value.automove

• Language(s): C++
• Purpose: Let occurrences of semantic values of the right-hand sides of a rule be implicitly turned in rvalues. When enabled, a grammar such as:

  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.

• Accepted Values: Boolean.
• Default Value: false
• History: introduced in Bison 3.2

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"
  

  Most C++ objects cannot be stored in a union, use ‘variant’ instead.

  ‘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"
  

  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 ‘%nterm <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.
• 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.
• Accepted Values: lalr, ielr, canonical-lr
• Default Value: lalr

Directive: %define namespace {namespace}

Obsoleted by api.namespace

Directive: %define parse.assert

• Languages(s): C, C++
• Purpose: Issue runtime assertions to catch invalid uses. In C, some important invariants in the implementation of the parser are checked when this option is enabled.

  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

Directive: %define parser_class_name {name}

Obsoleted by api.parser.class