page_util_norm_peg(3tcl)

💖 page_util_norm_peg — page AST normalization, PEG 💖

okay bestie, welcome to page_util_norm_peg from the tcllib manual (section 3tcl, obvi). this one is a lil niche but it's SO good at what it does. let's get into it 🫶

---

✨ SYNOPSIS ✨

package require page::util::norm_peg ?0.2?

package require snit

::page::util::norm::peg tree

---

🌸 DESCRIPTION 🌸

so this package gives you one single utility command and it's a whole vibe. you hand it an AST for a parsing expression grammar, and it normalizes it in a bunch of different ways. the glow-up result is called a Normalized PE Grammar Tree ✨

heads up bestie: this package can ONLY be used from inside a plugin that's managed by the package page::pluginmgr. no solo runs, no cap. 💅

---

🎀 API 🎀

::page::util::norm::peg tree

this command assumes the tree object contains a parsing expression grammar (yes, "contains for a parsing expression grammar", that's the wording, we don't question the ancestors 🙈). it normalizes this tree in place — meaning it just goes in and rearranges everything, no copy, no take-backs. the result? a Normalized PE Grammar Tree, iconic.

here's the operations it performs, in order, and the order MATTERS, we'll get to why:

1. the data for all terminals gets stored in their grandparental nodes. then the terminal nodes AND their parents get removed. type information? dropped. gone. bye. 💀
2. all nodes with exactly one child are irrelevant and get removed — with the exception of the root node. and the immediate child of the root is irrelevant too, so that gets removed as well. not me deleting the whole middle layer of the family tree 😭
3. the name of the grammar gets moved from the tree node it lives in to an attribute of the root node, and then that tree node is removed.

the node that keeps the start expression separate gets removed as irrelevant, and the root node of the start expression gets tagged with a marker attribute, and its handle is saved in an attribute of the root node so you can grab it quick. fast access, slay.

4. nonterminal hint information gets moved from nodes into attributes, and the now-irrelevant nodes get deleted.

note: this transformation DEPENDS on the removal of all nodes with exactly one child, because it already removes all the 'Attribute' nodes. if that hadn't happened first, this transformation would have to put the information into the grandparental node instead. so like, sequencing is everything bestie.

the default mode given to the nonterminals is the value value.

and just like with the global metadata definition, specific information gets moved out of nodes into attributes, the now-irrelevant nodes get deleted, and the root nodes of all definitions get tagged with marker attributes. this gives us a mapping from nonterminal names to their defining nodes too, which gets saved in an attribute of the root node for quick reference. 👑

last thing in this step: the range in the input covered by a definition gets computed. the left extent comes from the terminal for the nonterminal symbol it defines. the right extent comes from the rightmost child under the definition. and while this isn't an expression tree yet, the location data is already sound. periodt. ✨

5. the remaining nodes under all definitions get transformed into proper expression trees. first character ranges, then unary operations, characters, and nonterminals. and at last the tree gets flattened by removing superfluous inner nodes.

the order matters here — it's giving strategy. you shed as many nodes as possible early so you don't do unnecessary work later. efficiency queen 💅

---

🦋 BUGS, IDEAS, FEEDBACK 🦋

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. it's fine, it's a whole thing. please report them in the category page of the Tcllib Trackers: [http://core.tcl.tk/tcllib/reportlist]. and please also drop any ideas for enhancements you have for either the package and/or the documentation. we love ideas 💖

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

also note: attachments are strongly preferred over inlined patches. you can make an attachment by going to the Edit form of the ticket immediately after creating it, and then using the left-most button in the secondary navigation bar. iykyk 🎀

---

🌈 KEYWORDS 🌈

PEG, graph walking, normalization, 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 was page_util_norm_peg(3tcl) straight outta tcllib, version 1.0. go normalize something gorgeous 🦋✨💖