tclsh(1)

Okay bestie, manual page for tclsh(1) is here and it's giving tiny shell with a whole Tcl brain 🧚💖

🎀 NAME 🎀

tclsh - Simple shell containing Tcl interpreter ✨

🌸 SYNOPSIS 🌸

tclsh ?-encoding name? ?fileName arg arg ...?

---

💅 DESCRIPTION 💅

okay so tclsh is a shell-like app that reads Tcl commands from standard input or from a file, then evaluates them 🦋 With no arguments it runs interactively, reading commands from standard input and printing results and error messages to standard output. It keeps going until you invoke the exit command or it hits end-of-file on standard input 💀

Also, if there's a file called .tclshrc (or tclshrc.tcl on Windows) in your home directory, interactive tclsh will evaluate it as a Tcl script right before it reads the first command from standard input. Main character setup, no cap 👑

---

🦋 SCRIPT FILES 🦋

If you invoke tclsh with arguments, the first few arguments name a script file and, optionally, the encoding of the text data stored in that script file. Any extra arguments get handed to the script as variables (see below) ✨ Instead of reading standard input, tclsh reads Tcl commands from that named file, and it exits when it reaches the end of the file 🍓

The end of the file can be marked either by the physical end of the medium, or by the character "\032" ("\u001a", control-Z). If that character shows up in the file, the tclsh app reads text up to but not including it. Need that character in your file? Encode it safely as "\032", "\x1A", or "\u001a", or generate it with commands like format or binary. It's giving careful 🫶

There is no automatic evaluation of .tclshrc when you pass a script file on the tclsh command line. Your script can always source it manually if you want it, though 💜

If you make a Tcl script whose first line is:

#!/usr/local/bin/tclsh

then you can run the script file directly from your shell, as long as you mark the file as executable 🔥 This assumes tclsh got installed in the default location, /usr/local/bin. If it's somewhere else, you'll have to edit that line to match 🙈 Many UNIX systems won't let the #! line go over about 30 characters, so make sure the tclsh executable can be reached with a short file name 💀

An even better approach? Start your script files with these three lines:

#!/bin/sh
# the next line restarts using tclsh \
exec tclsh "$0" ${1+"$@"}

This approach has three advantages over the one above 🌈 First, the location of the tclsh binary doesn't have to be hard-wired into the script. It can live anywhere on your shell search path ✨ Second, it gets around the 30-character file name limit. Third, it works even if tclsh is itself a shell script (some systems do this to handle multiple architectures or operating systems, where the tclsh script picks one of several binaries to run) 🧚

Here's how the three lines work: both sh and tclsh process the script, but the exec only gets executed by sh. sh processes the script first, treats the second line as a comment, and executes the third line. The exec statement makes the shell stop processing and start up tclsh to reprocess the entire script. When tclsh starts up, it treats all three lines as comments, since the backslash at the end of the second line makes the third line part of the comment on the second line 😭

Also, it's super common to install tclsh with its version number in the name 🍒 This lets multiple Tcl versions live on the same system at once, but it makes it harder to write scripts that start up uniformly across different Tcl versions. Tradeoffs, bestie 🥺

---

🌈 VARIABLES 🌈

tclsh sets the following global Tcl variables, in addition to the ones the Tcl library creates itself (like env, which maps environment variables such as PATH into Tcl) 💖

• argc — Contains a count of the number of arg arguments (0 if none), not including the name of the script file.
• argv — Contains a Tcl list whose elements are the arg arguments, in order, or an empty string if there are no arg arguments.
• argv0 — Contains fileName if it was specified. Otherwise, it contains the name by which tclsh was invoked.
• tcl_interactive — Contains 1 if tclsh is running interactively (no fileName was specified and standard input is a terminal-like device), 0 otherwise.

---

💬 PROMPTS 💬

When tclsh runs interactively, it normally prompts for each command with "% " 🎀 You can change the prompt by setting the global variables tcl_prompt1 and tcl_prompt2. If tcl_prompt1 exists, it must be a Tcl script that outputs a prompt. Instead of outputting a prompt directly, tclsh evaluates the script in tcl_prompt1 ✨ The variable tcl_prompt2 works similarly when you hit newline but the current command isn't complete yet. If tcl_prompt2 isn't set, then no prompt gets output for incomplete commands 🦋

---

🔌 STANDARD CHANNELS 🔌

See Tcl_StandardChannels for more explanations 🧚

---

👀 SEE ALSO 👀

auto_path(3tcl), encoding(3tcl), env(3tcl), fconfigure(3tcl) 🍓

---

🫧 KEYWORDS 🫧

application, argument, interpreter, prompt, script file, shell 💜

---

That's the whole tea, bestie 🌈💖 Tcl source, tclsh(1) page, all sealed with a 💅 and a 🫶