1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
# Copyright 2022 Jeffrey Kegler
# This file is part of Marpa::R2. Marpa::R2 is free software: you can
# redistribute it and/or modify it under the terms of the GNU Lesser
# General Public License as published by the Free Software Foundation,
# either version 3 of the License, or (at your option) any later version.
#
# Marpa::R2 is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser
# General Public License along with Marpa::R2. If not, see
# http://www.gnu.org/licenses/.
=head1 NAME
Marpa::R2::Deprecated::NAIF::Tracing - Tracing a NAIF grammar
=head1 THE NAIF INTERFACE IS DEPRECATED
This document describes the NAIF interface,
which is deprecated.
PLEASE DO NOT USE IT FOR NEW DEVELOPMENT.
=head1 Description
This document is an overview of
the techniques for tracing and
debugging Marpa parses and grammars.
using its named argument interface (NAIF).
If you are a beginner,
or are not sure which interface you are interested in,
or do not know what the NAIF interfaces is,
you probably are looking for
L<the document on tracing and debugging for the SLIF
interface|Marpa::R2::Tracing>.
=head1 Basic techniques
=head2 Check the input location where parsing failed
If parsing failed in the recognizer,
look at the input location where it happened.
Compare the input against the grammar.
This step is fairly obvious,
but I include it because
even experts (actually, especially experts)
will sometimes overlook the obvious
in a rush to use more advanced techniques.
=head2 Turn on warnings
Make sure that
Marpa's C<warnings> named arguments
for both the grammar and the recognizer
are turned on.
Warnings are on by default.
=head2 Trace terminals
Turn on the C<trace_terminals> recognizer named argument.
This tells you which tokens the recognizer is looking for and which ones it thinks it found.
If the problem is in lexing, C<trace_terminals> tells you the whole story.
Even if the problem is not in the lexing,
tracing terminals can tell you a lot.
Marpa uses prediction-driven lexing.
At any given parse location,
Marpa is only looking
for those tokens that it thinks
could result in a successful parse.
Examining the list of
tokens that the recognizer is looking for
can tell you a lot about
what the recognizer thinks it has seen
so far.
=head2 Trace progress
Tracing the recognizer's progress
with
C<show_progress>
is most powerful tool available
in the basic toolkit.
C<show_progress>
should provide all the
information necessary to
debug an application's grammar.
L<A separate document|Marpa::R2::Deprecated::NAIF::Progress>
explains how to interpret the progress reports.
That document includes an
example of the use of C<show_progress>
to debug an error in a grammar.
=head2 Double check rules and symbols
It sometimes helps to look carefully at the output of
C<show_rules> and C<show_symbols>.
Check if anything there is
not what you expected.
=head2 Other traces
C<trace_actions> will show you how action names resolve to actions.
Setting the C<trace_values> evaluator named argument to a trace level of 1
traces the values of the parse tree nodes as they are pushed on, and
popped off, the evaluation stack.
=head2 Basic checklist
A full investigation of a parse
includes the following:
=over 4
=item * Make sure the C<warnings> option is turned on. It is on by default.
=item * Turn on the C<trace_terminals> recognizer named argument.
=item * Run C<show_symbols> on the precomputed grammar.
=item * Run C<show_rules> on the precomputed grammar.
=item * Run C<show_progress> on the recognizer.
=item * Turn on the C<trace_actions> evaluator named argument.
=item * Set the C<trace_values> evaluator named argument to level 1.
=back
When considering how much tracing to turn on,
remember that if the input text to the grammar is large,
the outputs from
C<trace_terminals>,
C<show_progress>,
and C<trace_values>
will be very lengthy.
You want to work with short inputs if at all possible.
=head1 Copyright and License
=for Marpa::R2::Display
ignore: 1
Copyright 2022 Jeffrey Kegler
This file is part of Marpa::R2. Marpa::R2 is free software: you can
redistribute it and/or modify it under the terms of the GNU Lesser
General Public License as published by the Free Software Foundation,
either version 3 of the License, or (at your option) any later version.
Marpa::R2 is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser
General Public License along with Marpa::R2. If not, see
http://www.gnu.org/licenses/.
=for Marpa::R2::Display::End
=cut
|
