term::receive::bind(n)

💖 term::receive::bind(n) — keyboard dispatch from terminals 💖

okay bestie so this is term::receive::bind, living in the Terminal control corner of the Tcllib manual. it's the little goblin that takes your keystrokes and turns them into actions. 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 little dispatchers — the thingies that take character sequences and route them to actions. and like. internally? each dispatcher is literally a deterministic finite automaton, but shaped like a tree. it's giving DFA but make it 🌳

---

👑 CLASS API 👑

the package exports one command and that's the class command itself, which is how you spawn dispatcher instances. its API, bestie:

• term::receive::bind object ?map? — this creates a brand new dispatcher object named object, initializes it, and hands you back the fully qualified name of the object command as its result. ✨ the argument is a dictionary mapping from strings (i.e. character sequences) to the command prefices you wanna invoke when that sequence shows up in the input stream. no cap.

---

💅 OBJECT API 💅

the objects that the class command makes give you all these methods, periodt:

• object map str cmd — adds an extra mapping from the string str to the action cmd. the mapping kicks in immediately if the processor happens to be sitting in a prefix of str, or else at the next reset operation. cmd is a command prefix and gets invoked with one argument appended to it — the character sequence that caused the invokation. it runs in the global namespace. 💫
• object default cmd — defines a default action cmd that fires whenever an unknown character sequence gets encountered. the command prefix is handled exactly the same way as the regular action you'd define via the map method.
• object listen ?chan? — sets up a filevent listener on the channel with handle chan and pings the dispatcher object every time characters arrive, or when EOF is reached. if you don't specify chan, it defaults to stdin. 🫶
• object unlisten ?chan? — removes the filevent listener for the channel with handle chan. if you don't specify chan, it defaults to stdin.
• object reset — resets the character processor right 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 sequence it recognized. 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. heads up: this is currently a no-op. it's a callback for listen.

---

📝 NOTES 📝

the DFA is simple (iconic of it) and that means you cannot recognize a character sequence that has another recognized character sequence as its prefix. sorry bestie 😭

in other words: the set of recognized strings has to form a prefix code. that's the vibe check. no exceptions.

---

🐛 BUGS, IDEAS, FEEDBACK 🐛

this document, and the package it describes, will undoubtedly contain bugs and other problems. (not me being self-aware 🙈) please report such in the category term 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 want them fr fr.

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

also note 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. iykyk 💅

---

🔑 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 beauty is from tcllib, version 0.2, and it's term::receive::bind(n) — go forth and dispatch those keystrokes 💖✨🎀🦋🌸