[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[RFC PATCH 4/4] parse stats: documentation
From: |
Akim Demaille |
Subject: |
[RFC PATCH 4/4] parse stats: documentation |
Date: |
Sun, 7 Jul 2019 20:20:36 +0200 |
* doc/bison.texi (%define Summary): Document parse.stats.
---
NEWS | 20 +++++++++++++++
TODO | 4 ++-
doc/bison.texi | 70 +++++++++++++++++++++++++++++++++++++++++++++-----
3 files changed, 87 insertions(+), 7 deletions(-)
diff --git a/NEWS b/NEWS
index df884905..bd7406dd 100644
--- a/NEWS
+++ b/NEWS
@@ -11,6 +11,26 @@ GNU Bison NEWS
The Java backend no longer emits code and data for parser tracing if the
%define variable parse.trace is not defined.
+*** Summary of a parser run (yacc.c)
+
+ Unless in POSIX Yacc mode, yydebug is now treated as a bit field which
+ controls several types of traces:
+
+ - yydebug_trace: Enable (usual) parse traces.
+ - yydebug_stats: At the end of the parse, print a count of the parser
+ actions.
+
+ The main function could control them as follows:
+
+ for (int i = 1; i < argc; ++i)
+ if (strcmp (argv[1], "-p") == 0)
+ yydebug |= yydebug_trace;
+ else if (strcmp (argv[1], "-s") == 0)
+ yydebug |= yydebug_stats;
+
+ In Yacc mode, yydebug remains a plain null/nonnull variable controling
+ only the usual parse traces.
+
* Noteworthy changes in release 3.4.1 (2019-05-22) [stable]
** Bug fixes
diff --git a/TODO b/TODO
index 0ddd6729..2a0cce4a 100644
--- a/TODO
+++ b/TODO
@@ -71,10 +71,12 @@ syntax error, unexpected $end, expecting "\342\206\246" or
"\360\237\216\205\360
$ gcc utf8.c -o utf8 && ./utf8
syntax error, unexpected $end, expecting ↦ or 🎅🐃 or '\n'
-
While at it, we should stop using "$end" by default, in favor of "end of
file", or "end of input", whatever.
+** parse.lac.memory-trace
+This should rather be controled by more yydebug bits, like yy_debug_stats.
+
* Bison 3.6
** Unit rules
Maybe we could expand unit rules (or "injections", see
diff --git a/doc/bison.texi b/doc/bison.texi
index c0b14383..ca9de35f 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -369,6 +369,7 @@ Tracing Your Parser
* Enabling Traces:: Activating run-time trace support
* Mfcalc Traces:: Extending @code{mfcalc} to support traces
* The YYPRINT Macro:: Obsolete interface for semantic value reports
+* Parsing Summary:: Additional Traces
Invoking Bison
@@ -9934,6 +9935,7 @@ When a Bison grammar compiles properly but parses
``incorrectly'', the
* Enabling Traces:: Activating run-time trace support
* Mfcalc Traces:: Extending @code{mfcalc} to support traces
* The YYPRINT Macro:: Obsolete interface for semantic value reports
+* Parsing Summary:: Additional Traces
@end menu
@node Enabling Traces
@@ -9972,7 +9974,7 @@ compatibility with previous versions of Bison.
Add the @samp{%define parse.trace} directive (@pxref{%define
Summary,,parse.trace}), or pass the @option{-Dparse.trace} option
(@pxref{Tuning the Parser}). This is a Bison extension, which is especially
-useful for languages that don't use a preprocessor. Unless POSIX and Yacc
+useful for languages that don't use a preprocessor. Unless POSIX Yacc
portability matter to you, this is the preferred solution.
@end table
@@ -9988,7 +9990,7 @@ define @code{YYFPRINTF}, @code{<stdio.h>} is
automatically included
and @code{YYFPRINTF} is defined to @code{fprintf}.
Once you have compiled the program with trace facilities, the way to
-request a trace is to store a nonzero value in the variable @code{yydebug}.
+request a trace is to store @code{1} in the variable @code{yydebug}.
You can do this by making the C code do it (in @code{main}, perhaps), or
you can alter the value with a C debugger.
@@ -10025,15 +10027,16 @@ parser function is a finite-state machine
interpreter, and aside from
the actions it executes the same code over and over. Only the values
of variables show where in the grammar it is working.
+
@node Mfcalc Traces
@subsection Enabling Debug Traces for @code{mfcalc}
The debugging information normally gives the token type of each token read,
but not its semantic value. The @code{%printer} directive allows specify
-how semantic values are reported, see @ref{Printer Decl, , Printing
-Semantic Values}. For backward compatibility, Yacc like C parsers may also
-use the @code{YYPRINT} (@pxref{The YYPRINT Macro, , The @code{YYPRINT}
-Macro}), but its use is discouraged.
+how semantic values are reported, see @ref{Printer Decl, , Printing Semantic
+Values}. For backward compatibility, Yacc-like C parsers may also use the
+@code{YYPRINT} (@pxref{The YYPRINT Macro, , The @code{YYPRINT} Macro}), but
+its use is discouraged.
As a demonstration of @code{%printer}, consider the multi-function
calculator, @code{mfcalc} (@pxref{Multi-function Calc}). To enable run-time
@@ -10233,6 +10236,61 @@ print_token_value (FILE *file, int type, YYSTYPE value)
@}
@end example
+
+@node Parsing Summary
+@subsection Parsing Summary
+
+When not in POSIX Yacc mode, the @code{yydebug} variable actually controls
+several features; it is interpreted via bit masks:
+@table @code
+@item yydebug_none
+Disable all traces. Equal to 0.
+
+@item yydebug_trace
+Enable parse traces.
+
+@item yydebug_stats
+At the end of the parse, print a count of the parser actions.
+
+@item yydebug_all
+Enable all traces. Equal to -1.
+@end table
+
+All these identifiers follow @code{api.prefix}. For instance to enable
+traces and summary when @samp{%define api.prefix @{calc_@}} is specified,
+use @samp{calc_debug = calc_debug_trace | calc_debug_stats}.
+
+As an example, the main function of MfCalc (@pxref{Mfcalc Main}) should be
+changed into:
+
+@example
+@group
+int main (int argc, char const* argv[])
+@end group
+@group
+@{
+ for (int i = 1; i < argc; ++i)
+ if (strcmp (argv[1], "-p") == 0)
+ yydebug |= yydebug_trace;
+ else if (strcmp (argv[1], "-s") == 0)
+ yydebug |= yydebug_stats;
+@end group
+@group
+ init_table ();
+ return yyparse ();
+@}
+@end group
+@end example
+
+Then, when run with @option{-s}, parsing facts would be printed at the end:
+
+@example
+$ @kbd{echo '1 + 2 * 3' | mfcalc -s}
+7
+num_reductions: 8
+num_shifts: 7
+@end example
+
@c ================================================= Invoking Bison
@node Invocation
--
2.22.0
- [PATCH 1/4] parse.stats: new feature of yacc.c, (continued)
- [PATCH 1/4] parse.stats: new feature of yacc.c, Akim Demaille, 2019/07/03
- [PATCH 4/4] parse.stats: documentation, Akim Demaille, 2019/07/03
- [PATCH 3/4] regen, Akim Demaille, 2019/07/03
- Re: [PATCH 0/4] RFC: add stats about parsing, Adrian Vogelsgesang, 2019/07/03
- Re: [PATCH 0/4] RFC: add stats about parsing, Akim Demaille, 2019/07/03
- Re: [PATCH 0/4] RFC: add stats about parsing, Adrian Vogelsgesang, 2019/07/04
- [RFC PATCH 0/4] RFC: add stats about parsing, Akim Demaille, 2019/07/07
- [RFC PATCH 1/4] parse stats: new feature of yacc.c, Akim Demaille, 2019/07/07
- [RFC PATCH 2/4] parse stats: add --trace=parse-stats, Akim Demaille, 2019/07/07
- [RFC PATCH 3/4] regen, Akim Demaille, 2019/07/07
- [RFC PATCH 4/4] parse stats: documentation,
Akim Demaille <=