page_util_peg(n)

💖 page_util_peg — page PEG transformation utilities 💖

okay bestie, so this is a manual page for page_util_peg (that's the title, and it lives in section n of the manual, and it's part of the Parser generator tools lineup — iykyk). sit down, grab a strawberry drink 🍓, and let's get into it.

---

✨ NAME ✨

page_util_peg — page PEG transformation utilities. that's the whole name. iconic. 💅

---

🌈 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

yes, the ?0.2? is literally in there with the question marks. that's the version, and the question marks mean "any version that satisfies this, we're not picky". slay.

---

🦋 DESCRIPTION 🦋

so this package hands you a little bundle of common operations for PEG transformations. it's giving helper-bestie energy. 🫶

the way that it works: everything here assumes you're feeding it a Normalized PE Grammar Tree as input — go look at the package page::util::norm::peg for the deets. and, lowkey important, that tree may also be augmented with attributes that came from transformations, as long as those attributes don't conflict with the base definition. no cap, that's the rule. ✨

---

🎀 API 🎀

here's the whole lineup, one by one. every single one, we're not skipping anybody. 👑

• ::page::util::peg::symbolNodeOf tree node — you hand it an arbitrary expression node in the AST tree, and it figures out the node (could be the node itself, could be an ancestor, whoever's got it) that contains the name of the nonterminal symbol the node belongs to, then returns that node's id. and what comes back is either the root of the tree (when we're talking about the start expression) or a definition node. simple as that. 💖
• ::page::util::peg::symbolOf tree node — literally the exact same thing as ::page::util::peg::symbolNodeOf, except it returns the symbol name instead of the node. that's it. that's the difference. 💅
• ::page::util::peg::updateUndefinedDueRemoval tree — okay so here's the drama 😭: when you remove nodes from the AST tree, symbols can end up losing one or more of their users. picture this:

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

so now A has lost the node in the expression for C that was calling it — or rather, is not calling it anymore. 💀 this command goes and updates the cross-references, plus it figures out which nonterminals are now undefined. cleanup crew, reporting for duty. 🧹✨

• ::page::util::peg::flatten treequery tree — this command flattens nested sequence and choice operators in the AST tree. and it re-uses that treeql object treequery to run the query that decides which nodes get cut. recycling queen. 🌸
• ::page::util::peg::getWarnings tree — this one peeks at the attributes of the AST tree, looking for problems with the grammar, and then it issues warnings. now listen: these warnings do not stop us from writing the grammar, but they still represent problems with it that the user genuinely should be made aware of. we're not gatekeeping. 🫶 the result you get back is a dictionary mapping nonterminal names to their associated warnings.
• ::page::util::peg::printWarnings msg — the argument here is a dictionary mapping nonterminal names to their associated warnings, exactly like the kind generated by, for example, ::page::util::peg::getWarnings. the warnings inside get formatted and then printed via the log command page_info. and here's the catch, bestie: 🚨 that means this command can only be used from inside a plugin managed by the package page::pluginmgr. no plugin, no printing. periodt.
• ::page::util::peg::peOf tree eroot — this command converts the parsing expression that starts at the node eroot in the AST tree into a nested list. the exact syntax of that list is specified by the package grammar::peg. 📜
• ::page::util::peg::printTclExpr pe — this command converts the parsing expression sitting inside the nested list pe into a Tcl string that you can drop straight into a Tcl script. and again, go check 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 giving "we're honest about it". 😭 please report them in the category page of the Tcllib Trackers:

http://core.tcl.tk/tcllib/reportlist

and please also report any ideas for enhancements you have for either the package and/or the documentation. we want them. all of them. 🙈

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

also note further that attachments are strongly preferred over inlined patches. you can attach stuff by going to the Edit form of the ticket immediately after it's created, and then using the left-most button in the secondary navigation bar. that's the one. the left-most one. 🎀

---

⭐ 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 thing, you're basically a PEG transformation expert now, no cap. 🦋 this page came to you from tcllib, version 1.0, and it's page_util_peg(n) — go forth and flatten some trees, bestie. 💅✨🌸