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

   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.

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