]> git.saurik.com Git - bison.git/blobdiff - doc/bison.texi
doc: introduce %empty and -Wempty-rule
[bison.git] / doc / bison.texi
index 8d7bb437a8304f7ce3b09bf3d013841963c43b89..cbae43e543fc5ed42098619d21dad2e158f4c610 100644 (file)
@@ -186,7 +186,6 @@ Bison Grammar Files
 * Grammar Outline::    Overall layout of the grammar file.
 * Symbols::            Terminal and nonterminal symbols.
 * Rules::              How to write grammar rules.
 * Grammar Outline::    Overall layout of the grammar file.
 * Symbols::            Terminal and nonterminal symbols.
 * Rules::              How to write grammar rules.
-* Recursion::          Writing recursive rules.
 * Semantics::          Semantic values and actions.
 * Tracking Locations:: Locations and actions.
 * Named References::   Using named references in actions.
 * Semantics::          Semantic values and actions.
 * Tracking Locations:: Locations and actions.
 * Named References::   Using named references in actions.
@@ -201,6 +200,13 @@ Outline of a Bison Grammar
 * Grammar Rules::         Syntax and usage of the grammar rules section.
 * Epilogue::              Syntax and usage of the epilogue.
 
 * Grammar Rules::         Syntax and usage of the grammar rules section.
 * Epilogue::              Syntax and usage of the epilogue.
 
+Grammar Rules
+
+* Rules Syntax::   Syntax of the rules.
+* Empty Rules::    Symbols that can match the empty string.
+* Recursion::      Writing recursive rules.
+
+
 Defining Language Semantics
 
 * Value Type::        Specifying one data type for all semantic values.
 Defining Language Semantics
 
 * Value Type::        Specifying one data type for all semantic values.
@@ -1538,6 +1544,7 @@ calculator.  As in C, comments are placed between @samp{/*@dots{}*/}.
 @example
 /* Reverse polish notation calculator.  */
 
 @example
 /* Reverse polish notation calculator.  */
 
+@group
 %@{
   #define YYSTYPE double
   #include <stdio.h>
 %@{
   #define YYSTYPE double
   #include <stdio.h>
@@ -1545,6 +1552,7 @@ calculator.  As in C, comments are placed between @samp{/*@dots{}*/}.
   int yylex (void);
   void yyerror (char const *);
 %@}
   int yylex (void);
   void yyerror (char const *);
 %@}
+@end group
 
 %token NUM
 
 
 %token NUM
 
@@ -2411,7 +2419,7 @@ Here are the C and Bison declarations for the multi-function calculator.
 %type  <val>  exp
 
 @group
 %type  <val>  exp
 
 @group
-%right '='
+%precedence '='
 %left '-' '+'
 %left '*' '/'
 %precedence NEG /* negation--unary minus */
 %left '-' '+'
 %left '*' '/'
 %precedence NEG /* negation--unary minus */
@@ -2787,7 +2795,6 @@ The Bison grammar file conventionally has a name ending in @samp{.y}.
 * Grammar Outline::    Overall layout of the grammar file.
 * Symbols::            Terminal and nonterminal symbols.
 * Rules::              How to write grammar rules.
 * Grammar Outline::    Overall layout of the grammar file.
 * Symbols::            Terminal and nonterminal symbols.
 * Rules::              How to write grammar rules.
-* Recursion::          Writing recursive rules.
 * Semantics::          Semantic values and actions.
 * Tracking Locations:: Locations and actions.
 * Named References::   Using named references in actions.
 * Semantics::          Semantic values and actions.
 * Tracking Locations:: Locations and actions.
 * Named References::   Using named references in actions.
@@ -2857,21 +2864,27 @@ can be done with two @var{Prologue} blocks, one before and one after the
 @code{%union} declaration.
 
 @example
 @code{%union} declaration.
 
 @example
+@group
 %@{
   #define _GNU_SOURCE
   #include <stdio.h>
   #include "ptypes.h"
 %@}
 %@{
   #define _GNU_SOURCE
   #include <stdio.h>
   #include "ptypes.h"
 %@}
+@end group
 
 
+@group
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
+@end group
 
 
+@group
 %@{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
 %@}
 %@{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
 %@}
