.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Marpa::R2::Tracing 3pm"
.TH Marpa::R2::Tracing 3pm "2021-01-22" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Marpa::R2::Tracing \- Tracing your grammar
.SH "Description"
.IX Header "Description"
This document is an overview of
the techniques for tracing and
debugging parses and grammars using Marpa's \s-1SLIF\s0 interface.
.SH "Basic techniques"
.IX Header "Basic techniques"
.SS "Check the input location where parsing failed"
.IX Subsection "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.
.SS "Dump the parse value"
.IX Subsection "Dump the parse value"
Sometimes, even when there is a parse error, you can still evaluate the parse
using the \s-1SLIF\s0 recognizer's \f(CW\*(C`value()\*(C'\fR
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 \s-1AST\s0's.
.PP
If you are trying to run diagnostics on a failed parse,
it is useful to catch the exception using \f(CW\*(C`eval\*(C'\fR:
.PP
.Vb 2
\&    my $eval_error = $EVAL_ERROR if not eval { $slr\->read( \e$test_input ); 1 };
\&    $progress_report = $slr\->show_progress( 0, \-1 );
.Ve
.SS "Trace terminals"
.IX Subsection "Trace terminals"
Set the \f(CW\*(C`trace_terminals\*(C'\fR 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, \f(CW\*(C`trace_terminals\*(C'\fR tells you the whole story.
Even if the problem is not in the lexing,
tracing terminals can tell you a lot.
.SS "Trace progress"
.IX Subsection "Trace progress"
Tracing the recognizer's progress
with
\&\f(CW\*(C`show_progress\*(C'\fR
is most powerful tool available
in the basic toolkit.
\&\f(CW\*(C`show_progress\*(C'\fR
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 \f(CW\*(C`show_progress\*(C'\fR
to debug an error in a grammar.
.SS "Double check rules and symbols"
.IX Subsection "Double check rules and symbols"
It sometimes helps to look carefully at the output of
\&\f(CW\*(C`show_symbols\*(C'\fR
and
\&\f(CW\*(C`show_rules\*(C'\fR.
Check if anything there is
not what you expected.
For thorough checking, it can be helpful to use a
verbosity level higher than 1.
.SS "Other traces"
.IX Subsection "Other traces"
Setting the \s-1SLIF\s0 recognizer's \f(CW\*(C`trace_values\*(C'\fR 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.
.SS "Basic checklist"
.IX Subsection "Basic checklist"
A full investigation of a parse
includes the following:
.IP "\(bu" 4
Of course, the error message.
.IP "\(bu" 4
If the failed parse returns a value, a dump of that value.
.IP "\(bu" 4
Set the 
\&\s-1SLIF\s0 recognizer's \f(CW\*(C`trace_terminals\*(C'\fR named
argument
to level 1.
.IP "\(bu" 4
Run 
\&\f(CW\*(C`show_rules\*(C'\fR
on the \s-1SLIF\s0 grammar.
.IP "\(bu" 4
Run 
\&\f(CW\*(C`show_symbols\*(C'\fR
on the \s-1SLIF\s0 grammar.
.IP "\(bu" 4
Run
\&\f(CW\*(C`show_progress()\*(C'\fR
on the \s-1SLIF\s0 recognizer.
.IP "\(bu" 4
Set the
\&\s-1SLIF\s0 recognizer's \f(CW\*(C`trace_terminals\*(C'\fR named
argument
to level 1.
.PP
When considering how much tracing to turn on,
remember that if the input text to the grammar is large,
the outputs from
\&\f(CW\*(C`trace_terminals\*(C'\fR,
\&\f(CW\*(C`show_progress\*(C'\fR,
and \f(CW\*(C`trace_values\*(C'\fR,
and the dump of the parse value,
can be very lengthy.
You want to work with short inputs when possible.
.SH "Copyright and License"
.IX Header "Copyright and License"
.Vb 5
\&  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/.
.Ve