Marpa:...Phases(3pm)

💖 NAME 💖

Marpa::R2::Deprecated::NAIF::Semantics::Phases — the deets on NAIF parse evaluation, bestie 💅

(perl's own User Contributed Perl Documentation, if you were wondering who to thank 🎀)

---

🚫 THE NAIF INTERFACE IS DEPRECATED 🚫

Okay so, real talk: this whole document is about the NAIF interface, and NAIF is deprecated. Like, capital-D deprecated.

PLEASE DO NOT USE IT FOR NEW DEVELOPMENT. fr fr. no cap. this is not a drill 😭

---

✨ Overview of the semantic phases ✨

So this page is about Marpa's low-level NAIF interface. If you're new to Marpa, or you're not sure which interface you even want, or you literally do not know what the Named Argment InterFace (NAIF) is — bestie, no stress 🫶 — you probably wanna go read the semantics doc for the SLIF interface instead.

Most apps out there are gonna find that the order Marpa's NAIF runs its semantics in "just works". This doc spells that order out in full detail though, because the details can actually matter for some applications — for example the ones that are out here exploiting side effects 👀. And some readers may just find this background material helpful, which, valid.

This one's an advanced document, okay? It's written assuming you've got the more low-level NAIF interface in play. The SLIF uses the exact same code as the NAIF for evaluation and works the same way, except it hides even more of these details from the user. Sneaky. Iconic. Both. 💅

---

🌳 Parse trees, parse results and parse series 🌳

Little reminder moment, bestie: when the semantics get applied to a parse tree, they produce a value called a parse result.

And because Marpa does ambiguous parsing (slay), each parse can produce a parse series — that's a series of zero or more parse trees, and each one of those trees has its own parse result. Zero. Or more. Yes, zero is allowed, don't @ me.

The first call to the recognizer's value method after the recognizer is created is the start of the first parse series. That first parse series keeps going until there's a call to the reset_evaluation method, or until the recognizer gets destroyed. Usually an application is only interested in a single parse series, so like. chill.

When the reset_evaluation method is called for a recognizer, it begins a new parse series. That new parse series continues until there's another call to the reset_evaluation method, or until the recognizer is destroyed. Periodt. 💀

---

📋 Summary of the phases 📋

While we're processing a parse series, here's the lineup:

• A Series Setup Phase, which happens during the first call of the recognizer's value method for that series. It's followed by
• the processing of zero or more parse trees.

And while we're processing a parse tree, we've got:

• A Tree Setup Phase, which happens during the call of the recognizer's value method for that parse tree. It's followed by
• a Tree Traveral Phase.

Also, Node Evaluation Time is the Tree Traversal Phase, as seen from the point of view of each rule node. It is not a separate phase. Not me having to say that out loud 🙈.

---

🛠️ Series Setup Phase 🛠️

During the Series Setup Phase, all value action names get resolved to value actions — which means constants or rule evaluation closures. That's it, that's the resolution.

Now, the rule evaluation closures are never called in the Series Setup Phase. They get called later, in the Tree Traversal Phase. Not now. Later. Patience, bestie 😌.

Also, during the Series Setup Phase, the logic that ranks parse trees is executed. Ranking rights, we love to see it.

---

🌱 Tree Setup Phase 🌱

In the Tree Setup Phase, the per-parse-tree variable is created. And if a constructor was found for the action_object, it gets run at this point, and the per-parse-tree variable is its return value. Cute, right?

And listen: exactly one Tree Setup Phase occurs for each parse tree. One. Per. Tree. No extras, no skips. 👑

---

🚶 Tree Traversal Phase 🚶

During the Tree Traversal Phase, the rule evaluation closures are called. Finally, their moment. Their main character arc.

And just to close the loop: Node Evaluation Time is the Tree Traversal Phase, as seen from the point of view of the individual nodes of the parse tree. Same phase, different lens, iykyk 💜

---

⚖️ 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 vibe check, bestie 🦋 — this was perl v5.42.3, dated 2026-08-20, and yes it was literally headlined Marpa:...Phases(3pm) on both ends, cute of it. Stay away from NAIF for new dev, mwah 💖🌸