tclreadline(3tcl)

okay bestie, sit down, hydrate, and let's talk about tclreadline — this is the tclreadline(3tcl) manual page and it's genuinely iconic 💅

---

✨ NAME ✨

tclreadline — gnu readline for the tcl scripting language 🦋

---

✨ SYNOPSIS ✨

::tclreadline::readline command [options]

---

🌸 DESCRIPTION 🌸

So basically, the tclreadline package hands the gnu readline over to the tcl scripting language. Its whole main character purpose? Making interactive script development so much nicer, with word and file name completion plus history expansion — you know, the stuff bash girlies have had forever 😌

Also, tclreadline is not just for the interactive vibe: tcl scripts that want a shell-like input interface can use it too. In that case you have to call the ::tclreadline::readline read command explicitly. No cap.

The big advantage here: tclreadline uses the callback handler mechanism of the gnu readline while it's processing tcl events. Which means X events from a wish gui get processed right alongside events from the tclreadline line interface. Both. At once. Slay ✨

Under the hood, tclreadline is basically a shared library plus a few tcl scripts that you access with the tcl package require command. So it should play nicely with all the common extensions — blt, itcl, itk, tix … all of them 🫶

---

👑 COMMANDS 👑

Okay so real talk: if you just want tclreadline as a line interface for developing tcl scripts, you can lowkey skip this whole section. In that case the only thing you should do is modify your .tclshrc according to the section FILES.

For how the GNU readline itself behaves, go read readline's own documentation, bestie — that's not on me.

Here's the full list of commands that are currently implemented in the shared lib (like, e.g., libtclreadline2.4.0.so). Extra commands were introduced in a startup script called tclreadlineSetup.tcl, which lives in the tclreadline installation directory (typically something like /usr/local/lib/tclreadline ..). Those commands are primarily for internal use and are not documented here. Don't @ me.

Heads up: every single one of these commands lives in the namespace ::tclreadline::.

::tclreadline::readline add string

Adds a string to the completer. If the string contains white spaces, each of the words will be completed consecutively when you hit <Tab>. Example:

::tclreadline::readline add "button pathName ?options?"

Typing but<Tab> will complete to button. Hitting <Tab> again will complete to "button pathName". ...

::tclreadline::readline complete string

Returns 1 if string is a complete tcl command and 0 otherwise. Simple. Clean. We love her 💖

::tclreadline::readline customcompleter [string]

