Marpa:...racing(3pm)

✨ NAME ✨

okay bestie, this is Marpa::R2::NAIF::Tracing 💅 — literally the whole vibe of tracing a NAIF grammar. it's a page from the User Contributed Perl Documentation, and we're gonna get you fluent in it. 🦋

---

🌸 Description 🌸

so this doc is the big-picture tour of how you trace and debug Marpa parses and grammars — using its named argument interface, aka NAIF. ✨

real talk though: if you're a beginner, or you're not sure which interface you even care about, or you straight-up don't know what the NAIF interface is? then bestie, you probably want the document on tracing and debugging for the SLIF interface instead. no shame, we've all been there 🫶

---

🎀 Basic techniques 🎀

💖 Check the input location where parsing failed

if parsing failed in the recognizer, go look at the input location where it happened. compare the input against the grammar. lowkey obvious, right? but i'm putting it here anyway because even the experts (honestly, especially the experts 😭) will sometimes skip right past the obvious in a rush to flex with the more advanced techniques. don't be that girl. 🙈

💖 Turn on warnings

make sure Marpa's warnings named arguments — for both the grammar and the recognizer — are turned on. good news: warnings are on by default. slay. ✨

💖 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 entire story. periodt. 💅

and even if the problem is not in the lexing, tracing terminals can still tell you a lot. here's why: 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. 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 even includes an example of using show_progress to debug an error in a grammar. obsessed. 👑

💖 Double check rules and symbols

sometimes it 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 grammar, bestie. 🧚

💖 Other traces

trace_actions will show you how action names resolve to actions. and 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. stack go up, stack go down 📚✨

💖 Basic checklist

a full investigation of a parse includes the following:

• make sure the warnings option is turned on. it is on by default. ✨
• turn on the trace_terminals recognizer named argument.
• run show_symbols on the precomputed grammar.
• run show_rules on the precomputed grammar.
• run show_progress on the recognizer.
• turn on the trace_actions evaluator named argument.
• set the trace_values evaluator named argument to level 1.

⚠️ okay important warning 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 will be very lengthy. 💀 you want to work with short inputs if at all possible. fr fr.

---

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

---

and that's a wrap, gorgeous 💜 this page came to you courtesy of perl v5.34.0 and the date 2022-02-06 — shoutout to the version and the timestamp, iconic as always. 🎀 go forth and debug, you've got this. ✨🦋