Marpa::R3::Tracing - Tracing your grammar
This document is an overview of the techniques for tracing and debugging 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.
Sometimes, even when there is a parse error, you can still evaluate the parse using the 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.
value()
If you are trying to run diagnostics on a failed parse, it is useful to catch the exception using eval:
eval
my $eval_error = $EVAL_ERROR if not eval { $recce->read( \$test_input ); 1 }; $progress_report = $recce->progress_show( 0, -1 );
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_terminals
Tracing the recognizer's progress with progress_show is the most powerful tool available in the basic toolkit. progress_show 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 progress_show to debug an error in a grammar.
progress_show
It sometimes helps to look carefully at the output of symbols_show and productions_show. Check if anything there is not what you expected. For thorough checking, it can be helpful to use a verbosity level higher than 1.
symbols_show
productions_show
Setting the 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.
trace_values
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 recognizer's trace_terminals named argument to level 1.
Run productions_show on the grammar.
Run symbols_show on the grammar.
Run progress_show() on the recognizer.
progress_show()
When considering how much tracing to turn on, remember that if the input text to the grammar is large, the outputs from trace_terminals, progress_show, and trace_values, and the dump of the parse value, can be very lengthy. You want to work with short inputs when possible.
Marpa::R3 is Copyright (C) 2018, Jeffrey Kegler. This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.1. For more details, see the full text of the licenses in the directory LICENSES. This program 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.
To install Marpa::R3, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Marpa::R3
CPAN shell
perl -MCPAN -e shell install Marpa::R3
For more information on module installation, please visit the detailed CPAN module installation guide.