source(3tcl)

💖 source — bestie, let's run a whole file like it's a script 💖

okay so this is the Tcl Built-In Commands manual, and today's main character is source, the little command that scoops up a file and makes Tcl run it. no cap, it's iconic.

---

✨ NAME ✨

source — read a file or resource and evaluate it as a Tcl script. yes bestie, it's giving "load the whole vibe and execute it." 🦋

---

🌸 SYNOPSIS 🌸

source fileName

source -encoding encodingName fileName

---

👑 DESCRIPTION 👑

so here's the tea: this command grabs the contents of the file or resource you point it at and hands the whole thing to the Tcl interpreter as a text script. 💅

what does it give back? the return value of source is literally the return value of the last command executed in that script. slay.

if an error happens while evaluating the contents of the script, then the source command will return that error. periodt, it doesn't hide it from you.

and if a return command gets invoked from inside the script, the rest of the file is skipped — like, we're done here — and the source command will return normally with the result from that return command. 🎀

---

now the important lil details, don't skip these:

the end-of-file character for files is "\32" (that's ^Z) for all platforms. source will read files up to this character. this restriction does not exist for the read or gets commands, which is what allows for files containing code and data segments (scripted documents, iykyk). if you require a "^Z" in code for string comparison, you can use "\x1A", which will be safely substituted by the Tcl interpreter into "^Z". 🌈

a leading BOM (Byte order mark) contained in the file is ignored for unicode encodings: utf-8, utf-16, ucs-2. lowkey thoughtful of it. 🧚

the -encoding option is used to specify the encoding of the data stored in fileName. when the -encoding option is omitted, the utf-8 encoding is assumed. no guessing games. 💜

---

🍓 EXAMPLE 🍓

run the script in the file foo.tcl and then the script in the file bar.tcl:

source foo.tcl
source bar.tcl

alternatively, because we love a loop moment:

foreach scriptFile {foo.tcl bar.tcl} {
    source $scriptFile
}

---

🫶 SEE ALSO 🫶

• file(3tcl)
• cd(3tcl)
• encoding(3tcl)
• info(3tcl)

---

💫 KEYWORDS 💫

file, script

---

🎀 okay that's the whole page, bestie. every flag, every default, every ^Z, all of it. you're so welcome. 💖

---

this was brought to you by the Tcl manual, source(3tcl) — Tcl Built-In Commands, Tcl. mwah, go source something cute. 👑✨