1Marpa::XS::Tracing(3pm)User Contributed Perl DocumentatioMnarpa::XS::Tracing(3pm)
2
3
4

NAME

6       Marpa::XS::Tracing - Tracing your Marpa grammar
7

DESCRIPTION

9       This document is an overview of the techniques for tracing and
10       debugging Marpa parses and grammars.
11

BASIC TECHNIQUES

13   Check the input location where parsing failed
14       If parsing failed in the recognizer, look at the input location where
15       it happened.  Compare the input against the grammar.  This step is
16       fairly obvious, but I include it because even experts (actually,
17       especially experts) will sometimes overlook the obvious in a rush to
18       use more advanced techniques.
19
20   Turn on warnings
21       Make sure that Marpa's "warnings" named arguments for both the grammar
22       and the recognizer are turned on.  Warnings are on by default.
23
24   Trace terminals
25       Turn on the "trace_terminals" recognizer named argument.  This tells
26       you which tokens the recognizer is looking for and which ones it thinks
27       it found.  If the problem is in lexing, "trace_terminals" tells you the
28       whole story.
29
30       Even if the problem is not in the lexing, tracing terminals can tell
31       you a lot.  Marpa uses prediction-driven lexing.  At any given parse
32       location, Marpa is only looking for those tokens that it thinks could
33       result in a successful parse.  Examining the list of tokens that the
34       recognizer is looking for can also tell you where the recognizer thinks
35       it is.
36
37   Trace progress
38       Tracing the recognizer's progress with "show_progress" is most powerful
39       tool available in the basic toolkit.  "show_progress" should provide
40       all the information necessary to debug an application's grammar.  A
41       separate document explains how to interpret the progress reports.  That
42       document includes an example of the use of "show_progress" to debug an
43       error in a grammar.
44
45   Double check rules and symbols
46       It sometimes helps to look carefully at the output of "show_rules" and
47       "show_symbols".  Check if anything there is not what you expected.
48
49   Other traces
50       "trace_actions" will show you how action names resolve to actions.
51       Setting the "trace_values" evaluator named argument to a trace level of
52       1 traces the values of the parse tree nodes as they are pushed on, and
53       popped off, the evaluation stack.
54
55   Basic checklist
56       A full investigation of a parse includes the following:
57
58       •   Make sure the "warnings" option is turned on.  It is on by default.
59
60       •   Turn on the "trace_terminals" recognizer named argument.
61
62       •   Run "show_symbols" on the precomputed grammar.
63
64       •   Run "show_rules" on the precomputed grammar.
65
66       •   Run "show_progress" on the recognizer.
67
68       •   Turn on the "trace_actions" evaluator named argument.
69
70       •   Set the "trace_values" evaluator named argument to level 1.
71
72       When considering how much tracing to turn on, remember that if the
73       input text to the grammar is large, the outputs from "trace_terminals",
74       "show_progress", and "trace_values" will be very lengthy.  You want to
75       work with short inputs if at all possible.
76
78         Copyright 2012 Jeffrey Kegler
79         This file is part of Marpa::XS.  Marpa::XS is free software: you can
80         redistribute it and/or modify it under the terms of the GNU Lesser
81         General Public License as published by the Free Software Foundation,
82         either version 3 of the License, or (at your option) any later version.
83
84         Marpa::XS is distributed in the hope that it will be useful,
85         but WITHOUT ANY WARRANTY; without even the implied warranty of
86         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
87         Lesser General Public License for more details.
88
89         You should have received a copy of the GNU Lesser
90         General Public License along with Marpa::XS.  If not, see
91         http://www.gnu.org/licenses/.
92
93
94
95perl v5.38.0                      2023-07-20           Marpa::XS::Tracing(3pm)
Impressum