1 Ceci est le fichier Info bison.info, produit par Makeinfo version 4.0 à
5 * bison: (bison). GNU Project parser generator (yacc replacement).
8 This file documents the Bison parser generator.
10 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1995, 1998, 1999,
11 2000 Free Software Foundation, Inc.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
17 Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided also
19 that the sections entitled "GNU General Public License" and "Conditions
20 for Using Bison" are included exactly as in the original, and provided
21 that the entire resulting derived work is distributed under the terms
22 of a permission notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that the sections entitled "GNU General Public
27 License", "Conditions for Using Bison" and this permission notice may be
28 included in translations approved by the Free Software Foundation
29 instead of in the original English.
32 File: bison.info, Node: Using Precedence, Next: Precedence Examples, Prev: Why Precedence, Up: Precedence
34 Specifying Operator Precedence
35 ------------------------------
37 Bison allows you to specify these choices with the operator
38 precedence declarations `%left' and `%right'. Each such declaration
39 contains a list of tokens, which are operators whose precedence and
40 associativity is being declared. The `%left' declaration makes all
41 those operators left-associative and the `%right' declaration makes
42 them right-associative. A third alternative is `%nonassoc', which
43 declares that it is a syntax error to find the same operator twice "in a
46 The relative precedence of different operators is controlled by the
47 order in which they are declared. The first `%left' or `%right'
48 declaration in the file declares the operators whose precedence is
49 lowest, the next such declaration declares the operators whose
50 precedence is a little higher, and so on.
53 File: bison.info, Node: Precedence Examples, Next: How Precedence, Prev: Using Precedence, Up: Precedence
58 In our example, we would want the following declarations:
64 In a more complete example, which supports other operators as well,
65 we would declare them in groups of equal precedence. For example,
66 `'+'' is declared with `'-'':
68 %left '<' '>' '=' NE LE GE
72 (Here `NE' and so on stand for the operators for "not equal" and so on.
73 We assume that these tokens are more than one character long and
74 therefore are represented by names, not character literals.)
77 File: bison.info, Node: How Precedence, Prev: Precedence Examples, Up: Precedence
82 The first effect of the precedence declarations is to assign
83 precedence levels to the terminal symbols declared. The second effect
84 is to assign precedence levels to certain rules: each rule gets its
85 precedence from the last terminal symbol mentioned in the components.
86 (You can also specify explicitly the precedence of a rule. *Note
87 Context-Dependent Precedence: Contextual Precedence.)
89 Finally, the resolution of conflicts works by comparing the
90 precedence of the rule being considered with that of the look-ahead
91 token. If the token's precedence is higher, the choice is to shift.
92 If the rule's precedence is higher, the choice is to reduce. If they
93 have equal precedence, the choice is made based on the associativity of
94 that precedence level. The verbose output file made by `-v' (*note
95 Invoking Bison: Invocation.) says how each conflict was resolved.
97 Not all rules and not all tokens have precedence. If either the
98 rule or the look-ahead token has no precedence, then the default is to
102 File: bison.info, Node: Contextual Precedence, Next: Parser States, Prev: Precedence, Up: Algorithm
104 Context-Dependent Precedence
105 ============================
107 Often the precedence of an operator depends on the context. This
108 sounds outlandish at first, but it is really very common. For example,
109 a minus sign typically has a very high precedence as a unary operator,
110 and a somewhat lower precedence (lower than multiplication) as a binary
113 The Bison precedence declarations, `%left', `%right' and
114 `%nonassoc', can only be used once for a given token; so a token has
115 only one precedence declared in this way. For context-dependent
116 precedence, you need to use an additional mechanism: the `%prec'
119 The `%prec' modifier declares the precedence of a particular rule by
120 specifying a terminal symbol whose precedence should be used for that
121 rule. It's not necessary for that symbol to appear otherwise in the
122 rule. The modifier's syntax is:
124 %prec TERMINAL-SYMBOL
126 and it is written after the components of the rule. Its effect is to
127 assign the rule the precedence of TERMINAL-SYMBOL, overriding the
128 precedence that would be deduced for it in the ordinary way. The
129 altered rule precedence then affects how conflicts involving that rule
130 are resolved (*note Operator Precedence: Precedence.).
132 Here is how `%prec' solves the problem of unary minus. First,
133 declare a precedence for a fictitious terminal symbol named `UMINUS'.
134 There are no tokens of this type, but the symbol serves to stand for its
142 Now the precedence of `UMINUS' can be used in specific rules:
147 | '-' exp %prec UMINUS
150 File: bison.info, Node: Parser States, Next: Reduce/Reduce, Prev: Contextual Precedence, Up: Algorithm
155 The function `yyparse' is implemented using a finite-state machine.
156 The values pushed on the parser stack are not simply token type codes;
157 they represent the entire sequence of terminal and nonterminal symbols
158 at or near the top of the stack. The current state collects all the
159 information about previous input which is relevant to deciding what to
162 Each time a look-ahead token is read, the current parser state
163 together with the type of look-ahead token are looked up in a table.
164 This table entry can say, "Shift the look-ahead token." In this case,
165 it also specifies the new parser state, which is pushed onto the top of
166 the parser stack. Or it can say, "Reduce using rule number N." This
167 means that a certain number of tokens or groupings are taken off the
168 top of the stack, and replaced by one grouping. In other words, that
169 number of states are popped from the stack, and one new state is pushed.
171 There is one other alternative: the table can say that the
172 look-ahead token is erroneous in the current state. This causes error
173 processing to begin (*note Error Recovery::).
176 File: bison.info, Node: Reduce/Reduce, Next: Mystery Conflicts, Prev: Parser States, Up: Algorithm
178 Reduce/Reduce Conflicts
179 =======================
181 A reduce/reduce conflict occurs if there are two or more rules that
182 apply to the same sequence of input. This usually indicates a serious
183 error in the grammar.
185 For example, here is an erroneous attempt to define a sequence of
186 zero or more `word' groupings.
188 sequence: /* empty */
189 { printf ("empty sequence\n"); }
192 { printf ("added word %s\n", $2); }
195 maybeword: /* empty */
196 { printf ("empty maybeword\n"); }
198 { printf ("single word %s\n", $1); }
201 The error is an ambiguity: there is more than one way to parse a single
202 `word' into a `sequence'. It could be reduced to a `maybeword' and
203 then into a `sequence' via the second rule. Alternatively,
204 nothing-at-all could be reduced into a `sequence' via the first rule,
205 and this could be combined with the `word' using the third rule for
208 There is also more than one way to reduce nothing-at-all into a
209 `sequence'. This can be done directly via the first rule, or
210 indirectly via `maybeword' and then the second rule.
212 You might think that this is a distinction without a difference,
213 because it does not change whether any particular input is valid or
214 not. But it does affect which actions are run. One parsing order runs
215 the second rule's action; the other runs the first rule's action and
216 the third rule's action. In this example, the output of the program
219 Bison resolves a reduce/reduce conflict by choosing to use the rule
220 that appears first in the grammar, but it is very risky to rely on
221 this. Every reduce/reduce conflict must be studied and usually
222 eliminated. Here is the proper way to define `sequence':
224 sequence: /* empty */
225 { printf ("empty sequence\n"); }
227 { printf ("added word %s\n", $2); }
230 Here is another common error that yields a reduce/reduce conflict:
232 sequence: /* empty */
241 redirects:/* empty */
245 The intention here is to define a sequence which can contain either
246 `word' or `redirect' groupings. The individual definitions of
247 `sequence', `words' and `redirects' are error-free, but the three
248 together make a subtle ambiguity: even an empty input can be parsed in
249 infinitely many ways!
251 Consider: nothing-at-all could be a `words'. Or it could be two
252 `words' in a row, or three, or any number. It could equally well be a
253 `redirects', or two, or any number. Or it could be a `words' followed
254 by three `redirects' and another `words'. And so on.
256 Here are two ways to correct these rules. First, to make it a
257 single level of sequence:
259 sequence: /* empty */
264 Second, to prevent either a `words' or a `redirects' from being
267 sequence: /* empty */
281 File: bison.info, Node: Mystery Conflicts, Next: Stack Overflow, Prev: Reduce/Reduce, Up: Algorithm
283 Mysterious Reduce/Reduce Conflicts
284 ==================================
286 Sometimes reduce/reduce conflicts can occur that don't look
287 warranted. Here is an example:
292 def: param_spec return_spec ','
311 It would seem that this grammar can be parsed with only a single
312 token of look-ahead: when a `param_spec' is being read, an `ID' is a
313 `name' if a comma or colon follows, or a `type' if another `ID'
314 follows. In other words, this grammar is LR(1).
316 However, Bison, like most parser generators, cannot actually handle
317 all LR(1) grammars. In this grammar, two contexts, that after an `ID'
318 at the beginning of a `param_spec' and likewise at the beginning of a
319 `return_spec', are similar enough that Bison assumes they are the same.
320 They appear similar because the same set of rules would be active--the
321 rule for reducing to a `name' and that for reducing to a `type'. Bison
322 is unable to determine at that stage of processing that the rules would
323 require different look-ahead tokens in the two contexts, so it makes a
324 single parser state for them both. Combining the two contexts causes a
325 conflict later. In parser terminology, this occurrence means that the
326 grammar is not LALR(1).
328 In general, it is better to fix deficiencies than to document them.
329 But this particular deficiency is intrinsically hard to fix; parser
330 generators that can handle LR(1) grammars are hard to write and tend to
331 produce parsers that are very large. In practice, Bison is more useful
334 When the problem arises, you can often fix it by identifying the two
335 parser states that are being confused, and adding something to make them
336 look distinct. In the above example, adding one rule to `return_spec'
337 as follows makes the problem go away:
346 /* This rule is never used. */
350 This corrects the problem because it introduces the possibility of an
351 additional active rule in the context after the `ID' at the beginning of
352 `return_spec'. This rule is not active in the corresponding context in
353 a `param_spec', so the two contexts receive distinct parser states. As
354 long as the token `BOGUS' is never generated by `yylex', the added rule
355 cannot alter the way actual input is parsed.
357 In this particular example, there is another way to solve the
358 problem: rewrite the rule for `return_spec' to use `ID' directly
359 instead of via `name'. This also causes the two confusing contexts to
360 have different sets of active rules, because the one for `return_spec'
361 activates the altered rule for `return_spec' rather than the one for
374 File: bison.info, Node: Stack Overflow, Prev: Mystery Conflicts, Up: Algorithm
376 Stack Overflow, and How to Avoid It
377 ===================================
379 The Bison parser stack can overflow if too many tokens are shifted
380 and not reduced. When this happens, the parser function `yyparse'
381 returns a nonzero value, pausing only to call `yyerror' to report the
384 By defining the macro `YYMAXDEPTH', you can control how deep the
385 parser stack can become before a stack overflow occurs. Define the
386 macro with a value that is an integer. This value is the maximum number
387 of tokens that can be shifted (and not reduced) before overflow. It
388 must be a constant expression whose value is known at compile time.
390 The stack space allowed is not necessarily allocated. If you
391 specify a large value for `YYMAXDEPTH', the parser actually allocates a
392 small stack at first, and then makes it bigger by stages as needed.
393 This increasing allocation happens automatically and silently.
394 Therefore, you do not need to make `YYMAXDEPTH' painfully small merely
395 to save space for ordinary inputs that do not need much stack.
397 The default value of `YYMAXDEPTH', if you do not define it, is 10000.
399 You can control how much stack is allocated initially by defining the
400 macro `YYINITDEPTH'. This value too must be a compile-time constant
401 integer. The default is 200.
404 File: bison.info, Node: Error Recovery, Next: Context Dependency, Prev: Algorithm, Up: Top
409 It is not usually acceptable to have a program terminate on a parse
410 error. For example, a compiler should recover sufficiently to parse the
411 rest of the input file and check it for errors; a calculator should
412 accept another expression.
414 In a simple interactive command parser where each input is one line,
415 it may be sufficient to allow `yyparse' to return 1 on error and have
416 the caller ignore the rest of the input line when that happens (and
417 then call `yyparse' again). But this is inadequate for a compiler,
418 because it forgets all the syntactic context leading up to the error.
419 A syntax error deep within a function in the compiler input should not
420 cause the compiler to treat the following line like the beginning of a
423 You can define how to recover from a syntax error by writing rules to
424 recognize the special token `error'. This is a terminal symbol that is
425 always defined (you need not declare it) and reserved for error
426 handling. The Bison parser generates an `error' token whenever a
427 syntax error happens; if you have provided a rule to recognize this
428 token in the current context, the parse can continue.
432 stmnts: /* empty string */
437 The fourth rule in this example says that an error followed by a
438 newline makes a valid addition to any `stmnts'.
440 What happens if a syntax error occurs in the middle of an `exp'? The
441 error recovery rule, interpreted strictly, applies to the precise
442 sequence of a `stmnts', an `error' and a newline. If an error occurs in
443 the middle of an `exp', there will probably be some additional tokens
444 and subexpressions on the stack after the last `stmnts', and there will
445 be tokens to read before the next newline. So the rule is not
446 applicable in the ordinary way.
448 But Bison can force the situation to fit the rule, by discarding
449 part of the semantic context and part of the input. First it discards
450 states and objects from the stack until it gets back to a state in
451 which the `error' token is acceptable. (This means that the
452 subexpressions already parsed are discarded, back to the last complete
453 `stmnts'.) At this point the `error' token can be shifted. Then, if
454 the old look-ahead token is not acceptable to be shifted next, the
455 parser reads tokens and discards them until it finds a token which is
456 acceptable. In this example, Bison reads and discards input until the
457 next newline so that the fourth rule can apply.
459 The choice of error rules in the grammar is a choice of strategies
460 for error recovery. A simple and useful strategy is simply to skip the
461 rest of the current input line or current statement if an error is
464 stmnt: error ';' /* on error, skip until ';' is read */
466 It is also useful to recover to the matching close-delimiter of an
467 opening-delimiter that has already been parsed. Otherwise the
468 close-delimiter will probably appear to be unmatched, and generate
469 another, spurious error message:
471 primary: '(' expr ')'
476 Error recovery strategies are necessarily guesses. When they guess
477 wrong, one syntax error often leads to another. In the above example,
478 the error recovery rule guesses that an error is due to bad input
479 within one `stmnt'. Suppose that instead a spurious semicolon is
480 inserted in the middle of a valid `stmnt'. After the error recovery
481 rule recovers from the first error, another syntax error will be found
482 straightaway, since the text following the spurious semicolon is also
485 To prevent an outpouring of error messages, the parser will output
486 no error message for another syntax error that happens shortly after
487 the first; only after three consecutive input tokens have been
488 successfully shifted will error messages resume.
490 Note that rules which accept the `error' token may have actions, just
491 as any other rules can.
493 You can make error messages resume immediately by using the macro
494 `yyerrok' in an action. If you do this in the error rule's action, no
495 error messages will be suppressed. This macro requires no arguments;
496 `yyerrok;' is a valid C statement.
498 The previous look-ahead token is reanalyzed immediately after an
499 error. If this is unacceptable, then the macro `yyclearin' may be used
500 to clear this token. Write the statement `yyclearin;' in the error
503 For example, suppose that on a parse error, an error handling
504 routine is called that advances the input stream to some point where
505 parsing should once again commence. The next symbol returned by the
506 lexical scanner is probably correct. The previous look-ahead token
507 ought to be discarded with `yyclearin;'.
509 The macro `YYRECOVERING' stands for an expression that has the value
510 1 when the parser is recovering from a syntax error, and 0 the rest of
511 the time. A value of 1 indicates that error messages are currently
512 suppressed for new syntax errors.
515 File: bison.info, Node: Context Dependency, Next: Debugging, Prev: Error Recovery, Up: Top
517 Handling Context Dependencies
518 *****************************
520 The Bison paradigm is to parse tokens first, then group them into
521 larger syntactic units. In many languages, the meaning of a token is
522 affected by its context. Although this violates the Bison paradigm,
523 certain techniques (known as "kludges") may enable you to write Bison
524 parsers for such languages.
528 * Semantic Tokens:: Token parsing can depend on the semantic context.
529 * Lexical Tie-ins:: Token parsing can depend on the syntactic context.
530 * Tie-in Recovery:: Lexical tie-ins have implications for how
531 error recovery rules must be written.
533 (Actually, "kludge" means any technique that gets its job done but is
534 neither clean nor robust.)
537 File: bison.info, Node: Semantic Tokens, Next: Lexical Tie-ins, Up: Context Dependency
539 Semantic Info in Token Types
540 ============================
542 The C language has a context dependency: the way an identifier is
543 used depends on what its current meaning is. For example, consider
548 This looks like a function call statement, but if `foo' is a typedef
549 name, then this is actually a declaration of `x'. How can a Bison
550 parser for C decide how to parse this input?
552 The method used in GNU C is to have two different token types,
553 `IDENTIFIER' and `TYPENAME'. When `yylex' finds an identifier, it
554 looks up the current declaration of the identifier in order to decide
555 which token type to return: `TYPENAME' if the identifier is declared as
556 a typedef, `IDENTIFIER' otherwise.
558 The grammar rules can then express the context dependency by the
559 choice of token type to recognize. `IDENTIFIER' is accepted as an
560 expression, but `TYPENAME' is not. `TYPENAME' can start a declaration,
561 but `IDENTIFIER' cannot. In contexts where the meaning of the
562 identifier is _not_ significant, such as in declarations that can
563 shadow a typedef name, either `TYPENAME' or `IDENTIFIER' is
564 accepted--there is one rule for each of the two token types.
566 This technique is simple to use if the decision of which kinds of
567 identifiers to allow is made at a place close to where the identifier is
568 parsed. But in C this is not always so: C allows a declaration to
569 redeclare a typedef name provided an explicit type has been specified
572 typedef int foo, bar, lose;
573 static foo (bar); /* redeclare `bar' as static variable */
574 static int foo (lose); /* redeclare `foo' as function */
576 Unfortunately, the name being declared is separated from the
577 declaration construct itself by a complicated syntactic structure--the
580 As a result, part of the Bison parser for C needs to be duplicated,
581 with all the nonterminal names changed: once for parsing a declaration
582 in which a typedef name can be redefined, and once for parsing a
583 declaration in which that can't be done. Here is a part of the
584 duplication, with actions omitted for brevity:
587 declarator maybeasm '='
589 | declarator maybeasm
593 notype_declarator maybeasm '='
595 | notype_declarator maybeasm
598 Here `initdcl' can redeclare a typedef name, but `notype_initdcl'
599 cannot. The distinction between `declarator' and `notype_declarator'
600 is the same sort of thing.
602 There is some similarity between this technique and a lexical tie-in
603 (described next), in that information which alters the lexical analysis
604 is changed during parsing by other parts of the program. The
605 difference is here the information is global, and is used for other
606 purposes in the program. A true lexical tie-in has a special-purpose
607 flag controlled by the syntactic context.
610 File: bison.info, Node: Lexical Tie-ins, Next: Tie-in Recovery, Prev: Semantic Tokens, Up: Context Dependency
615 One way to handle context-dependency is the "lexical tie-in": a flag
616 which is set by Bison actions, whose purpose is to alter the way tokens
619 For example, suppose we have a language vaguely like C, but with a
620 special construct `hex (HEX-EXPR)'. After the keyword `hex' comes an
621 expression in parentheses in which all integers are hexadecimal. In
622 particular, the token `a1b' must be treated as an integer rather than
623 as an identifier if it appears in that context. Here is how you can do
639 { $$ = make_sum ($1, $3); }
648 Here we assume that `yylex' looks at the value of `hexflag'; when it is
649 nonzero, all integers are parsed in hexadecimal, and tokens starting
650 with letters are parsed as integers if possible.
652 The declaration of `hexflag' shown in the C declarations section of
653 the parser file is needed to make it accessible to the actions (*note
654 The C Declarations Section: C Declarations.). You must also write the
655 code in `yylex' to obey the flag.
658 File: bison.info, Node: Tie-in Recovery, Prev: Lexical Tie-ins, Up: Context Dependency
660 Lexical Tie-ins and Error Recovery
661 ==================================
663 Lexical tie-ins make strict demands on any error recovery rules you
664 have. *Note Error Recovery::.
666 The reason for this is that the purpose of an error recovery rule is
667 to abort the parsing of one construct and resume in some larger
668 construct. For example, in C-like languages, a typical error recovery
669 rule is to skip tokens until the next semicolon, and then start a new
670 statement, like this:
673 | IF '(' expr ')' stmt { ... }
679 If there is a syntax error in the middle of a `hex (EXPR)'
680 construct, this error rule will apply, and then the action for the
681 completed `hex (EXPR)' will never run. So `hexflag' would remain set
682 for the entire rest of the input, or until the next `hex' keyword,
683 causing identifiers to be misinterpreted as integers.
685 To avoid this problem the error recovery rule itself clears
688 There may also be an error recovery rule that works within
689 expressions. For example, there could be a rule which applies within
690 parentheses and skips to the close-parenthesis:
698 If this rule acts within the `hex' construct, it is not going to
699 abort that construct (since it applies to an inner level of parentheses
700 within the construct). Therefore, it should not clear the flag: the
701 rest of the `hex' construct should be parsed with the flag still in
704 What if there is an error recovery rule which might abort out of the
705 `hex' construct or might not, depending on circumstances? There is no
706 way you can write the action to determine whether a `hex' construct is
707 being aborted or not. So if you are using a lexical tie-in, you had
708 better make sure your error recovery rules are not of this kind. Each
709 rule must be such that you can be sure that it always will, or always
710 won't, have to clear the flag.
713 File: bison.info, Node: Debugging, Next: Invocation, Prev: Context Dependency, Up: Top
715 Debugging Your Parser
716 *********************
718 If a Bison grammar compiles properly but doesn't do what you want
719 when it runs, the `yydebug' parser-trace feature can help you figure
722 To enable compilation of trace facilities, you must define the macro
723 `YYDEBUG' when you compile the parser. You could use `-DYYDEBUG=1' as
724 a compiler option or you could put `#define YYDEBUG 1' in the C
725 declarations section of the grammar file (*note The C Declarations
726 Section: C Declarations.). Alternatively, use the `-t' option when you
727 run Bison (*note Invoking Bison: Invocation.). We always define
728 `YYDEBUG' so that debugging is always possible.
730 The trace facility uses `stderr', so you must add
731 `#include <stdio.h>' to the C declarations section unless it is already
734 Once you have compiled the program with trace facilities, the way to
735 request a trace is to store a nonzero value in the variable `yydebug'.
736 You can do this by making the C code do it (in `main', perhaps), or you
737 can alter the value with a C debugger.
739 Each step taken by the parser when `yydebug' is nonzero produces a
740 line or two of trace information, written on `stderr'. The trace
741 messages tell you these things:
743 * Each time the parser calls `yylex', what kind of token was read.
745 * Each time a token is shifted, the depth and complete contents of
746 the state stack (*note Parser States::).
748 * Each time a rule is reduced, which rule it is, and the complete
749 contents of the state stack afterward.
751 To make sense of this information, it helps to refer to the listing
752 file produced by the Bison `-v' option (*note Invoking Bison:
753 Invocation.). This file shows the meaning of each state in terms of
754 positions in various rules, and also what each state will do with each
755 possible input token. As you read the successive trace messages, you
756 can see that the parser is functioning according to its specification
757 in the listing file. Eventually you will arrive at the place where
758 something undesirable happens, and you will see which parts of the
759 grammar are to blame.
761 The parser file is a C program and you can use C debuggers on it,
762 but it's not easy to interpret what it is doing. The parser function
763 is a finite-state machine interpreter, and aside from the actions it
764 executes the same code over and over. Only the values of variables
765 show where in the grammar it is working.
767 The debugging information normally gives the token type of each token
768 read, but not its semantic value. You can optionally define a macro
769 named `YYPRINT' to provide a way to print the value. If you define
770 `YYPRINT', it should take three arguments. The parser will pass a
771 standard I/O stream, the numeric code for the token type, and the token
772 value (from `yylval').
774 Here is an example of `YYPRINT' suitable for the multi-function
775 calculator (*note Declarations for `mfcalc': Mfcalc Decl.):
777 #define YYPRINT(file, type, value) yyprint (file, type, value)
780 yyprint (FILE *file, int type, YYSTYPE value)
783 fprintf (file, " %s", value.tptr->name);
784 else if (type == NUM)
785 fprintf (file, " %d", value.val);
789 File: bison.info, Node: Invocation, Next: Table of Symbols, Prev: Debugging, Up: Top
794 The usual way to invoke Bison is as follows:
798 Here INFILE is the grammar file name, which usually ends in `.y'.
799 The parser file's name is made by replacing the `.y' with `.tab.c'.
800 Thus, the `bison foo.y' filename yields `foo.tab.c', and the `bison
801 hack/foo.y' filename yields `hack/foo.tab.c'.
805 * Bison Options:: All the options described in detail,
806 in alphabetical order by short options.
807 * Environment Variables:: Variables which affect Bison execution.
808 * Option Cross Key:: Alphabetical list of long options.
809 * VMS Invocation:: Bison command syntax on VMS.
812 File: bison.info, Node: Bison Options, Next: Environment Variables, Up: Invocation
817 Bison supports both traditional single-letter options and mnemonic
818 long option names. Long option names are indicated with `--' instead of
819 `-'. Abbreviations for option names are allowed as long as they are
820 unique. When a long option takes an argument, like `--file-prefix',
821 connect the option name and the argument with `='.
823 Here is a list of options that can be used with Bison, alphabetized
824 by short option. It is followed by a cross key alphabetized by long
830 Print a summary of the command-line options to Bison and exit.
834 Print the version number of Bison and exit.
838 `--fixed-output-files'
839 Equivalent to `-o y.tab.c'; the parser output file is called
840 `y.tab.c', and the other outputs are called `y.output' and
841 `y.tab.h'. The purpose of this option is to imitate Yacc's output
842 file name conventions. Thus, the following shell script can
851 Specify the skeleton to use. You probably don't need this option
852 unless you are developing Bison.
856 Output a definition of the macro `YYDEBUG' into the parser file, so
857 that the debugging facilities are compiled. *Note Debugging Your
861 Pretend that `%locactions' was specified. *Note Decl Summary::.
864 `--name-prefix=PREFIX'
865 Rename the external symbols used in the parser so that they start
866 with PREFIX instead of `yy'. The precise list of symbols renamed
867 is `yyparse', `yylex', `yyerror', `yynerrs', `yylval', `yychar'
870 For example, if you use `-p c', the names become `cparse', `clex',
873 *Note Multiple Parsers in the Same Program: Multiple Parsers.
877 Don't put any `#line' preprocessor commands in the parser file.
878 Ordinarily Bison puts them in the parser file so that the C
879 compiler and debuggers will associate errors with your source
880 file, the grammar file. This option causes them to associate
881 errors with the parser file, treating it as an independent source
882 file in its own right.
886 Pretend that `%no_parser' was specified. *Note Decl Summary::.
890 Pretend that `%token_table' was specified. *Note Decl Summary::.
896 Pretend that `%verbose' was specified, i.e., write an extra output
897 file containing macro definitions for the token type names defined
898 in the grammar and the semantic value type `YYSTYPE', as well as a
899 few `extern' variable declarations. *Note Decl Summary::.
902 `--file-prefix=PREFIX'
903 Specify a prefix to use for all Bison output file names. The
904 names are chosen as if the input file were named `PREFIX.c'.
908 Pretend that `%verbose' was specified, i.e, write an extra output
909 file containing verbose descriptions of the grammar and parser.
910 *Note Decl Summary::, for more.
913 `--output-file=OUTFILE'
914 Specify the name OUTFILE for the parser file.
916 The other output files' names are constructed from OUTFILE as
917 described under the `-v' and `-d' options.
920 File: bison.info, Node: Environment Variables, Next: Option Cross Key, Prev: Bison Options, Up: Invocation
922 Environment Variables
923 =====================
925 Here is a list of environment variables which affect the way Bison
930 Much of the parser generated by Bison is copied verbatim from a
931 file called `bison.simple'. If Bison cannot find that file, or if
932 you would like to direct Bison to use a different copy, setting the
933 environment variable `BISON_SIMPLE' to the path of the file will
934 cause Bison to use that copy instead.
936 When the `%semantic_parser' declaration is used, Bison copies from
937 a file called `bison.hairy' instead. The location of this file can
938 also be specified or overridden in a similar fashion, with the
939 `BISON_HAIRY' environment variable.
942 File: bison.info, Node: Option Cross Key, Next: VMS Invocation, Prev: Environment Variables, Up: Invocation
947 Here is a list of options, alphabetized by long option, to help you
948 find the corresponding short option.
952 --file-prefix=PREFIX -b FILE-PREFIX
953 --fixed-output-files --yacc -y
955 --name-prefix=PREFIX -p NAME-PREFIX
958 --output-file=OUTFILE -o OUTFILE
964 File: bison.info, Node: VMS Invocation, Prev: Option Cross Key, Up: Invocation
966 Invoking Bison under VMS
967 ========================
969 The command line syntax for Bison on VMS is a variant of the usual
970 Bison command syntax--adapted to fit VMS conventions.
972 To find the VMS equivalent for any Bison option, start with the long
973 option, and substitute a `/' for the leading `--', and substitute a `_'
974 for each `-' in the name of the long option. For example, the
975 following invocation under VMS:
977 bison /debug/name_prefix=bar foo.y
979 is equivalent to the following command under POSIX.
981 bison --debug --name-prefix=bar foo.y
983 The VMS file system does not permit filenames such as `foo.tab.c'.
984 In the above example, the output file would instead be named
988 File: bison.info, Node: Table of Symbols, Next: Glossary, Prev: Invocation, Up: Top
994 A token name reserved for error recovery. This token may be used
995 in grammar rules so as to allow the Bison parser to recognize an
996 error in the grammar without halting the process. In effect, a
997 sentence containing an error may be recognized as valid. On a
998 parse error, the token `error' becomes the current look-ahead
999 token. Actions corresponding to `error' are then executed, and
1000 the look-ahead token is reset to the token that originally caused
1001 the violation. *Note Error Recovery::.
1004 Macro to pretend that an unrecoverable syntax error has occurred,
1005 by making `yyparse' return 1 immediately. The error reporting
1006 function `yyerror' is not called. *Note The Parser Function
1007 `yyparse': Parser Function.
1010 Macro to pretend that a complete utterance of the language has been
1011 read, by making `yyparse' return 0 immediately. *Note The Parser
1012 Function `yyparse': Parser Function.
1015 Macro to discard a value from the parser stack and fake a
1016 look-ahead token. *Note Special Features for Use in Actions:
1020 Macro to pretend that a syntax error has just been detected: call
1021 `yyerror' and then perform normal error recovery if possible
1022 (*note Error Recovery::), or (if recovery is impossible) make
1023 `yyparse' return 1. *Note Error Recovery::.
1026 Macro that you define with `#define' in the Bison declarations
1027 section to request verbose, specific error message strings when
1028 `yyerror' is called.
1031 Macro for specifying the initial size of the parser stack. *Note
1035 Macro for specifying an extra argument (or list of extra
1036 arguments) for `yyparse' to pass to `yylex'. *Note Calling
1037 Conventions for Pure Parsers: Pure Calling.
1040 Macro for the data type of `yylloc'; a structure with four
1041 members. *Note Textual Positions of Tokens: Token Positions.
1044 Default value for YYLTYPE.
1047 Macro for specifying the maximum size of the parser stack. *Note
1051 Macro for specifying the name of a parameter that `yyparse' should
1052 accept. *Note Calling Conventions for Pure Parsers: Pure Calling.
1055 Macro whose value indicates whether the parser is recovering from a
1056 syntax error. *Note Special Features for Use in Actions: Action
1060 Macro for the data type of semantic values; `int' by default.
1061 *Note Data Types of Semantic Values: Value Type.
1064 External integer variable that contains the integer value of the
1065 current look-ahead token. (In a pure parser, it is a local
1066 variable within `yyparse'.) Error-recovery rule actions may
1067 examine this variable. *Note Special Features for Use in Actions:
1071 Macro used in error-recovery rule actions. It clears the previous
1072 look-ahead token. *Note Error Recovery::.
1075 External integer variable set to zero by default. If `yydebug' is
1076 given a nonzero value, the parser will output information on input
1077 symbols and parser action. *Note Debugging Your Parser: Debugging.
1080 Macro to cause parser to recover immediately to its normal mode
1081 after a parse error. *Note Error Recovery::.
1084 User-supplied function to be called by `yyparse' on error. The
1085 function receives one argument, a pointer to a character string
1086 containing an error message. *Note The Error Reporting Function
1087 `yyerror': Error Reporting.
1090 User-supplied lexical analyzer function, called with no arguments
1091 to get the next token. *Note The Lexical Analyzer Function
1095 External variable in which `yylex' should place the semantic value
1096 associated with a token. (In a pure parser, it is a local
1097 variable within `yyparse', and its address is passed to `yylex'.)
1098 *Note Semantic Values of Tokens: Token Values.
1101 External variable in which `yylex' should place the line and column
1102 numbers associated with a token. (In a pure parser, it is a local
1103 variable within `yyparse', and its address is passed to `yylex'.)
1104 You can ignore this variable if you don't use the `@' feature in
1105 the grammar actions. *Note Textual Positions of Tokens: Token
1109 Global variable which Bison increments each time there is a parse
1110 error. (In a pure parser, it is a local variable within
1111 `yyparse'.) *Note The Error Reporting Function `yyerror': Error
1115 The parser function produced by Bison; call this function to start
1116 parsing. *Note The Parser Function `yyparse': Parser Function.
1119 Equip the parser for debugging. *Note Decl Summary::.
1122 Bison declaration to create a header file meant for the scanner.
1123 *Note Decl Summary::.
1126 Bison declaration to assign left associativity to token(s). *Note
1127 Operator Precedence: Precedence Decl.
1130 Bison declaration to avoid generating `#line' directives in the
1131 parser file. *Note Decl Summary::.
1134 Bison declaration to assign non-associativity to token(s). *Note
1135 Operator Precedence: Precedence Decl.
1138 Bison declaration to assign a precedence to a specific rule.
1139 *Note Context-Dependent Precedence: Contextual Precedence.
1142 Bison declaration to request a pure (reentrant) parser. *Note A
1143 Pure (Reentrant) Parser: Pure Decl.
1146 Bison declaration to assign right associativity to token(s).
1147 *Note Operator Precedence: Precedence Decl.
1150 Bison declaration to specify the start symbol. *Note The
1151 Start-Symbol: Start Decl.
1154 Bison declaration to declare token(s) without specifying
1155 precedence. *Note Token Type Names: Token Decl.
1158 Bison declaration to include a token name table in the parser file.
1159 *Note Decl Summary::.
1162 Bison declaration to declare nonterminals. *Note Nonterminal
1166 Bison declaration to specify several possible data types for
1167 semantic values. *Note The Collection of Value Types: Union Decl.
1169 These are the punctuation and delimiters used in Bison input:
1172 Delimiter used to separate the grammar rule section from the Bison
1173 declarations section or the additional C code section. *Note The
1174 Overall Layout of a Bison Grammar: Grammar Layout.
1177 All code listed between `%{' and `%}' is copied directly to the
1178 output file uninterpreted. Such code forms the "C declarations"
1179 section of the input file. *Note Outline of a Bison Grammar:
1183 Comment delimiters, as in C.
1186 Separates a rule's result from its components. *Note Syntax of
1187 Grammar Rules: Rules.
1190 Terminates a rule. *Note Syntax of Grammar Rules: Rules.
1193 Separates alternate rules for the same result nonterminal. *Note
1194 Syntax of Grammar Rules: Rules.
projects / bison.git / blob