Marpa:...racing(3pm)

✨ NAME ✨

Marpa::R2::Deprecated::NAIF::Tracing — tracing a NAIF grammar, bestie. The manual page is Marpa:...racing(3pm) from User Contributed Perl Documentation, and we are getting into it 💅

---

💀 THE NAIF INTERFACE IS DEPRECATED 💀

Okay so first things first, and I need you to hear me on this: this doc describes the NAIF interface, which is deprecated. And I'm not saying that to be dramatic, it says it in all caps in the real page so you know it's serious:

PLEASE DO NOT USE IT FOR NEW DEVELOPMENT.

Periodt. No new code on this, bestie. 🚫

---

🌸 Description 🌸

So this doc is an overview of the techniques for tracing and debugging Marpa parses and grammars, using its named argument interface (NAIF). It's giving ~vintage~.

Real talk though: if you're a beginner, or you're not sure which interface you're interested in, or you literally don't know what the NAIF interface even is — you are probably looking for the document on tracing and debugging for the SLIF interface. Go there, queen. 👑

---

🧚 Basic techniques 🧚

🔍 Check the input location where parsing failed

If parsing failed in the recognizer, look at the input location where it happened. Then compare the input against the grammar.

I know, I know — this step is fairly obvious. But I'm including it because even experts (actually, especially experts) will sometimes overlook the obvious in a rush to use more advanced techniques. Not me calling anyone out but also... it's in the official docs so 💀

🔔 Turn on warnings

Make sure that Marpa's "warnings" named arguments for both the grammar and the recognizer are turned on.

Good news: warnings are on by default. So if you didn't touch anything, you're already slaying. ✨

🎀 Trace terminals

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. Whole. Story. 📖

Even if the problem is not in the lexing, tracing terminals can tell you a lot, because 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. So examining the list of tokens the recognizer is looking for can tell you a lot about what the recognizer thinks it has seen so far. It's giving mind-reading, honestly. 🔮

📈 Trace progress

Tracing the recognizer's progress with "show_progress" is the most powerful tool available in the basic toolkit. Like, highkey the main character of this whole list 👑

"show_progress" should provide all the information necessary to debug an application's grammar. There's a separate document that explains how to interpret the progress reports, and that document includes an example of the use of "show_progress" to debug an error in a grammar. Go read it, iykyk 🦋

✅ Double check rules and symbols

It sometimes helps to look carefully at the output of "show_rules" and "show_symbols". Check if anything there is not what you expected. Vibe check your own output, basically ✨

🫶 Other traces

• "trace_actions" will show you how action names resolve to actions.
• 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. Pushed on, popped off, we love a little stack choreography 🎀

📝 Basic checklist

A full investigation of a parse includes the following:

1. Make sure the "warnings" option is turned on. It is on by default.
2. Turn on the "trace_terminals" recognizer named argument.
3. Run "show_symbols" on the precomputed grammar.
4. Run "show_rules" on the precomputed grammar.
5. Run "show_progress" on the recognizer.
6. Turn on the "trace_actions" evaluator named argument.
7. 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.

Like, keep it short bestie, your scrollback will thank you 😭

---

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

---

🫶 That's the whole page, babe. This one comes from perl v5.42.3 and it's dated 2026-08-20 — so like, fresh off the press, slay. Go forth and debug responsibly 🌈💖