page_util_flow(n)

💖 page_util_flow(n) — the page dataflow/treewalker bestie 💖

okay so this is a Parser generator tools page, and honestly? it's giving "quiet little utility that does SO much". come sit with me, we're gonna go through it together 🫶

---

✨ NAME ✨

page_util_flow — the page dataflow/treewalker utility. that's the whole vibe. no cap.

---

🌸 SYNOPSIS 🌸

package require page::util::flow ?0.2?

package require snit

::page::util::flow start flowvar nodevar script

flow visit node

flow visitl nodelist

flow visita node...

---

🦋 DESCRIPTION 🦋

so this package hands you one single utility command and that command is your new best friend for dataflow-based manipulation of arbitrary data structures. and when I say arbitrary I mean it — especially abstract syntax trees, which is literally the main character use case here. 🌳✨

---

💅 API 💅

• ::page::util::flow start flowvar nodevar script — okay so this one is the core logic, the brain, the moment. it drives the walking of an arbitrary data structure that you can partition into separate parts. trees? graphs? both invited to the party. 💃

here's the thing bestie: this command makes zero assumptions about the API of the structure you're walking. the only rule is that its parts — we call them nodes — are identified by strings. those strings get taken exactly as-is, from the arguments and from the body, and handed right back to the body, no modification, no edits, no notes. untouched. iconic behavior fr fr. 👑

who gets access to the actual data structure? who decides which nodes get visited and in what order? the body of the loop, aka the script. all of it. fully delegated. it's the body's world and we're just living in it.

the body gets invoked first for the nodes in the start-set you specify via start, and from then on it's invoked for the nodes that the body itself has requested to be visited. once the set of nodes-to-visit goes empty, we're done. and heads up: a node can absolutely be visited more than once. the body has complete control over that. no gatekeeping here. 🙈

the body is invoked in the context of the caller. the variable named by nodevar gets set to the current node, and the variable named by flowvar gets set to the command of the flow object — that's the thing the body uses to request which nodes to visit next. that object's API is in the next section, FLOW API. keep scrolling bestie ⬇️

also, the command makes no promises about the order nodes are visited in. the only guarantee: the nodes requested by the current iteration will be visited afterward, in some order. that's it. that's the deal. ✨

---

🌈 FLOW API 🌈

this section is all about the API that the flow object gives you — and that object is made accessible to the body script of ::page::util::flow. here we go:

• flow visit node — invoke this method and you're requesting that the node n gets visited after the current iteration. one node, one request. simple. 🎀
• flow visitl nodelist — invoke this one and you're requesting that all the nodes found in the list nodelist get visited after the current iteration. bulk request energy. 🧚
• flow visita node... — this is the variadic-arguments form of the visitl method above. same energy, different shape. 💫

---

😭 BUGS, IDEAS, FEEDBACK 😭

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. it's giving "we're all human". please report them in the category page of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. 🫶

also please report any ideas for enhancements you have — for the package, the documentation, or both. we want them all. 💖

when you're proposing code changes, please provide unified diffs, i.e. the output of diff -u. that's the format, periodt.

note further that attachments are strongly preferred over inlined patches. you can make attachments by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. yes, that specific button. 💀

---

👑 KEYWORDS 👑

dataflow, graph walking, page, parser generator, text processing, tree walking

---

⭐ CATEGORY ⭐

Page Parser Generator

---

💜 COPYRIGHT 💜

Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

and that's the whole page, bestie!! 🎀 this one shipped as part of tcllib, version 1.0, and it's the page_util_flow(n) page — go forth and walk those trees, you absolute legend 🌸🦋✨