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

* ChangeLog: For changes in doc/bison.texinfo, consistently reference

Browse Source 
node names: say "Table of Symbols" not "Bison Symbols", and say "Decl
Summary" not "Directives".
* doc/bison.texinfo (Decl Summary, Calc++ Parser): Cross-reference the
%code entry in "Decl Summary" rather than the one in "Table of Symbols"
since the former is now the more complete one.
(Prologue Alternatives): Likewise and do the same for %defines.
(Table of Symbols): Add summary of %code, add summary of %define, and
move full %code documentation to...
(Decl Summary): ... here for consistency with other entries in these
sections.
Move %define entry in order to keep this list alphabetized.
Reword %define entry a little to put less emphasis on the skeleton
concept, which most users shouldn't have to think about.
This commit is contained in:
Joel E. Denny
2007-01-27 23:34:16 +00:00
parent 665f0c2454
commit 148d66d861
2 changed files with 164 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
ChangeLog
View File

@@ -1,3 +1,20 @@
2007-01-27 Joel E. Denny <jdenny@ces.clemson.edu>
* ChangeLog: For changes in doc/bison.texinfo, consistently reference
node names: say "Table of Symbols" not "Bison Symbols", and say "Decl
Summary" not "Directives".
* doc/bison.texinfo (Decl Summary, Calc++ Parser): Cross-reference the
%code entry in "Decl Summary" rather than the one in "Table of Symbols"
since the former is now the more complete one.
(Prologue Alternatives): Likewise and do the same for %defines.
(Table of Symbols): Add summary of %code, add summary of %define, and
move full %code documentation to...
(Decl Summary): ... here for consistency with other entries in these
sections.
Move %define entry in order to keep this list alphabetized.
Reword %define entry a little to put less emphasis on the skeleton
concept, which most users shouldn't have to think about.
2007-01-26 Paul Eggert <eggert@cs.ucla.edu>
Adjust to recent gnulib changes.
@@ -18,7 +35,7 @@
* data/glr.cc: Likewise.
* data/location.cc: Use b4_percent_define_flag_if.
* doc/bison.texinfo (Directives): Document %define.
* doc/bison.texinfo (Decl Summary): Document %define.
* src/parse-gram.y (Unqualified %code): Change muscle name to
b4_percent_code().
@@ -200,7 +217,7 @@
(C++ Location Values): Update %define uses.
(Calc++ Parser Interface): Likewise.
(Calc++ Parser): Likewise, and update `%code requires' uses.
(Bison Symbols): Update %code documentation.
(Table of Symbols): Update %code documentation.
* src/parse-gram.y (prologue_declaration): For %define variables, use
`variable' instead of `STRING'.
(grammar_declaration): For %code qualifiers, use `ID' instead of
@@ -418,7 +435,7 @@
* doc/bison.texinfo (Prologue Alternatives): Update.
(Decl Summary): Update to %code "requires" and %code "provides".
(Calc++ Parser): Update to %code "requires".
(Bison Symbols): Remove entries for %requires, %provides, and
(Table of Symbols): Remove entries for %requires, %provides, and
%code-top. Rewrite %code entry, and add a %code "QUALIFIER" entry.
* data/bison.m4 (b4_user_provides, b4_user_requires): Remove as these
are replaced by b4_percent_code_provides and b4_percent_code_requires,
@@ -831,7 +848,7 @@
documentation instead.
(Calc++ Parser): Use `%require "@value{VERSION}"' rather than
`%require "2.3b"' so that the example is always up-to-date.
(Bison Symbols): Add entries for %language and %skeleton.
(Table of Symbols): Add entries for %language and %skeleton.
* examples/extexi (normalize): Instead of replacing every %require
argument with the current Bison version, just substitute for
`@value{VERSION}'. This guarantees that we're testing what actually
@@ -866,7 +883,7 @@
* doc/bison.texinfo (C++ Parser Interface): Prefer %language
over %skeleton.
(Directives): Document %language and %skeleton.
(Decl Summary): Document %language and %skeleton.
(Command line): Document -L.
* examples/extexi: Rewrite %require directive.
@@ -1067,7 +1084,7 @@
(2.3a): Annotate this entry to say the old forms of these features were
also experimental.
* doc/bison.texinfo (Prologue Alternatives, Freeing Discarded Symbols,
Bison Symbols): Say they're experimental. Comment out any mention
Table of Symbols): Say they're experimental. Comment out any mention
of Java (we'll want this back eventually).
2006-12-01 Joel E. Denny <jdenny@ces.clemson.edu>
@@ -1076,7 +1093,7 @@
%file-prefix, %name-prefix, and %output. Discussed at
<http://lists.gnu.org/archive/html/help-bison/2006-09/msg00001.html>.
* NEWS (2.3a+): Mention.
* doc/bison.texinfo (Decl Summary, Bison Symbols): Add entry for new
* doc/bison.texinfo (Decl Summary, Table of Symbols): Add entry for new
form of %defines, and remove `=' from entries for %file-prefix,
%name-prefix, and %output.
* src/parse-gram.y (prologue_declaration): Implement.
@@ -1106,7 +1123,7 @@
Rename <!> to <>. Discussed starting at
<http://lists.gnu.org/archive/html/bison-patches/2006-11/msg00039.html>.
* NEWS (2.3a+): Update.
* doc/bison.texinfo (Freeing Discarded Symbols, Bison Symbols):
* doc/bison.texinfo (Freeing Discarded Symbols, Table of Symbols):
Update.
* src/parse-gram.y (TYPE_TAG_NONE, generic_symlist_item): Implement.
* src/scan-gram.l (INITIAL): Implement.
@@ -1282,7 +1299,7 @@
* NEWS (2.3a+): Mention.
* doc/bison.texinfo (Freeing Discarded Symbols): Document this and the
previous change today related to mid-rules.
(Bison Symbols): Remove %symbol-default and add <*> and <!>.
(Table of Symbols): Remove %symbol-default and add <*> and <!>.
* src/parse-gram.y (PERCENT_SYMBOL_DEFAULT): Remove.
(TYPE_TAG_ANY): Add as <*>.
(TYPE_TAG_NONE): Add as <!>.
@@ -1375,8 +1392,8 @@
alternatives to...
(Prologue Alternatives): ... this new section, and extend it to discuss
all 4 directives in detail.
(Bison Symbols): Clean up discussion of prologue alternatives and add
%code-top.
(Table of Symbols): Clean up discussion of prologue alternatives and
add %code-top.
2006-10-16 Juan Manuel Guerrero <juan.guerrero@gmx.de>
@@ -1832,7 +1849,7 @@
<http://lists.gnu.org/archive/html/bison-patches/2006-09/msg00007.html>.
* NEWS (2.3+): Add %symbol-default to example.
* bison.texinfo (Freeing Discarded Symbols): Likewise.
(Bison Symbols): Add entry for %symbol-default.
(Table of Symbols): Add entry for %symbol-default.
* src/parse-gram.y (PERCENT_SYMBOL_DEFAULT): New token.
(generic_symlist, generic_symlist_item): New nonterminals for creating
a list in which each item is a symbol, semantic type, or
@@ -2474,7 +2491,7 @@
prologue blocks with %*-header declarations.
(Calc++ Parser): Likewise.
(Bison Declaration Summary): Update names.
(Bison Symbols): Update description.
(Table of Symbols): Update description.
* src/parse-gram.y (PERCENT_AFTER_DEFINITIONS): Update to...
(PERCENT_END_HEADER): ... this.
(PERCENT_BEFORE_DEFINITIONS): Update to...
@@ -2555,7 +2572,7 @@
file.
(Calc++ Parser): Forward declare driver in a %before-definitions rather
than in the pre-prologue so that make check succeeds.
(Bison Symbols): Add entries for %before-definitions and
(Table of Symbols): Add entries for %before-definitions and
%after-definitions.
* src/parse-gram.y (PERCENT_BEFORE_DEFINITIONS): New token for
%before-definitions.
@@ -3645,7 +3662,7 @@
in the yychar entry.
In the yychar entry, remove mention of the local yychar case (pure
parser) since this is irrelevant information when writing semantic
actions and since it's already discussed in `Bison Symbols' where
actions and since it's already discussed in `Table of Symbols' where
yychar is otherwise described as an external variable.
In the yychar entry, don't call it the `current' look-ahead since it
isn't when semantic actions are deferred.
@@ -3656,7 +3673,7 @@
`current' look-ahead, and do mention yylval and yylloc.
(Error Recovery): Cross-reference `Action Features' when mentioning
yyclearin.
(Bison Symbols): In the yychar entry, don't call it the `current'
(Table of Symbols): In the yychar entry, don't call it the `current'
look-ahead.
In the yylloc and yylval entries, mention look-ahead usage.

248
doc/bison.texinfo
View File

@@ -2695,7 +2695,7 @@ field, which identifies the purpose of the code and thus the location(s) where
Bison should generate it.
For C/C++, the qualifier can be omitted for the default location, or it can be
@code{requires}, @code{provides}, or @code{top}.
@xref{Table of Symbols,,Bison Symbols}.
@xref{Decl Summary,,%code}.
Look again at the example of the previous section:
@@ -2793,8 +2793,8 @@ parser source code file.
The first line after the warning is required by @code{YYSTYPE} and thus also
needs to appear in the parser source code file.
However, if you've instructed Bison to generate a parser header file
(@pxref{Table of Symbols, ,%defines}), you probably want that line to appear
before the @code{YYSTYPE} definition in that header file as well.
(@pxref{Decl Summary, ,%defines}), you probably want that line to appear before
the @code{YYSTYPE} definition in that header file as well.
The @code{YYLTYPE} definition should also appear in the parser header file to
override the default @code{YYLTYPE} definition there.
@@ -4569,12 +4569,129 @@ Declare the expected number of shift-reduce conflicts
In order to change the behavior of @command{bison}, use the following
directives:
@deffn {Directive} %code @{@var{code}@}
@findex %code
This is the unqualified form of the @code{%code} directive.
It inserts @var{code} verbatim at the default location in the output.
That default location is determined by the selected target language and/or
parser skeleton.
@cindex Prologue
For the current C/C++ skeletons, the default location is the parser source code
file after the usual contents of the parser header file.
Thus, @code{%code} replaces the traditional Yacc prologue,
@code{%@{@var{code}%@}}, for most purposes.
For a detailed discussion, see @ref{Prologue Alternatives}.
@comment For Java, the default location is inside the parser class.
(Like all the Yacc prologue alternatives, this directive is experimental.
More user feedback will help to determine whether it should become a permanent
feature.)
@end deffn
@deffn {Directive} %code @var{qualifier} @{@var{code}@}
This is the qualified form of the @code{%code} directive.
If you need to specify location-sensitive verbatim @var{code} that does not
belong at the default location selected by the unqualified @code{%code} form,
use this form instead.
@var{qualifier} identifies the purpose of @var{code} and thus the location(s)
where Bison should generate it.
Not all values of @var{qualifier} are available for all target languages:
@itemize @bullet
@findex %code requires
@item requires
@itemize @bullet
@item Language(s): C, C++
@item Purpose: This is the best place to write dependency code required for
@code{YYSTYPE} and @code{YYLTYPE}.
In other words, it's the best place to define types referenced in @code{%union}
directives, and it's the best place to override Bison's default @code{YYSTYPE}
and @code{YYLTYPE} definitions.
@item Location(s): The parser header file and the parser source code file
before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
@end itemize
@item provides
@findex %code provides
@itemize @bullet
@item Language(s): C, C++
@item Purpose: This is the best place to write additional definitions and
declarations that should be provided to other modules.
@item Location(s): The parser header file and the parser source code file after
the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
@end itemize
@item top
@findex %code top
@itemize @bullet
@item Language(s): C, C++
@item Purpose: The unqualified @code{%code} or @code{%code requires} should
usually be more appropriate than @code{%code top}.
However, occasionally it is necessary to insert code much nearer the top of the
parser source code file.
For example:
@smallexample
%code top @{
#define _GNU_SOURCE
#include <stdio.h>
@}
@end smallexample
@item Location(s): Near the top of the parser source code file.
@end itemize
@ignore
@item imports
@findex %code imports
@itemize @bullet
@item Language(s): Java
@item Purpose: This is the best place to write Java import directives.
@item Location(s): The parser Java file after any Java package directive and
before any class definitions.
@end itemize
@end ignore
@end itemize
(Like all the Yacc prologue alternatives, this directive is experimental.
More user feedback will help to determine whether it should become a permanent
feature.)
@cindex Prologue
For a detailed discussion of how to use @code{%code} in place of the
traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
@end deffn
@deffn {Directive} %debug
In the parser file, define the macro @code{YYDEBUG} to 1 if it is not
already defined, so that the debugging facilities are compiled.
@end deffn
@xref{Tracing, ,Tracing Your Parser}.
@deffn {Directive} %define @var{define-variable}
@deffnx {Directive} %define @var{define-variable} @var{value}
Define a variable to adjust Bison's behavior.
The list of available variables and their meanings depends on the selected
target language and/or the parser skeleton (@pxref{Decl Summary,,%language}).
The @var{value} can be omitted for boolean variables; for
boolean variables, the skeletons will treat a @var{value} of @samp{0}
or @samp{false} as the boolean variable being false, and anything else
as true.
@end deffn
@deffn {Directive} %defines
Write a header file containing macro definitions for the token type
names defined in the grammar as well as a few other declarations.
@@ -4612,16 +4729,7 @@ Tokens}.
@findex %code provides
If you have declared @code{%code requires} or @code{%code provides}, the output
header also contains their code.
@xref{Table of Symbols, ,%code}.
@end deffn
@deffn {Directive} %define @var{define-variable}
@deffnx {Directive} %define @var{define-variable} @var{value}
Define a variable to be used by the skeleton in order to adjust its
behavior. The @var{value} can be omitted for boolean variables; for
boolean variables, the skeletons will treat a @var{value} of @samp{0}
or @samp{false} as the boolean variable being false, and anything else
as true.
@xref{Decl Summary, ,%code}.
@end deffn
@deffn {Directive} %defines @var{defines-file}
@@ -7903,7 +8011,7 @@ reciprocally, both cannot include the header of the other. Because the
driver's header needs detailed knowledge about the parser class (in
particular its inner types), it is the parser's header which will simply
use a forward declaration of the driver.
@xref{Table of Symbols, ,%code}.
@xref{Decl Summary, ,%code}.
@comment file: calc++-parser.yy
@example
@@ -8669,109 +8777,9 @@ Start-Symbol}. It cannot be used in the grammar.
@end deffn
@deffn {Directive} %code @{@var{code}@}
@findex %code
This is the unqualified form of the @code{%code} directive.
It inserts @var{code} verbatim at the default location in the output.
That default location is determined by the selected target language and/or
parser skeleton.
@cindex Prologue
For the current C/C++ skeletons, the default location is the parser source code
file after the usual contents of the parser header file.
Thus, @code{%code} replaces the traditional Yacc prologue,
@code{%@{@var{code}%@}}, for most purposes.
For a detailed discussion, see @ref{Prologue Alternatives}.
@comment For Java, the default location is inside the parser class.
(Like all the Yacc prologue alternatives, this directive is experimental.
More user feedback will help to determine whether it should become a permanent
feature.)
@end deffn
@deffn {Directive} %code @var{qualifier} @{@var{code}@}
This is the qualified form of the @code{%code} directive.
If you need to specify location-sensitive verbatim @var{code} that does not
belong at the default location selected by the unqualified @code{%code} form,
use this form instead.
@var{qualifier} identifies the purpose of @var{code} and thus the location(s)
where Bison should generate it.
Not all values of @var{qualifier} are available for all target languages:
@itemize @bullet
@findex %code requires
@item requires
@itemize @bullet
@item Language(s): C, C++
@item Purpose: This is the best place to write dependency code required for
@code{YYSTYPE} and @code{YYLTYPE}.
In other words, it's the best place to define types referenced in @code{%union}
directives, and it's the best place to override Bison's default @code{YYSTYPE}
and @code{YYLTYPE} definitions.
@item Location(s): The parser header file and the parser source code file
before the Bison-generated @code{YYSTYPE} and @code{YYLTYPE} definitions.
@end itemize
@item provides
@findex %code provides
@itemize @bullet
@item Language(s): C, C++
@item Purpose: This is the best place to write additional definitions and
declarations that should be provided to other modules.
@item Location(s): The parser header file and the parser source code file after
the Bison-generated @code{YYSTYPE}, @code{YYLTYPE}, and token definitions.
@end itemize
@item top
@findex %code top
@itemize @bullet
@item Language(s): C, C++
@item Purpose: The unqualified @code{%code} or @code{%code requires} should
usually be more appropriate than @code{%code top}.
However, occasionally it is necessary to insert code much nearer the top of the
parser source code file.
For example:
@smallexample
%code top @{
#define _GNU_SOURCE
#include <stdio.h>
@}
@end smallexample
@item Location(s): Near the top of the parser source code file.
@end itemize
@ignore
@item imports
@findex %code imports
@itemize @bullet
@item Language(s): Java
@item Purpose: This is the best place to write Java import directives.
@item Location(s): The parser Java file after any Java package directive and
before any class definitions.
@end itemize
@end ignore
@end itemize
(Like all the Yacc prologue alternatives, this directive is experimental.
More user feedback will help to determine whether it should become a permanent
feature.)
@cindex Prologue
For a detailed discussion of how to use @code{%code} in place of the
traditional Yacc prologue for C/C++, see @ref{Prologue Alternatives}.
@deffnx {Directive} %code @var{qualifier} @{@var{code}@}
Insert @var{code} verbatim into output parser source.
@xref{Decl Summary,,%code}.
@end deffn
@deffn {Directive} %debug
@@ -8790,6 +8798,12 @@ Precedence}.
@end deffn
@end ifset
@deffn {Directive} %define @var{define-variable}
@deffnx {Directive} %define @var{define-variable} @var{value}
Define a variable to adjust Bison's behavior.
@xref{Decl Summary,,%define}.
@end deffn
@deffn {Directive} %defines
Bison declaration to create a header file meant for the scanner.
@xref{Decl Summary}.