+@end group
 
 @dots{}
 @end example
 
 @dots{}
 @end example
@@ -2903,21 +2916,27 @@ location, or it can be one of @code{requires}, @code{provides},
 Look again at the example of the previous section:
 
 @example
 Look again at the example of the previous section:
 
 @example
+@group
 %@{
   #define _GNU_SOURCE
   #include <stdio.h>
   #include "ptypes.h"
 %@}
 %@{
   #define _GNU_SOURCE
   #include <stdio.h>
   #include "ptypes.h"
 %@}
+@end group
 
 
+@group
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
+@end group
 
 
+@group
 %@{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
 %@}
 %@{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
 %@}
+@end group
 
 @dots{}
 @end example
 
 @dots{}
 @end example
@@ -2969,16 +2988,20 @@ Let's go ahead and add the new @code{YYLTYPE} definition and the
   @} YYLTYPE;
 @}
 
   @} YYLTYPE;
 @}
 
+@group
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
 %union @{
   long int n;
   tree t;  /* @r{@code{tree} is defined in @file{ptypes.h}.} */
 @}
+@end group
 
 
+@group
 %code @{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
   static void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
 %code @{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
   static void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
+@end group
 
 @dots{}
 @end example
 
 @dots{}
 @end example
@@ -3389,7 +3412,18 @@ value of the error token is 256, unless you explicitly assigned 256 to
 one of your tokens with a @code{%token} declaration.
 
 @node Rules
 one of your tokens with a @code{%token} declaration.
 
 @node Rules
-@section Syntax of Grammar Rules
+@section Grammar Rules
+
+A Bison grammar is a list of rules.
+
+@menu
+* Rules Syntax::   Syntax of the rules.
+* Empty Rules::    Symbols that can match the empty string.
+* Recursion::      Writing recursive rules.
+@end menu
+
+@node Rules Syntax
+@subsection Syntax of Grammar Rules
 @cindex rule syntax
 @cindex grammar rule syntax
 @cindex syntax of grammar rules
 @cindex rule syntax
 @cindex grammar rule syntax
 @cindex syntax of grammar rules
@@ -3463,33 +3497,57 @@ be joined with the vertical-bar character @samp{|} as follows:
 @noindent
 They are still considered distinct rules even when joined in this way.
 
 @noindent
 They are still considered distinct rules even when joined in this way.
 
-If @var{components} in a rule is empty, it means that @var{result} can
-match the empty string.  For example, here is how to define a
-comma-separated sequence of zero or more @code{exp} groupings:
+@node Empty Rules
+@subsection Empty Rules
+@cindex empty rule
+@cindex rule, empty
+@findex %empty
+
+A rule is said to be @dfn{empty} if its right-hand side (@var{components})
+is empty.  It means that @var{result} can match the empty string.  For
+example, here is how to define an optional semicolon:
+
+@example
+semicolon.opt: | ";";
+@end example
+
+@noindent
+It is easy not to see an empty rule, especially when @code{|} is used.  The
+@code{%empty} directive allows to make explicit that a rule is empty on
+purpose:
 
 @example
 @group
 
 @example
 @group
-expseq:
-  /* empty */
-| expseq1
+semicolon.opt:
+  %empty
+| ";"
 ;
 @end group
 ;
 @end group
+@end example
+
+Flagging a non-empty rule with @code{%empty} is an error.  If run with
+@option{-Wempty-rule}, @command{bison} will report empty rules without
+@code{%empty}.  Using @code{%empty} enables this warning, unless
+@option{-Wno-empty-rule} was specified.
 
 
+The @code{%empty} directive is a Bison extension, it does not work with
+Yacc.  To remain compatible with POSIX Yacc, it is customary to write a
+comment @samp{/* empty */} in each rule with no components:
+
+@example
 @group
 @group
-expseq1:
-  exp
-| expseq1 ',' exp
+semicolon.opt:
+  /* empty */
+| ";"
 ;
 @end group
 @end example
 
 ;
 @end group
 @end example
 
-@noindent
-It is customary to write a comment @samp{/* empty */} in each rule
-with no components.
 
 @node Recursion
 
 @node Recursion
-@section Recursive Rules
+@subsection Recursive Rules
 @cindex recursive rule
 @cindex recursive rule
+@cindex rule, recursive
 
 A rule is called @dfn{recursive} when its @var{result} nonterminal
 appears also on its right hand side.  Nearly all Bison grammars need to
 
 A rule is called @dfn{recursive} when its @var{result} nonterminal
 appears also on its right hand side.  Nearly all Bison grammars need to
@@ -3916,16 +3974,20 @@ declare a destructor for that symbol:
 @group
 %type <context> let
 %destructor @{ pop_context ($$); @} let
 @group
 %type <context> let
 %destructor @{ pop_context ($$); @} let
+@end group
 
 %%
 
 
 %%
 
+@group
 stmt:
   let stmt
     @{
       $$ = $2;
       pop_context ($let);
     @};
 stmt:
   let stmt
     @{
       $$ = $2;
       pop_context ($let);
     @};
+@end group
 
 
+@group
 let:
   "let" '(' var ')'
     @{
 let:
   "let" '(' var ')'
     @{
@@ -9716,6 +9778,72 @@ no effect on the conflict report.
 Deprecated constructs whose support will be removed in future versions of
 Bison.
 
 Deprecated constructs whose support will be removed in future versions of
 Bison.
 
+@item empty-rule
+Empty rules without @code{%empty}.  @xref{Empty Rules}.  Disabled by
+default, but enabled by uses of @code{%empty}, unless
+@option{-Wno-empty-rule} was specified.
+
+@item precedence
+Useless precedence and associativity directives.  Disabled by default.
+
+Consider for instance the following grammar:
+
+@example
+@group
+%nonassoc "="
+%left "+"
+%left "*"
+%precedence "("
+@end group
+%%
+@group
+stmt:
+  exp
+| "var" "=" exp
+;
+@end group
+
+@group
+exp:
+  exp "+" exp
+| exp "*" "num"
+| "(" exp ")"
+| "num"
+;
+@end group
+@end example
+
+Bison reports:
+
+@c cannot leave the location and the [-Wprecedence] for lack of
+@c width in PDF.
+@example
+@group
+warning: useless precedence and associativity for "="
+ %nonassoc "="
+           ^^^
+@end group
+@group
+warning: useless associativity for "*", use %precedence
+ %left "*"
+       ^^^
+@end group
+@group
+warning: useless precedence for "("
+ %precedence "("
+             ^^^
+@end group
+@end example
+
+One would get the exact same parser with the following directives instead:
+
+@example
+@group
+%left "+"
+%precedence "*"
+@end group
+@end example
+
 @item other
 All warnings not categorized above.  These warnings are enabled by default.
 
 @item other
 All warnings not categorized above.  These warnings are enabled by default.
 
@@ -10207,14 +10335,6 @@ therefore, since, as far as we know, @code{double} is the most demanding
 type on all platforms, alignments are enforced for @code{double} whatever
 types are actually used.  This may waste space in some cases.
 
 type on all platforms, alignments are enforced for @code{double} whatever
 types are actually used.  This may waste space in some cases.
 
-@item
-Our implementation is not conforming with strict aliasing rules.  Alias
-analysis is a technique used in optimizing compilers to detect when two
-pointers are disjoint (they cannot ``meet'').  Our implementation breaks
-some of the rules that G++ 4.4 uses in its alias analysis, so @emph{strict
-alias analysis must be disabled}.  Use the option
-@option{-fno-strict-aliasing} to compile the generated parser.
-
 @item
 There might be portability issues we are not aware of.
 @end itemize
 @item
 There might be portability issues we are not aware of.
 @end itemize
@@ -12357,6 +12477,11 @@ time to resolve reduce/reduce conflicts.  @xref{GLR Parsers, ,Writing
 GLR Parsers}.
 @end deffn
 
 GLR Parsers}.
 @end deffn
 
+@deffn {Directive} %empty
+Bison declaration to declare make explicit that a rule has an empty
+right-hand side.  @xref{Empty Rules}.
+@end deffn
+
 @deffn {Symbol} $end
 The predefined token marking the end of the token stream.  It cannot be
 used in the grammar.
 @deffn {Symbol} $end
 The predefined token marking the end of the token stream.  It cannot be
 used in the grammar.