Registers the proc string as your custom completer. This proc gets called with exactly four arguments every single time completion happens: the word to complete (that's "text"), the "start" and "end" positions of that word in the line entered so far, and the line itself ("line"). Your custom completion script should return an array of strings, which is a list of completions for "text". If there are no completions, it should return an empty string "". The first entry in the returned list is the substitution for "text". The remaining entries are the possible completions. If your custom completion script returns an empty string and builtin completion is enabled (see tclreadline::readline builtincompleter), then the builtin completer gets called instead. Teamwork 🧚

tclreadline::readline customcompleter simply returns the current custom completer if you call it w/o string. To turn off custom completion, call tclreadline::readline customcompleter with an empty string.

Example: % puts $b<TAB> will call the custom completer with the four arguments "$b", "5", "8" and "puts $b". The custom completer could return a string like "$bl $black $blue", which will complete "$b" to "$bl" (the longest match) and offer a list of two further matches, "$black" and "$blue". Chef's kiss 👑

For further reference, see the proc tclreadline::ScriptCompleter in the file tclreadlineSetup.tcl.

::tclreadline::readline builtincompleter [bool]

Enable or disable the builtin completer. If the builtin completer is enabled, it will be invoked either when there is no custom completer, or when the custom completer returned an empty string. The builtin completer is on by default. tclreadline::readline builtincompleter returns the current custom completer (also if called w/o the bool argument).

::tclreadline::readline eofchar [script]

Sets a script which will be called if readline returns the eof character (this is typically the case if CTRL-D is entered at the very beginning of the line). The default for this script is "puts {}; exit". Setting this to an empty value disables any action on eof. tclreadline::readline eof returns the current eof script.

::tclreadline::readline initialize historyfile

Initialize the tclreadline interface and read the history from the historyfile. On success, an empty string is returned.

Real talk, this one is a must-do-first situation: this command has to be called before any other tclreadline commands. Periodt.

::tclreadline::readline read prompt

Prints the prompt to stdout and enters the tclreadline event loop. Both readline and X events are processed. Returns the (eventually history-expanded) input string. Heads up though — tclreadline::readline read raises an error if an error occurs while evaluating a script completer 😭

::tclreadline::readline write historyfile

Writes the history to the historyfile. This command is called automatically from the internal routine ::tclreadline::Exit. If the variable tclreadline::historyLength is non-negative, the historyfile will be truncated to hold only this number of lines.

::tclreadline::readline reset-terminal [terminalName]

Without argument: reset the state of the terminal to what it was before tclreadline was used. With argument: reinitialize readline's idea of the terminal settings, using terminalName as the terminal type.

Fair warning bestie: the form without argument might not work if tclreadline was compiled with an older version of libreadline. It's giving legacy energy 💀

::tclreadline::readline historyexpansion [bool]

Enable or disable history expansion. With no argument, it returns the current value.

::tclreadline::readline bell

Ring the terminal bell, obeying the setting of bell-style — audible or visible. Tiny drama, on demand 🔔

::tclreadline::text

Return the current input.

::tclreadline::readline update

Redraw the current input line.

::tclreadline::Print [yes / no]

Turns on or off the default behavior of tclsh to print the result of every command. This is turned on by default, so it will just behave as the tclsh w/o tclreadline. Turning it off might be useful when reading binary data, for example. If ::tclreadline::Print is called w/o arguments, it returns the current setting.

::tclreadline::Loop [historyfile]

Enter the tclreadline main loop. This command is typically called from the startup resource file (something .tclshrc, depending on the interpreter you use — see the file sample.tclshrc). The main loop sets up some completion characteristics as variable — try something like "puts $b<TAB>" — and command completion — try "puts [in<TAB>". If the optional argument historyfile is given, this file will be used for reading and writing the command history instead of the default .tclsh-history. ::tclreadline::Loop will normally not return.

If you want to write your own main loop and/or your own custom completers, it's probably a good idea to start with tclreadline::Loop (see the file tclreadlineSetup.tcl). Main character energy, but make it your own ✨

::tclreadline::prompt1

A proc which is called by ::tclreadline::Loop and returns a string which will be displayed as the primary prompt. This prompt will be something like "[info nameofexecutable] \[[pwd]\]", possibly fancy colored. The default proc is defined on entering the ::tclreadline::Loop, if it is not already defined. So: if you define your own proc ::tclreadline::prompt1 before entering ::tclreadline::Loop, this proc is called each time the prompt is to be displayed. Example:

package require tclreadline
namespace eval tclreadline {
    proc prompt1 {} {
        return "[clock format [clock seconds]]> "
    }
}
::tclreadline::Loop

Important detail, don't skip it: non-printable control characters (like color control characters) must be enclosed in literal ctrl-a / ctrl-b to tell readline the length of the printable prompt. See for example the variable prompt_string in the file tclreadlineSetup.tcl in your tclreadline installation directory. iykyk 🌈

::tclreadline::prompt2

A proc which is called by ::tclreadline::Loop and returns a string which will be displayed as the secondary prompt when interactively prompting for continuation of an incomplete command.

---

💜 VARIABLES 💜

tclreadline defines the following variables in the namespace ::tclreadline: (and for backwards compatibility, the global variables tclreadline_version, tclreadline_patchLevel and tclreadline_library are still present — we keep the old ones around, we're sentimental like that 🫶).

tclreadline::version (read-only)

Holds the version string "2.4.0".

tclreadline::patchLevel (read-only)

Holds the patch level string "2.4.0".

tclreadline::library (read-only)

Holds the library directory string.

tclreadline::license (read-only)

Holds a BSD license statement.

tclreadline::historyLength

Number of lines which will be written to the historyfile. This number is -1 by default, which means that the historyfile will not be truncated. See also tclreadline::write.

✨ FILES ✨

okay bestie, this is the part where your shell gets its lil personality from files in your HOME directory. 💖

First up: the .tclshrc file in the HOME directory, which is read on tclsh startup. Alternatively, the name of this initialization file might be .wishrc ... depending on what interpreter you use. These files should typically contain something like:

if {$tcl_interactive} {
    package require tclreadline
    ::tclreadline::Loop
}

which will enter the tclreadline main loop. ✨

Next: the .tclsh-history file in the HOME directory. On startup commands will be read from this file. On exit, the readline history is written to this file. Note that if you abort tclsh with <cntrl-c> no history is written. For the future it is planned to set up a signal handler, which will write the history on <ctrl-c> before exiting. 😭

Then: the .inputrc file in the users HOME directory. This file is used normally for all programs which use the gnu readline (e.g. bash). The global' readline settings there will be valid also for tclreadline. Additionally the .inputrc might hold conditional settings for the implementation name tclreadline. Example of some lines in your .inputrc:

$if tclreadline
"\C-xp": "puts $env(PATH)"
$endif

For further documentation please refer to the gnu readline documentation. 📚

---

💀 BUGS 💀

Citing the readline manual: It's too big and too slow.

not me exposing readline like this but okay periodt 💅

---

🔗 SEE ALSO 🔗

The official tclreadline web site at:

https://github.com/flightaware/tclreadline/

---

👑 AUTHOR 👑

Johannes Zellner, <johannes@zellner.org>

---

🫶 CONTRIBUTIONS, SUGGESTIONS AND PATCHES 🫶

• Magnus Eriksson <magnus.eriksson@netinsight.se>
• Les Johnson <les@infolabs.com>
• Harald Kirsch <kir@iitb.fhg.de>
• Christian Krone <krischan@sql.de>
• Larry W. Virden <lvirden@cas.org>
• David Engel <dlengel@home.com> <david@debian.org>
• Matthew Clarke <Matthew_Clarke@mindlink.bc.ca>

---

🎀 DEBIAN PACKAGE 🎀

David Engel <dlengel@home.com>, <david@debian.org>

---

🌈 DISCLAIMER 🌈

tclreadline comes with a BSD type license. The read-only variable tclreadline::license holds the complete license statement. 📜

---

okay bestie, that's the whole page — Johannes Zellner, version 2.4.0, tclreadline(3tcl). slay 💅✨