grammar...::dexec(n)

🦋 grammar...::dexec(n) — the manual, but make it make sense 💖

okay bestie, pull up a chair, we're doing grammar::fa::dexec from tcllib and honestly? it's giving executor energy ✨ This is the n manual page for the package, and I'm gonna walk you through every last crumb of it, no skips, no shortcuts. periodt 💅

---

✨ NAME ✨

grammar::fa::dexec — Execute deterministic finite automatons. yes that's the whole name section, she's brief and she knows it 🎀

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require snit

package require grammar::fa::dexec ?0.3?

::grammar::fa::dexec daName fa ?-any any? ?-command cmdprefix?

daName option ?arg arg ...?

daName destroy

daName put symbol

daName reset

daName state

cmdprefix error code message

cmdprefix final stateid

cmdprefix reset

cmdprefix state stateid

look at her. all those little ?arg?s are optional and the ...s mean "keep going girl". 💖

---

✨ DESCRIPTION ✨

So this package hands you a class for executors that get built out of deterministic finite automatons, aka DFAs (iykyk 🌸). An executor is an object that you feed a string of symbols to — and you feed it piecemeal, like one lil symbol at a time, not all at once, okay? — and it does its state transitions and then reports back when it lands in a final state, or when it finds an error in the input. 🫶

For actually making the DFAs that these executors are based on, we've got the packages grammar::fa and grammar::fa::op. those are the blueprint besties, this is the girl who runs the show 💅

The objects follow a push model. That means symbols get pushed into the executor, and when something important happens — like an error occurs, a state transition happens, or a final state is entered — it gets reported via the callback you specified with the -command option. 📣

Side note from the original, and I'm keeping it because it's tea ☕: turning this into a pull model — where the environment retrieves messages from the object and the object uses a callback to ask for more symbols — is a trivial thing. easy peasy.

Another side note, because the authors said it and I respect it: the acceptor objects provided by grammar::fa::dacceptor could have been implemented on top of the executors provided here… but they were not, and the reason is performance. Specifically, they wanted a bit more speed by avoiding a number of method calls and the time required for their dispatch. efficiency queen 👑

---

✨ API ✨

The package exports the API described right here, bestie. no gatekeeping.

🌟 ::grammar::fa::dexec daName fa ?-any any? ?-command cmdprefix?

Creates a new deterministic executor with an associated global Tcl command whose name is daName. That command is how you invoke all the various operations on the executor. It has this general form:

💫 daName option ?arg arg ...?

The option and the args determine the exact behavior of the command. Peep the EXECUTOR METHODS section below for the full explanation, because that's where the lore lives 📖

The executor will be based on the deterministic finite automaton stored in the object fa. And here's the important bit: it keeps a copy of the relevant data of the FA in its own storage, in a form that's easy for it to use. Which means — say it with me — changes made to the fa after the construction of the executor will NOT influence the executor. she's independent, she doesn't need you anymore 😭💜

And if any has been specified? Then the executor will convert all symbols in the input which are unknown to the base FA to that symbol before it proceeds with the processing. cute little translation moment 🌈

---

✨ EXECUTOR METHODS ✨

Every executor provides these methods for their manipulation. one bullet each, no crumbs left behind 🍓

• daName destroy — Destroys the automaton, including its storage space and its associated command. she's gone, she's resting 💀
• daName put symbol — Takes the current state of the executor plus the symbol, and performs the appropriate state transition. It reports any errors it runs into via the command callback, and also reports entering a final state of the underlying FA. 🎀

⚠️ Heads up: once an error is reported, all further invokations of put will do nothing until the error condition has been cleared by an invokation of the method reset. so clear that error, girl.

• daName reset — Unconditionally sets the executor into the start state of the underlying FA. This also clears any error condition put may have encountered. fresh start, clean slate, new era ✨
• daName state — Returns the current state of the underlying FA. This lets you do introspection without having to pass data from the callback command. nosy? maybe. allowed? absolutely. 👀

---

✨ EXECUTOR CALLBACK ✨

The callback command cmdprefix that you hand to an executor via the -command option gets executed by the object at the global level, using the syntax described below. 📢

And this is important: cmdprefix is not simply the name of a command — it's a full command prefix. In other words, it may contain additional fixed argument words beyond the command word. so you can pre-load her with extras 💅

• cmdprefix error code message — The executor has encountered an error, and message contains a human-readable text explaining the nature of the problem. The code, on the other hand, is a fixed machine-readable text. The following error codes can be generated by executor objects:
  • BADSYM — An unknown symbol was found in the input. This can happen if and only if no -any symbol was specified. 🚨
  • BADTRANS — The underlying FA has no transition for the current combination of input symbol and state. In other words, the executor was not able to compute a new state for this combination. she's stuck, no cap 😭
• cmdprefix final stateid — The executor has entered the final state stateid. 🎉 iconic.
• cmdprefix reset — The executor was reset. 🔄
• cmdprefix state stateid — The FA changed state due to a transition. stateid is the new state. 👑

---

✨ EXAMPLES ✨

…and the original page just leaves this heading here with nothing under it. the blank space is the example. it's giving mystery, it's giving "figure it out bestie" 🙈✨ no fr, there are no examples listed in this one.

---

✨ BUGS, IDEAS, FEEDBACK ✨

This document, and the package it describes, will undoubtedly contain bugs and other problems. like, the authors said it themselves, so we're all being honest here 💀

Please report such in the category grammar_fa 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 — they want your thoughts, bestie 🫶

When proposing code changes, please provide unified diffs, i.e. the output of diff -u. that's the format, no improvising 💅

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. yes, that specific button. she's the one. 🎀

---

✨ KEYWORDS ✨

automaton, execution, finite automaton, grammar, parsing, regular expression, regular grammar, regular languages, running, state, transducer 🌸

---

✨ CATEGORY ✨

Grammars and finite automata 🧚

---

✨ COPYRIGHT ✨

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

Copyright (c) 2007 Bogdan <rftghost@users.sourceforge.net>

---

and that's the whole page, bestie!! 💖 this is grammar...::dexec(n), brought to you by tcllib, version 0.3 — huge shoutout to Andreas Kupries (2004) and Bogdan (2007) for the copyright, and to the whole tcllib era for making it happen. mwah, slay, go push some symbols into a state machine, ily 🎀✨🦋