unknown(3tcl)

👑 unknown(3tcl) — Tcl Built-In Commands 💅

okay bestie, we're deep in the Tcl built-in commands today and this one is genuinely so fun. buckle up 🎀

---

✨ NAME ✨

unknown — the lil handler that catches it when you try to use a command that literally does not exist 🙈

---

🦋 SYNOPSIS 🦋

unknown cmdName ?arg arg ...?

---

💖 DESCRIPTION 💖

so here's the vibe: whenever a script tries to invoke a command that doesn't exist, the Tcl interpreter invokes this command. iconic, right? ✨

The default implementation of unknown is a library procedure that gets defined when Tcl initializes an interpreter. You can override that default unknown to change its functionality, or you can register a new handler for individual namespaces using the namespace unknown command. both are valid, do what feels right 🫶

🌸 real talk though: there is no default implementation of unknown in a safe interpreter. so don't be surprised, okay?

Now here's the actual flow, and it's giving detective energy 🔍. If the Tcl interpreter encounters a command name for which there is not a defined command — whether in the current namespace or the global namespace — then Tcl checks for the existence of an unknown handler for the current namespace. By default, this handler is a command named ::unknown. If there is no such command, then the interpreter returns an error 💀. If the unknown command does exist (or a new handler has been registered for the current namespace), then it gets invoked with arguments consisting of the fully-substituted name and arguments for the original non-existent command.

The unknown command typically does things like:

• searching through library directories for a command procedure with the name cmdName 🔎
• expanding abbreviated command names to full-length 📏
• automatically executing unknown commands as sub-processes ⚙️

In some cases (like expanding abbreviations) unknown will change the original command slightly and then (re-)execute it. and the result of the unknown command is used as the result for the original non-existent command. no cap 🧚

---

🌈 the default implementation, step by step 🌈

The default implementation of unknown behaves as follows, and honestly it's a whole journey:

1. It first calls the auto_load library procedure to load the command. If this succeeds, then it executes the original command with its original arguments. slay ✨
2. If the auto-load fails and Tcl is run interactively, then unknown calls auto_execok to see if there is an executable file by the name cmd. If so, it invokes the Tcl exec command with cmd and all the args as arguments.
3. If cmd cannot be auto-executed, unknown checks to see if the command was invoked at top-level and outside of any script. If so, then unknown takes two additional steps:
   • First, it sees if cmd has one of the following three forms: !!, !event, or ^old^new?^?. If so, then unknown carries out history substitution in the same way that csh would for these constructs. yes really, we're doing csh history substitution in the year of our lord 😭
   • Finally, unknown checks to see if cmd is a unique abbreviation for an existing Tcl command. If so, it expands the command name and executes the command with the original arguments 👑
4. If none of the above efforts has been able to execute the command, unknown generates an error return.

Some global variables you should know about:

• If the global variable auto_noload is defined, then the auto-load step is skipped.
• If the global variable auto_noexec is defined then the auto-exec step is skipped.

Under normal circumstances the return value from unknown is the return value from the command that was eventually executed. periodt 💅

---

🍓 EXAMPLE 🍓

Arrange for the unknown command to have its standard behavior except for first logging the fact that a command was not found:

# Save the original one so we can chain to it
rename unknown _original_unknown

# Provide our own implementation
proc unknown args {
    puts stderr "WARNING: unknown command: $args"
    uplevel 1 [list _original_unknown {*}$args]
}

---

🔥 SEE ALSO 🔥

• info(3tcl)
• proc(3tcl)
• interp(3tcl)
• library(3tcl)
• namespace(3tcl)

---

⭐ KEYWORDS ⭐

error, non-existent command, unknown

---

and that's the whole page bestie 🫶 this is Tcl's built-in commands manual, the unknown(3tcl) page, and it's giving peak 3tcl energy. go forth and handle your non-existent commands with main character energy 💖✨🎀