Marpa:...racing(3pm)

💖 Marpa::R2::Tracing — Tracing your grammar ✨

okay bestie, welcome to Marpa::R2::Tracing (that's the <pink>3pm</pink> page btw, perl gang rise up 💅). This one is your whole overview of how to trace and debug parses and grammars using Marpa's SLIF interface. No cap, it's the debugging bible. 🫶

---

🌸 Description 🌸

This doc is, like, an overview — the big picture tour — of the techniques for tracing and debugging parses and grammars with Marpa's SLIF interface. That's it, that's the vibe check. 💖

---

🔥 Basic techniques 🔥

🎀 Check the input location where parsing failed 🎀

If the recognizer is like "nope, parse failed 😭", go look at the input location where it happened. Then compare the input against the grammar. Lowkey obvious? Yes. But I'm putting it here anyway because even the experts (honestly, especially the experts 💀) will sometimes overlook the obvious in a rush to go use the fancier techniques. Not me calling anyone out. 👑 It's giving "check your spelling before you rewrite the whole file," iykyk.

✨ Dump the parse value ✨

Sometimes, even when there's a parse error, you can still evaluate the parse using the SLIF recognizer's value() method. And if you're lucky enough to have a parse value at the point of failure — slay — that's an excellent way to figure out what the parser thinks it has seen so far. It's more likely you'll get a parse value if you're doing incremental development, and those parse values are especially helpful if your parse values are AST's. 🌟

If you're trying to run diagnostics on a failed parse, it's useful to catch the exception using "eval":

my $eval_error = $EVAL_ERROR if not eval { $recce->read( \$test_input ); 1 };
$progress_report = $recce->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 — full tea, no crumbs. ☕ Even if the problem is not in the lexing, tracing terminals can still tell you a lot. Obsessed with it frankly.

💜 Trace progress 💜

Tracing the recognizer's progress with "show_progress" is the 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. Main character energy fr fr.

🌈 Double check rules and symbols 🌈

Sometimes it helps to look very carefully at the output of "show_symbols" and "show_rules". Check if anything there is not what you expected — like, vibe check those symbols. For thorough checking, it can be helpful to use a verbosity level higher than 1. Turn it up, bestie. 🔉

🧚 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. Push, pop, push, pop — ASMR honestly. 🍓

---

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

⚠️ okay important bestie — when you're deciding 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", plus the dump of the parse value, can be very lengthy. 😭 You want to work with short inputs when possible. Short inputs = cute outputs. Periodt.

---

👑 Copyright and License 👑

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

---

and that's the whole page, bestie!! 🎀 this was built for perl v5.42.3 and stamped 2026-08-20 — shoutout to the perl fam for keeping it alive, we love to see it. go forth and trace, you're doing amazing sweetie 💖✨🦋