Next: , Previous: , Up: Bison Declarations   [Contents][Index]

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 Bison Declaration Summary, see Bison Declaration Summary). Unaccepted variables produce an error. Some of the accepted variables are described below.

Directive: %define api.filename.type {type}
  • Language(s): C++
  • Purpose: Define the type of file names in Bison’s default location and position types. See Exposing the Location Classes.
  • Accepted Values: Any type that is printable (via streams) and comparable (with == and !=).
  • Default Value: const std::string.
  • History: Introduced in Bison 2.0 as filename_type (with std::string as default), renamed as api.filename.type in Bison 3.7 (with const std::string as default).
Directive: %define api.header.include {"header.h"}
Directive: %define api.header.include {<header.h>}
  • Languages(s): C (yacc.c)
  • Purpose: Specify how the generated parser should include the generated header.

    Historically, when option -d or --header was used, bison generated a header and pasted an exact copy of it into the generated parser implementation file. Since Bison 3.6, it is #included as ‘"basename.h"’, instead of duplicated, unless file is ‘y.tab’, see below.

    The api.header.include variable allows to control how the generated parser #includes the generated header. For instance: 

    %define api.header.include {"parse.h"}

    or 

    %define api.header.include {<parser/parse.h>}

    Using api.header.include does not change the name of the generated header, only how it is included.

    To work around limitations of Automake’s ylwrap (which runs bison with --yacc), api.header.include is not predefined when the output file is y.tab.c. Define it to avoid the duplication.

  • Accepted Values: An argument for #include.
  • Default Value: ‘"header-basename"’, unless the header file is y.tab.h, where header-basename is the name of the generated header, without directory part. For instance with ‘bison -d calc/parse.y’, api.header.include defaults to ‘"parse.h"’, not ‘"calc/parse.h"’.
  • History: Introduced in Bison 3.4. Defaults to ‘"basename.h"’ since Bison 3.7, unless the header file is y.tab.h.
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 %header, 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 Data Type of Locations, and 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. Was originally named location_type in Bison 2.5 and 2.6.
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::value_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.parser.class {name}
  • Language(s): C++, Java, D
  • Purpose: The name of the parser class.
  • Accepted Values: Any valid identifier.
  • Default Value: In C++, parser. In D and 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): C, C++, Java
  • 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, with its argument in double quotes. Uses braces since Bison 3.0 (double quotes are still supported for backward compatibility).
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 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 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), D, Java
  • 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.symbol.prefix {prefix}
  • Languages(s): all
  • Purpose: Add a prefix to the name of the symbol kinds. For instance 
    %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  */
};
  • Accepted Values: Any non empty string. Must be a valid identifier in the target language (typically a non empty sequence of letters, underscores, and —not at the beginning— digits).

    The empty prefix is (generally) invalid:

    • in C it would create collision with the YYERROR macro, and potentially token kind definitions and symbol kind definitions would collide;
    • unnamed symbols (such as ‘'+'’) have a name which starts with a digit;
    • even in languages with scoped enumerations such as Java, an empty prefix is dangerous: symbol names may collide with the target language keywords, or with other members of the SymbolKind class.
  • Default Value: YYSYMBOL_ in C, S_ in C++ and Java, empty in D.
  • History: introduced in Bison 3.6.
Directive: %define api.token.constructor
  • Language(s): C++, D
  • Purpose: Request that symbols be handled as a whole (type, value, and possibly location) in the scanner. In the case of C++, it works only when variant-based semantic values are enabled (see C++ Variants), see Complete Symbols, for details. In D, token constructors work with both ‘%union’ and ‘%define api.value.type union’.
  • 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 
    %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 Generating the Semantic Value Type, for more details.

    See Calc++ Parser and Calc++ Scanner, for a complete example.

  • Accepted Values: Any string. Must be a valid identifier prefix in the target language (typically, a possibly empty 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 enumeration of the token kinds with Yacc-compatible token codes: 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 kinds which are assigned numbers sequentially starting at 0. Therefore each time the scanner returns an (external) token kind, it must be mapped to the (internal) symbol kind.

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

  • Accepted Values: Boolean.
  • Default Value: true in D, false otherwise
  • 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++, D)

    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 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 using runtime type information (RTTI). Therefore the generated code cannot be compiled with RTTI disabled (via compiler options such as -fno-rtti).

  • Accepted Values: Boolean
  • Default Value: false
Directive: %define parse.error verbosity
  • Languages(s): all
  • Purpose: Control the generation of syntax error messages. See Error Reporting.
  • Accepted Values:
    • 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 LAC). Token name internationalization is supported.
    • verbose Similar (but inferior) to detailed. The D parser does not support this value.

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

      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 The Syntax Error Reporting Function yyreport_syntax_error.
  • Default Value: simple
  • History: introduced in 3.0 with support for simple and verbose. Values custom and detailed were introduced in 3.6.
Directive: %define parse.lac when
  • Languages(s): C/C++ (deterministic parsers only), D and Java.
  • 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++, D, 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 (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

Next: %code Summary, Previous: Bison Declaration Summary, Up: Bison Declarations   [Contents][Index]