term::receive::bind(3tcl)

💖 term::receive::bind — the manual, but make it cute 💖

okay bestie, welcome to term::receive::bind, a page straight out of the Terminal control manual (section 3tcl, iykyk). it's about keyboard dispatch from terminals, and honestly? it's giving tiny elegant machine. let's get into it 🦋

---

✨ NAME ✨

term::receive::bind — keyboard dispatch from terminals 👑

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require term::receive::bind ?0.2?

term::receive::bind object ?map?

object map str cmd

object default cmd

object listen ?chan?

object unlisten ?chan?

object reset

object next char

object process str

object eof

---

🎀 DESCRIPTION 🎀

so this package hands you a class for building simple dispatchers — things that take character sequences and turn them into actions. and the way it does that internally? each dispatcher is, lowkey, a deterministic finite automaton with a tree structure. no cap. a whole DFA just vibing in there 🌳✨

---

💅 CLASS API 💅

the package exports exactly one command — the class command — and that's what lets you create dispatcher instances. its API, periodt:

• term::receive::bind object ?map? — this command creates a brand new dispatcher object named object, initializes it, and returns the fully qualified name of the object command as its result. the argument is a dictionary mapping from strings — aka character sequences — to the command prefices to invoke when that sequence shows up in the input stream. 🫶

---

🦋 OBJECT API 🦋

the objects that the class command creates come with all these methods:

• object map str cmd — adds an extra mapping from the string str to the action cmd. the mapping takes effect immediately if the processor is currently sitting in a prefix of str, or otherwise at the next reset operation. the action is a command prefix, and it gets invoked with one argument appended to it: the character sequence that caused the invocation. it runs in the global namespace. 💫
• object default cmd — defines a default action cmd that fires whenever an unknown character sequence is encountered. that command prefix is handled the exact same way as the regular action you'd define through the map method. 🍓
• object listen ?chan? — sets up a filevent listener for the channel with handle chan, and invokes the dispatcher object whenever characters have been received, or when EOF was reached. if you don't specify chan, it defaults to stdin. 👀
• object unlisten ?chan? — removes the filevent listener for the channel with handle chan. and yeah, if you don't specify chan, it defaults to stdin. 🧚
• object reset — resets the character processor all the way back to the beginning of the tree. fresh start energy ✨
• object next char — makes the character processor process the character c. this might just advance the internal state, or it might invoke an associated action for a recognized sequence. either way, slay 💅
• object process str — makes the character processor process the character sequence str, advancing the internal state and invoking actions as necessary. this one is a callback for listen. 🔥
• object eof — makes the character processor handle EOF on the input. rn this is no-op. it's a callback for listen. 🌈

---

📝 NOTES 📝

because of how simple this DFA is, you can't recognize a character sequence that has another recognized character sequence as its prefix. 😭

in other words: the set of recognized strings has to form a prefix code. that's the vibe check, and the DFA is not negotiable about it.

---

🐛 BUGS, IDEAS, FEEDBACK 🐛

this document, and the package it describes, will undoubtedly contain bugs and other problems. it's just how it is bestie. please report them in the category term of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. also please report any ideas for enhancements you have for either the package and/or the documentation — we want them fr fr 🫶

when proposing code changes, please provide unified diffs, i.e. the output of diff -u. 👑

also note: attachments are strongly preferred over inlined patches. you can attach stuff 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. 💖

---

🔑 KEYWORDS 🔑

character input, control, dispatcher, listener, receiver, terminal

---

🏷️ CATEGORY 🏷️

Terminal control

---

©️ COPYRIGHT ©️

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

---

and that's the whole page, bestie 💜 this came to you from tcllib, version 0.2, and yeah — it's the term::receive::bind page, section 3tcl, under Terminal control. go build a dispatcher, you absolute icon 👑✨💖