NAME¶
Marpa::R2::Tracing - Tracing your grammar
Description¶
This document is an overview of the techniques for tracing and debugging parses
and grammars using Marpa's SLIF interface.
Basic techniques¶
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.
Dump the parse value¶
Sometimes, even when there is a parse error, you can still evaluate the parse
using the SLIF recognizer's "value()" method. If you are fortunate
enough to have a parse value at the point of failure, it can be an excellent
way to determine what the parser thinks it has seen so far. It is more likely
that there will be a parse value if you are using incremental development, and
the parse values will be especially helpful if your parse values are AST's.
If you are trying to run diagnostics on a failed parse, it is useful to catch
the exception using "eval":
my $eval_error = $EVAL_ERROR if not eval { $slr->read( \$test_input ); 1 };
$progress_report = $slr->show_progress( 0, -1 );
Trace terminals¶
Set the "trace_terminals" recognizer named argument to 1. This tells
you which tokens the recognizer is looking for and which ones it thinks it
found. If the problem is in lexing, "trace_terminals" tells you the
whole story. Even if the problem is not in the lexing, tracing terminals can
tell you a lot.
Trace progress¶
Tracing the recognizer's progress with "show_progress" is most
powerful tool available in the basic toolkit. "show_progress" should
provide all the information necessary to debug an application's grammar. A
separate document explains how to interpret the progress reports. That
document includes an example of the use of "show_progress" to debug
an error in a grammar.
Double check rules and symbols¶
It sometimes helps to look carefully at the output of "show_symbols"
and "show_rules". Check if anything there is not what you expected.
For thorough checking, it can be helpful to use a verbosity level higher than
1.
Other traces¶
Setting the SLIF recognizer's "trace_values" 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.
Basic checklist¶
A full investigation of a parse includes the following:
- •
- Of course, the error message.
- •
- If the failed parse returns a value, a dump of that value.
- •
- Set the SLIF recognizer's "trace_terminals" named argument to
level 1.
- •
- Run "show_rules" on the SLIF grammar.
- •
- Run "show_symbols" on the SLIF grammar.
- •
- Run "show_progress()" on the SLIF recognizer.
- •
- Set the SLIF recognizer's "trace_terminals" named argument to
level 1.
When considering how much tracing to turn on, remember that if the input text to
the grammar is large, the outputs from "trace_terminals",
"show_progress", and "trace_values", and the dump of the
parse value, can be very lengthy. You want to work with short inputs when
possible.
Copyright and License¶
Copyright 2014 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/.