GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Marpa::Tracing(3) User Contributed Perl Documentation Marpa::Tracing(3)

Marpa::Tracing - Tracing Your 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.

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.

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.

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

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.

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::Recognizer::show_earley_sets" , and "Marpa::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 2007-2010 Jeffrey Kegler, all rights reserved. Marpa is free software under the Perl license. For details see the LICENSE file in the Marpa distribution.
2022-04-09 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.