gramm...dexec(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ gramm...dexec — Finite automaton operations and usage ✨

ok so bestie, you're in the 3tcl section of the manual, and the page you're holding is gramm...dexec from Finite automaton operations and usage. grab a strawberry 🍓 and let's get into it.

💖 NAME 💖

grammar::fa::dexec — Execute deterministic finite automatons

ok so literally what it says on the tin: it runs DFAs. slay. 👑

🌸 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 all that. iconic honestly. 💅

🦋 DESCRIPTION 🦋

This package gives you a class for executors, and those executors get built from deterministic finite automatons (DFAs, iykyk). An executor is an object that you feed a string of symbols to piece by piece — not all at once, one lil bite at a time — and it does state transitions and then yells back at you when it lands in a final state, or when it finds an error in the input. 🔥

And where do the DFAs come from? Bestie, we are not building them here. For the actual creation of the DFAs the executors are based on, you want the packages grammar::fa and grammar::fa::op. go say hi to them first. 🫶

The objects follow a push model. 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 — that gets reported through the callback you specified via the option -command. 💌

and ngl, if you're sitting there like "hmm what if I want a pull model, where the environment retrieves messages from the object and the object uses a callback to ask for more symbols?" — bestie, converting this into that is a trivial thing. genuinely. go off. ✨

side note (the original says "Side note" and we respect it): the acceptor objects provided by grammar::fa::dacceptor could have been implemented on top of the executors provided here, but were not, to get a bit more performance — we avoid a number of method calls and the time required for their dispatch. efficiency queen behavior. 👑

💅 API 💅

The package exports the API described here.

  • ::grammar::fa::dexec daName fa ?-any any? ?-command cmdprefix? — Creates a new deterministic executor with an associated global Tcl command whose name is daName. This command may be used to invoke various operations on the executor. It has the following general form:
daName option ?arg arg ...?

option and the args determine the exact behavior of the command. See section EXECUTOR METHODS for more explanations. 📖

The executor will be based on the deterministic finite automaton stored in the object fa. It will keep a copy of the relevant data of the FA in its own storage, in a form easy to use for its purposes. This also means that changes made to the fa after the construction of the executor will not influence the executor. it took a snapshot and it's living its truth. 📸

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 proceeding with the processing. very forgiving of it. 🧚

🎀 EXECUTOR METHODS 🎀

All executors provide the following methods for their manipulation:

  • daName destroy — Destroys the automaton, including its storage space and associated command. bye bestie 👋💀
  • daName put symbol — Takes the current state of the executor and the symbol and performs the appropriate state transition. Reports any errors encountered via the command callback, as well as entering a final state of the underlying FA.
⚠️ when an error is reported, all further invokations of put will do nothing, until the error condition has been cleared via an invokation of method reset. so like, it's pouting. you have to actually clear it.
  • 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 energy 🌈
  • daName state — Returns the current state of the underlying FA. This allow for introspection without the need to pass data from the callback command. nosy in a healthy way 🔍

💌 EXECUTOR CALLBACK 💌

The callback command cmdprefix given to an executor via the option -command will be executed by the object at the global level, using the syntax described below. Note that cmdprefix is not simply the name of a command, but a full command prefix. In other words, it may contain additional fixed argument words beyond the command word. so it's giving "a whole vibe", not just a name. periodt. 💅

  • 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. it literally cannot even. 💀
  • cmdprefix final stateid — The executor has entered the final state stateid. 🎉
  • cmdprefix reset — The executor was reset. 🔄
  • cmdprefix state stateid — The FA changed state due to a transition. stateid is the new state. ✨

🍓 EXAMPLES 🍓

so this section exists in the original and it is empty. no examples. nothing. it's giving minimalist. I'm not gonna invent any for you because that would be lying and we don't do that here — the section is just there, vibing, with nothing in it. 🙈

🔥 BUGS, IDEAS, FEEDBACK 🔥

This document, and the package it describes, will undoubtedly contain bugs and other problems. yes, fr fr, they said it themselves. 😭

Please report such in the category grammar_fa of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist](http://core.tcl.tk/tcllib/reportlist). Please also report any ideas for enhancements you may have for either package and/or documentation. we love a contribution moment 🫶

When proposing code changes, please provide unified diffs, i.e the output of diff -u. no vibes-based patches bestie, actual diffs.

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. okay so: create ticket → Edit form → left-most button. got it. 💅

⭐ KEYWORDS ⭐

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

👑 CATEGORY 👑

Grammars and finite automata

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 was gramm...dexec(3tcl) from the tcllib collection, version 0.3. mwah. go execute some deterministic finite automatons, you main character. 💖✨🦋

📦 where this page comes from