source(n)

💖 source(n) — the Tcl Built-In Commands manual, but make it a group chat 💖

okay bestie, gather round, because this one is genuinely iconic. it's source, it lives in the Tcl Built-In Commands manual, and it's about to become your whole personality. no cap. 🫶

---

✨ NAME ✨

source — slurp up a file or resource and evaluate it as a Tcl script. that's it. that's the girl. 💅

---

🌸 SYNOPSIS 🌸

source fileName

source -encoding encodingName fileName

two forms, both slay. the first is the classic, the second lets you tell it what encoding to expect. 🌈

---

🦋 DESCRIPTION 🦋

okay so. source takes the entire contents of the file or resource you point it at and hands that whole thing to the Tcl interpreter like "here, read this as a text script." 💖

and the return value? it's the return value of the last command executed in the script. so whatever that final command spat out, that's what source hands back to you. periodt.

now for the plot twists:

• if an error happens while evaluating the contents of the script, then source will return that error. not hide it, not swallow it — return it. 😭
• if a return command gets invoked from inside the script, then the remainder of the file is skipped, and source returns normally with the result from that return command. so it's a graceful exit, not a crash. main character energy. 👑

---

🎀 the end-of-file character situation

the end-of-file character for files is "\32" (that's ^Z) for all platforms. yes, all of them. source will read files up to this character. 💀

heads up though: that restriction does not exist for the read or gets commands, which is what allows for files containing code and data segments — aka scripted documents. so if you need that flexibility, read/gets are your girls.

and if you genuinely require a "^Z" inside code for string comparison, use "\x1A" instead — it'll be safely substituted by the Tcl interpreter into "^Z". sneaky but valid. 🙈

---

🧚 BOM business

a leading BOM (Byte order mark) contained in the file is ignored for unicode encodings — that's utf-8, utf-16, and ucs-2. so don't stress about it. ✨

---

💜 the -encoding option

the -encoding option is how you specify the encoding of the data stored in fileName. 🍓

and when you just... don't mention -encoding at all? the utf-8 encoding is assumed. default behaviour, we love her.

---

🔥 EXAMPLE 🔥

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

source foo.tcl
source bar.tcl

or, alternatively, if you want to be fancy about it:

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

the second one is giving efficiency. the first one is giving "I have two files and I'm not sorry." both valid. ⭐

---

👑 SEE ALSO 👑

• file(n)
• cd(n)
• encoding(n)
• info(n)

go read those too, they're all in the same friend group. 🫶

---

🌈 KEYWORDS 🌈

file, script

iykyk. 💅

---

and that's the whole page, bestie — brought to you by the Tcl manual, source(n), straight out of the Tcl Built-In Commands collection. no version stamp or date on this one, just vibes and a very well-behaved interpreter. go forth and source something. 💖✨🎀