mirror of
https://git.savannah.gnu.org/git/bison.git
synced 2026-03-09 12:23:04 +00:00
Merge remote-tracking branch 'origin/maint'
* origin/maint: (46 commits) doc: minor style change maint: use gendocs's new -I option regen yacc.c: do not define location support when not using locations maint: be compilable with GCC 4.0 tests: address a warning from GCC 4.4 tests: don't use options that Clang does not support tests: restore the tests on -Werror regen parse-gram: update the Bison interface fix comment maint: post-release administrivia version 2.6.4 regen 2.6.4: botched 2.6.3 maint: post-release administrivia version 2.6.3 gnulib: update tests: check %no-lines NEWS: warnings with clang ... Conflicts: NEWS TODO data/c.m4 data/java.m4 doc/Makefile.am src/getargs.c src/getargs.h src/output.c src/parse-gram.c src/parse-gram.h src/parse-gram.y src/reader.h
This commit is contained in:
Akim Demaille
112
doc/bison.texi
112
doc/bison.texi
@@ -298,6 +298,7 @@ Handling Context Dependencies
|
||||
Debugging Your Parser
|
||||
|
||||
* Understanding:: Understanding the structure of your parser.
|
||||
* Graphviz:: Getting a visual representation of the parser.
|
||||
* Tracing:: Tracing the execution of your parser.
|
||||
|
||||
Tracing Your Parser
|
||||
@@ -8422,6 +8423,7 @@ automaton, and how to enable and understand the parser run-time traces.
|
||||
|
||||
@menu
|
||||
* Understanding:: Understanding the structure of your parser.
|
||||
* Graphviz:: Getting a visual representation of the parser.
|
||||
* Tracing:: Tracing the execution of your parser.
|
||||
@end menu
|
||||
|
||||
@@ -8838,6 +8840,114 @@ precedence of @samp{/} with respect to @samp{+}, @samp{-}, and
|
||||
@samp{*}, but also because the
|
||||
associativity of @samp{/} is not specified.
|
||||
|
||||
@c ================================================= Graphical Representation
|
||||
|
||||
@node Graphviz
|
||||
@section Visualizing Your Parser
|
||||
@cindex dot
|
||||
|
||||
As another means to gain better understanding of the shift/reduce
|
||||
automaton corresponding to the Bison parser, a DOT file can be generated. Note
|
||||
that debugging a real grammar with this is tedious at best, and impractical
|
||||
most of the times, because the generated files are huge (the generation of
|
||||
a PDF or PNG file from it will take very long, and more often than not it will
|
||||
fail due to memory exhaustion). This option was rather designed for beginners,
|
||||
to help them understand LR parsers.
|
||||
|
||||
This file is generated when the @option{--graph} option is specified (see
|
||||
@pxref{Invocation, , Invoking Bison}). Its name is made by removing
|
||||
@samp{.tab.c} or @samp{.c} from the parser implementation file name, and
|
||||
adding @samp{.dot} instead. If the grammar file is @file{foo.y}, the
|
||||
Graphviz output file is called @file{foo.dot}.
|
||||
|
||||
The following grammar file, @file{rr.y}, will be used in the sequel:
|
||||
|
||||
@example
|
||||
%%
|
||||
@group
|
||||
exp: a ";" | b ".";
|
||||
a: "0";
|
||||
b: "0";
|
||||
@end group
|
||||
@end example
|
||||
|
||||
The graphical output is very similar to the textual one, and as such it is
|
||||
easier understood by making direct comparisons between them. See
|
||||
@ref{Debugging, , Debugging Your Parser} for a detailled analysis of the
|
||||
textual report.
|
||||
|
||||
@subheading Graphical Representation of States
|
||||
|
||||
The items (pointed rules) for each state are grouped together in graph nodes.
|
||||
Their numbering is the same as in the verbose file. See the following points,
|
||||
about transitions, for examples
|
||||
|
||||
When invoked with @option{--report=lookaheads}, the lookahead tokens, when
|
||||
needed, are shown next to the relevant rule between square brackets as a
|
||||
comma separated list. This is the case in the figure for the representation of
|
||||
reductions, below.
|
||||
|
||||
@sp 1
|
||||
|
||||
The transitions are represented as directed edges between the current and
|
||||
the target states.
|
||||
|
||||
@subheading Graphical Representation of Shifts
|
||||
|
||||
Shifts are shown as solid arrows, labelled with the lookahead token for that
|
||||
shift. The following describes a reduction in the @file{rr.output} file:
|
||||
|
||||
@example
|
||||
@group
|
||||
state 3
|
||||
|
||||
1 exp: a . ";"
|
||||
|
||||
";" shift, and go to state 6
|
||||
@end group
|
||||
@end example
|
||||
|
||||
A Graphviz rendering of this portion of the graph could be:
|
||||
|
||||
@center @image{figs/example-shift, 100pt}
|
||||
|
||||
@subheading Graphical Representation of Reductions
|
||||
|
||||
Reductions are shown as solid arrows, leading to a diamond-shaped node
|
||||
bearing the number of the reduction rule. The arrow is labelled with the
|
||||
appropriate comma separated lookahead tokens. If the reduction is the default
|
||||
action for the given state, there is no such label.
|
||||
|
||||
This is how reductions are represented in the verbose file @file{rr.output}:
|
||||
@example
|
||||
state 1
|
||||
|
||||
3 a: "0" . [";"]
|
||||
4 b: "0" . ["."]
|
||||
|
||||
"." reduce using rule 4 (b)
|
||||
$default reduce using rule 3 (a)
|
||||
@end example
|
||||
|
||||
A Graphviz rendering of this portion of the graph could be:
|
||||
|
||||
@center @image{figs/example-reduce, 120pt}
|
||||
|
||||
When unresolved conflicts are present, because in deterministic parsing
|
||||
a single decision can be made, Bison can arbitrarily choose to disable a
|
||||
reduction, see @ref{Shift/Reduce, , Shift/Reduce Conflicts}. Discarded actions
|
||||
are distinguished by a red filling color on these nodes, just like how they are
|
||||
reported between square brackets in the verbose file.
|
||||
|
||||
The reduction corresponding to the rule number 0 is the acceptation state. It
|
||||
is shown as a blue diamond, labelled "Acc".
|
||||
|
||||
@subheading Graphical representation of go tos
|
||||
|
||||
The @samp{go to} jump transitions are represented as dotted lines bearing
|
||||
the name of the rule being jumped to.
|
||||
|
||||
@c ================================================= Tracing
|
||||
|
||||
@node Tracing
|
||||
@section Tracing Your Parser
|
||||
@@ -12580,9 +12690,9 @@ London, Department of Computer Science, TR-00-12 (December 2000).
|
||||
@c LocalWords: subdirectory Solaris nonassociativity perror schemas Malloy ints
|
||||
@c LocalWords: Scannerless ispell american ChangeLog smallexample CSTYPE CLTYPE
|
||||
@c LocalWords: clval CDEBUG cdebug deftypeopx yyterminate LocationType
|
||||
@c LocalWords: errorVerbose
|
||||
|
||||
@c Local Variables:
|
||||
@c ispell-dictionary: "american"
|
||||
@c fill-column: 76
|
||||
@c End:
|
||||
@c LocalWords: errorVerbose
|
||||
|
||||
11
doc/figs/example-reduce.dot
Normal file
11
doc/figs/example-reduce.dot
Normal file
@@ -0,0 +1,11 @@
|
||||
digraph "reduce.y"
|
||||
{
|
||||
node [fontname=courier shape=box]
|
||||
edge [fontname=courier]
|
||||
|
||||
1 [label="State 1\n 3 a: \"0\" . [\".\"]\l 4 b: \"0\" . [\";\"]\l"]
|
||||
1 -> "1R3" [label="" style=solid]
|
||||
"1R3" [style=filled shape=diamond fillcolor=yellowgreen label="R3"]
|
||||
1 -> "1R4" [label="[\";\"]" style=solid]
|
||||
"1R4" [style=filled shape=diamond fillcolor=yellowgreen label="R4"]
|
||||
}
|
||||
13
doc/figs/example-reduce.txt
Normal file
13
doc/figs/example-reduce.txt
Normal file
@@ -0,0 +1,13 @@
|
||||
.------------------.
|
||||
| State 1 |
|
||||
| 3 a: "0" . [";"] |
|
||||
| 4 b: "0" . ["."] |
|
||||
`------------------'
|
||||
/ \
|
||||
/ \ ["."]
|
||||
/ \
|
||||
v v
|
||||
/ \ / \
|
||||
/ R \ / R \
|
||||
(green) \ 3 / \ 4 / (green)
|
||||
\ / \ /
|
||||
9
doc/figs/example-shift.dot
Normal file
9
doc/figs/example-shift.dot
Normal file
@@ -0,0 +1,9 @@
|
||||
digraph "shift.y"
|
||||
{
|
||||
node [fontname=courier shape=box]
|
||||
edge [fontname=courier]
|
||||
|
||||
3 [label="State 3\n 1 exp: a . \".\"\l"]
|
||||
3 -> 6 [style=solid label="\".\""]
|
||||
6 [label="State 6\n 1 exp: a \".\" .\l"]
|
||||
}
|
||||
12
doc/figs/example-shift.txt
Normal file
12
doc/figs/example-shift.txt
Normal file
@@ -0,0 +1,12 @@
|
||||
.----------------.
|
||||
| State 3 |
|
||||
| 1 exp: a . ";" |
|
||||
`----------------'
|
||||
|
|
||||
| ";"
|
||||
|
|
||||
v
|
||||
.----------------.
|
||||
| State 6 |
|
||||
| 1 exp: a ";" . |
|
||||
`----------------'
|
||||
30
doc/local.mk
30
doc/local.mk
@@ -112,6 +112,36 @@ $(top_srcdir)/doc/bison.1: doc/bison.help doc/bison.x $(top_srcdir)/configure
|
||||
|
||||
nodist_man_MANS = doc/yacc.1
|
||||
|
||||
## ----------------------------- ##
|
||||
## Graphviz examples generation. ##
|
||||
## ----------------------------- ##
|
||||
|
||||
CLEANDIRS += doc/figs
|
||||
FIGS_DOT = doc/figs/example-reduce.dot doc/figs/example-shift.dot
|
||||
EXTRA_DIST += \
|
||||
$(FIGS_DOT) \
|
||||
$(FIGS_DOT:.dot=.eps) $(FIGS_DOT:.dot=.pdf) $(FIGS_DOT:.dot=.png)
|
||||
SUFFIXES += .dot .eps .pdf .png
|
||||
|
||||
bison.dvi: $(FIGS_DOT:.dot=.eps)
|
||||
bison.html: $(FIGS_DOT:.dot=.png)
|
||||
bison.pdf: $(FIGS_DOT:.dot=.pdf)
|
||||
|
||||
.dot.eps:
|
||||
$(AM_V_GEN) $(MKDIR_P) `echo "./$@" | sed -e 's,/[^/]*$$,,'`
|
||||
$(AM_V_at) $(DOT) -Gmargin=0 -Teps $< >$@.tmp
|
||||
$(AM_V_at) mv $@.tmp $@
|
||||
|
||||
.dot.pdf:
|
||||
$(AM_V_GEN) $(MKDIR_P) `echo "./$@" | sed -e 's,/[^/]*$$,,'`
|
||||
$(AM_V_at) $(DOT) -Gmargin=0 -Tpdf $< >$@.tmp
|
||||
$(AM_V_at) mv $@.tmp $@
|
||||
|
||||
.dot.png:
|
||||
$(AM_V_GEN) $(MKDIR_P) `echo "./$@" | sed -e 's,/[^/]*$$,,'`
|
||||
$(AM_V_at) $(DOT) -Gmargin=0 -Tpng $< >$@.tmp
|
||||
$(AM_V_at) mv $@.tmp $@
|
||||
|
||||
## -------------- ##
|
||||
## Doxygenation. ##
|
||||
## -------------- ##
|
||||
|
||||
Reference in New Issue
Block a user