/ 
Marpa-XS-0.001_030
/ Marpa::XS::Tracing

NAME

Marpa::XS::Tracing - Tracing Your Grammar

DESCRIPTION

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

BASIC TECHNIQUES

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.

Turn on Warnings

Make sure that Marpa's warnings named arguments for both the grammar and the recognizer are turned on. Warnings are on by default.

Turn off Stripping

When Marpa "strips" its objects, it removes data that is not needed for subsequent processing. This saves time and memory, but data that is not needed for processing can be extremely valuable for debugging. When objects are stripped, many of Marpa's tracing methods will return partial information or no information at all.

You should turn off Marpa's strip named argument to the grammar. Grammar stripping is on by default. If you are using the recognizer's strip method to strip the recognizer, stop doing that.

Trace Terminals

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 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 also tell you where the recognizer thinks it is.

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_rules and show_symbols. Check if anything there is not what you expected.

Other Traces

trace_actions will show you how action names resolve to semantic Perl closures. 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.

Basic Checklist

A full investigation of a parse includes the following:

  • Make sure the warnings option is turned on. It is on by default.

  • Turn off the strip Marpa named argument. By default, it is on.

  • Make sure you're not stripping the recognizer.

  • 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.

ADVANCED TECHNIQUES

Most users can skip this section. Marpa's advanced traces should not be necessary for debugging application grammars. They are documented for those who want to delve into internals.

Marpa's internals are described in the implementation document. The internal traces are Marpa::XS::Recognizer::show_earley_sets , and Marpa::XS::Grammar::show_AHFA . The implementation document has example outputs from the show_earley_sets and show_AHFA methods, and explains how to read them. Note that, if the input text to the grammar is large, the output from show_earley_sets will be very lengthy. You want to work with short inputs if at all possible.

COPYRIGHT AND LICENSE

Copyright 2011 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
http://www.gnu.org/licenses/.