Marpa::XS::Tracing - Tracing your Marpa grammar
This document is an overview of the techniques for tracing and debugging Marpa
parses and grammars.
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.
Make sure that Marpa's "warnings" named arguments for both the grammar
and the recognizer are turned on. Warnings are on by default.
Turn on the "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, "trace_terminals" tells you the
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
also tell you where the recognizer thinks it is.
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.
It sometimes helps to look carefully at the output of "show_rules" and
"show_symbols". Check if anything there is not what you expected.
"trace_actions" will show you how action names resolve to actions.
Setting the "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.
A full investigation of a parse includes the following:
- Make sure the "warnings" option is turned on. It is on by
- Turn on the "trace_terminals" recognizer named argument.
- Run "show_symbols" on the precomputed grammar.
- Run "show_rules" on the precomputed grammar.
- Run "show_progress" on the recognizer.
- Turn on the "trace_actions" evaluator named argument.
- Set the "trace_values" evaluator 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" will be very lengthy.
You want to work with short inputs if at all possible.
Copyright 2012 Jeffrey Kegler
This file is part of Marpa::XS. Marpa::XS 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::XS 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::XS. If not, see