page_util_peg(3tcl)

💖 page_util_peg — page PEG transformation utilities 💖

okay bestie, so this is a Tcllib page — it lives in the Parser generator tools corner of the manual, and the page itself is literally called page_util_peg. sit down, grab a strawberry 🍓, and let me tell you about it.

---

✨ SYNOPSIS ✨

package require page::util::peg ?0.2?

package require snit

::page::util::peg::symbolNodeOf tree node

::page::util::peg::symbolOf tree node

::page::util::peg::updateUndefinedDueRemoval tree

::page::util::peg::flatten treequery tree

::page::util::peg::getWarnings tree

::page::util::peg::printWarnings msg

::page::util::peg::peOf tree eroot

::page::util::peg::printTclExpr pe

like… that's the whole lineup 👑 and yes, you can pull in page::util::peg at version 0.2 (or don't specify, whatever, it's optional) and it also needs snit to come along. no cap.

---

🌸 DESCRIPTION 🌸

so this package is basically a little toolkit of common operations for PEG transformations. the vibe is: it expects a Normalized PE Grammar Tree as its input (go look at the package page::util::norm::peg for that, iykyk) — and that tree might also be carrying extra attributes from other transformations, as long as those transformations don't clash with the base definition. it's giving flexible but respectful. 💅

---

🎀 API 🎀

::page::util::peg::symbolNodeOf tree node

you hand it any random expression node in the AST tree, and it figures out which node holds the name of the nonterminal symbol that node belongs to — either the node itself, or one of its ancestors — and gives you back that node's id. and the result is either the root of the tree (which is what you get for the start expression) or a definition node. slay. ✨

::page::util::peg::symbolOf tree node

literally the same as ::page::util::peg::symbolNodeOf, except it returns the symbol name instead of the node. same energy, different return value. 🦋

::page::util::peg::updateUndefinedDueRemoval tree

okay so this one is about what happens when you remove nodes from the AST tree — because doing that can make symbols lose one or more of their users 😭 like:

A used by B and C,
B is reachable,
C is not,

so now A loses the node in the expression for C calling it — or, honestly, not calling it anymore. 🙈

this command updates the cross-references, and also which nonterminals are now undefined. it's the cleanup bestie.

::page::util::peg::flatten treequery tree

this command flattens the nested sequence and choice operators in the AST tree, and it re-uses the treeql object treequery to run the query that decides which nodes get cut. teamwork makes the dream work fr fr 🫶

::page::util::peg::getWarnings tree

this one goes snooping through the attributes of the AST tree looking for problems with the grammar and issues warnings. important bit: these warnings do not stop us from writing the grammar, but they're still real problems with it that the user should be made aware of. ⭐

the result you get back is a dictionary mapping nonterminal names to their associated warnings.

::page::util::peg::printWarnings msg

the argument here is that same dictionary — nonterminal names mapped to their warnings — exactly the kind of thing you'd get from, say, the command ::page::util::peg::getWarnings.

then all those warnings get formatted and printed via the log command page_info. heads up though: that means you can only use this command from inside a plugin managed by the package page::pluginmgr. not just anywhere, bestie. 😤

::page::util::peg::peOf tree eroot

this converts the parsing expression that starts at node eroot in the AST tree into a nested list. the exact syntax of that list is defined by the package grammar::peg — go check it there if you need the deets. 💜

::page::util::peg::printTclExpr pe

this one takes the parsing expression sitting in the nested list pe and turns it into a Tcl string that you can drop straight into a Tcl script. and yeah — see the package grammar::peg for the exact syntax of pe. ✨

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl this document, and the package it describes, will undoubtedly contain bugs and other problems. it's not a maybe, it's a when. 😭

so please report them in the category page of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. and please also send in any ideas you have for enhancements — for the package, the docs, either, both, we're not picky, we're just obsessed with hearing from you. 🫶

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

also note: attachments are strongly preferred over inlined patches. how do you attach? go to the Edit form of the ticket right after you create it, then use the left-most button in the secondary navigation bar. iconic workflow, honestly. 👑

---

🧚 KEYWORDS 🧚

PEG, page, parser generator, parsing expression grammar, text processing, transformation

---

👑 CATEGORY 👑

Page Parser Generator

---

🌈 COPYRIGHT 🌈

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

---

okay that's the whole page, bestie, you ate it 💅✨ and just so you know where this came from — it's from the tcllib collection, version 1.0, and the man page goes by page_util_peg(3tcl). mwah, go forth and transform some PEGs 🎀🦋💖