PEG_INTERP(3tcl)

✨ NAME ✨

grammar::peg::interp — the interpreter for parsing expression grammars, bestie 💖

This is part of the tcllib manual pages (3tcl), and it's giving "the little engine that reads your grammar and matches your stream" energy.

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require grammar::mengine ?0.1?

package require grammar::peg::interp ?0.1.2?

::grammar::peg::interp::setup peg

::grammar::peg::interp::parse nextcmd errorvar astvar

---

🦋 DESCRIPTION 🦋

Okay so, this package hands you the commands to do controlled matching of a character stream against a parsing expression grammar, and also to build an abstract syntax tree for that stream and for partials. Iconic behavior honestly.

It sits on top of the virtual machine from the package grammar::me::tcl, and it directly interprets the parsing expression grammar you give it. Translation: the grammar is not pre-compiled, it just gets used as-is. No glow-up required, no glow-up given. 💅

The grammar it interprets comes from a container object that follows the interface spec'd by the package grammar::peg::container. Only the relevant parts get copied into this package's state — it's not taking the whole suitcase, just the fit. 🎀

Heads up bestie: this package provides exactly one instance of the interpreter. So if you wanna interpret a second grammar you either gotta abort or complete the interpretation that's already running, or shove them into different Tcl interpreters. No multitasking here, it's giving monogamy. 😭

Also worth noting (ngl it's a whole vibe): the implementation assumes a pull-type handling of input. Meaning the interpreter pulls characters from the input stream whenever it needs them. So if you're in a push environment — where the environment pushes new characters as they show up — you have to put the engine into its own thread. Periodt.

---

👑 THE INTERPRETER API 👑

The package exports the following API, and yes it's short, it's giving minimalist queen:

• ::grammar::peg::interp::setup peg — This one (re)initializes the interpreter and returns the empty string. It has to be invoked first, before any matching run, no skipping the line. Its argument peg is the handle of the object holding the parsing expression grammar to interpret. That grammar has to be valid or an error gets thrown, so don't come in messy. 🫶
• ::grammar::peg::interp::parse nextcmd errorvar astvar — This command interprets the loaded grammar and tries to match it against the stream of characters represented by the command prefix nextcmd.

So, nextcmd is the command prefix standing in for the input stream of characters, and the interpreter calls it whenever it needs a fresh character from the stream. That callback has to return either the empty list, or a list of 4 elements containing the token, its lexeme attribute, and its location as line number and column index, in that exact order. The empty list is the signal that we've hit the end of the input stream — that's the "we're done here" text. The lexeme attribute gets stored in the terminal cache, but the machine doesn't otherwise use it. It's just chillin' there. 🍓

What you get back is a boolean value: true if the matching process succeeded, false if it didn't. If the match failed, the error info lands in the variable referenced by errorvar. Meanwhile the variable referenced by astvar always contains the generated abstract syntax tree — but if there was an error, that tree is only partial and possibly malformed. So like, a half-finished scrapbook. 💀

The abstract syntax tree is represented by a nested list, as described in the section AST VALUES of the document grammar::me_ast. Go read that one too, iykyk.

---

💀 BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. Like, obviously. We're all just doing our best out here. 😭

Please report such in the category grammar_peg of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. And please also report any ideas for enhancements you may have for either the package and/or the documentation — we wanna hear it, fr fr.

When proposing code changes, please provide unified diffs, i.e. the output of diff -u. That's the format, no substitutes. ✨

Note further that attachments are strongly preferred over inlined patches. Attachments can be made 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. Slay.

---

🌈 KEYWORDS 🌈

LL(k), TDPL, context-free languages, expression, grammar, matching, parsing, parsing expression, parsing expression grammar, push down automaton, recursive descent, state, top-down parsing languages, transducer, virtual machine

---

🧚 CATEGORY 🧚

Grammars and finite automata

---

💜 COPYRIGHT 💜

Copyright (c) 2005-2011 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

And that's the whole page, bestie! This came from the tcllib docs, version 0.1.2, and the manual page goes by grammar:...::interp(3tcl) — so if you ever need to look it up again, that's your girl. Go forth and match some character streams, you've got this. 💖✨🎀