Future/bison
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/bison.git synced 2026-03-21 18:23:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: formatting changes

Browse Source 
* doc/bison.texi: here.
This commit is contained in:
Akim Demaille
2018-11-28 13:07:04 +01:00
parent 23e022718b
commit ebe9b20841
1 changed files with 53 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
doc/bison.texi
View File

@@ -2952,31 +2952,30 @@ Look again at the example of the previous section:
@end example @end example
@noindent @noindent
Notice that there are two @var{Prologue} sections here, but there's a Notice that there are two @var{Prologue} sections here, but there's a subtle
subtle distinction between their functionality. For example, if you distinction between their functionality. For example, if you decide to
decide to override Bison's default definition for @code{YYLTYPE}, in override Bison's default definition for @code{YYLTYPE}, in which
which @var{Prologue} section should you write your new definition? @var{Prologue} section should you write your new definition? You should
You should write it in the first since Bison will insert that code write it in the first since Bison will insert that code into the parser
into the parser implementation file @emph{before} the default implementation file @emph{before} the default @code{YYLTYPE} definition. In
@code{YYLTYPE} definition. In which @var{Prologue} section should you which @var{Prologue} section should you prototype an internal function,
prototype an internal function, @code{trace_token}, that accepts @code{trace_token}, that accepts @code{YYLTYPE} and @code{yytokentype} as
@code{YYLTYPE} and @code{yytokentype} as arguments? You should arguments? You should prototype it in the second since Bison will insert
prototype it in the second since Bison will insert that code that code @emph{after} the @code{YYLTYPE} and @code{yytokentype}
@emph{after} the @code{YYLTYPE} and @code{yytokentype} definitions. definitions.
This distinction in functionality between the two @var{Prologue} sections is This distinction in functionality between the two @var{Prologue} sections is
established by the appearance of the @code{%union} between them. established by the appearance of the @code{%union} between them. This
This behavior raises a few questions. behavior raises a few questions. First, why should the position of a
First, why should the position of a @code{%union} affect definitions related to @code{%union} affect definitions related to @code{YYLTYPE} and
@code{YYLTYPE} and @code{yytokentype}? @code{yytokentype}? Second, what if there is no @code{%union}? In that
Second, what if there is no @code{%union}? case, the second kind of @var{Prologue} section is not available. This
In that case, the second kind of @var{Prologue} section is not available. behavior is not intuitive.
This behavior is not intuitive.
To avoid this subtle @code{%union} dependency, rewrite the example using a To avoid this subtle @code{%union} dependency, rewrite the example using a
@code{%code top} and an unqualified @code{%code}. @code{%code top} and an unqualified @code{%code}. Let's go ahead and add
Let's go ahead and add the new @code{YYLTYPE} definition and the the new @code{YYLTYPE} definition and the @code{trace_token} prototype at
@code{trace_token} prototype at the same time: the same time:
@example @example
%code top @{ %code top @{
@@ -3084,36 +3083,33 @@ Thus, they belong in one or more @code{%code requires}:
@end example @end example
@noindent @noindent
Now Bison will insert @code{#include "ptypes.h"} and the new Now Bison will insert @code{#include "ptypes.h"} and the new @code{YYLTYPE}
@code{YYLTYPE} definition before the Bison-generated @code{YYSTYPE} definition before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE}
and @code{YYLTYPE} definitions in both the parser implementation file definitions in both the parser implementation file and the parser header
and the parser header file. (By the same reasoning, @code{%code file. (By the same reasoning, @code{%code requires} would also be the
requires} would also be the appropriate place to write your own appropriate place to write your own definition for @code{YYSTYPE}.)
definition for @code{YYSTYPE}.)
When you are writing dependency code for @code{YYSTYPE} and When you are writing dependency code for @code{YYSTYPE} and @code{YYLTYPE},
@code{YYLTYPE}, you should prefer @code{%code requires} over you should prefer @code{%code requires} over @code{%code top} regardless of
@code{%code top} regardless of whether you instruct Bison to generate whether you instruct Bison to generate a parser header file. When you are
a parser header file. When you are writing code that you need Bison writing code that you need Bison to insert only into the parser
to insert only into the parser implementation file and that has no implementation file and that has no special need to appear at the top of
special need to appear at the top of that file, you should prefer the that file, you should prefer the unqualified @code{%code} over @code{%code
unqualified @code{%code} over @code{%code top}. These practices will top}. These practices will make the purpose of each block of your code
make the purpose of each block of your code explicit to Bison and to explicit to Bison and to other developers reading your grammar file.
other developers reading your grammar file. Following these Following these practices, we expect the unqualified @code{%code} and
practices, we expect the unqualified @code{%code} and @code{%code @code{%code requires} to be the most important of the four @var{Prologue}
requires} to be the most important of the four @var{Prologue}
alternatives. alternatives.
At some point while developing your parser, you might decide to At some point while developing your parser, you might decide to provide
provide @code{trace_token} to modules that are external to your @code{trace_token} to modules that are external to your parser. Thus, you
parser. Thus, you might wish for Bison to insert the prototype into might wish for Bison to insert the prototype into both the parser header
both the parser header file and the parser implementation file. Since file and the parser implementation file. Since this function is not a
this function is not a dependency required by @code{YYSTYPE} or dependency required by @code{YYSTYPE} or @code{YYLTYPE}, it doesn't make
@code{YYLTYPE}, it doesn't make sense to move its prototype to a sense to move its prototype to a @code{%code requires}. More importantly,
@code{%code requires}. More importantly, since it depends upon since it depends upon @code{YYLTYPE} and @code{yytokentype}, @code{%code
@code{YYLTYPE} and @code{yytokentype}, @code{%code requires} is not requires} is not sufficient. Instead, move its prototype from the
sufficient. Instead, move its prototype from the unqualified unqualified @code{%code} to a @code{%code provides}:
@code{%code} to a @code{%code provides}:
@example @example
@group @group
@@ -3166,18 +3162,16 @@ sufficient. Instead, move its prototype from the unqualified
@end example @end example
@noindent @noindent
Bison will insert the @code{trace_token} prototype into both the Bison will insert the @code{trace_token} prototype into both the parser
parser header file and the parser implementation file after the header file and the parser implementation file after the definitions for
definitions for @code{yytokentype}, @code{YYLTYPE}, and @code{yytokentype}, @code{YYLTYPE}, and @code{YYSTYPE}.
@code{YYSTYPE}.
The above examples are careful to write directives in an order that The above examples are careful to write directives in an order that reflects
reflects the layout of the generated parser implementation and header the layout of the generated parser implementation and header files:
files: @code{%code top}, @code{%code requires}, @code{%code provides}, @code{%code top}, @code{%code requires}, @code{%code provides}, and then
and then @code{%code}. While your grammar files may generally be @code{%code}. While your grammar files may generally be easier to read if
easier to read if you also follow this order, Bison does not require you also follow this order, Bison does not require it. Instead, Bison lets
it. Instead, Bison lets you choose an organization that makes sense you choose an organization that makes sense to you.
to you.
You may declare any of these directives multiple times in the grammar file. You may declare any of these directives multiple times in the grammar file.
In that case, Bison concatenates the contained code in declaration order. In that case, Bison concatenates the contained code in declaration order.