Tcl_Eval(3)

💖 Tcl_Eval(3) — aka the "go run this script bestie" page 💖

okay so welcome to the Tcl_Eval(3) page of the Tcl Library Procedures, and no cap this one is lowkey the main character of the whole C API. grab a strawberry 🍓, we're executing Tcl scripts from C and it's gonna be iconic.

---

✨ NAME ✨

Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval — literally just: execute Tcl scripts. that's the whole job description. slay. 💅

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_EvalObjEx(interp, objPtr, flags)

int
Tcl_EvalFile(interp, fileName)

int
Tcl_EvalObjv(interp, objc, objv, flags)

int
Tcl_Eval(interp, script)

int
Tcl_EvalEx(interp, script, numBytes, flags)

int
Tcl_GlobalEval(interp, script)

int
Tcl_GlobalEvalObj(interp, objPtr)

int
Tcl_VarEval(interp, part, part, ... (char *)NULL)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter where we're executing the script. its result gets overwritten to hold either the result or the error message from the script. so yeah, whatever was chilling in there before? gone. 🙈
• Tcl_Obj *objPtr (in) — a Tcl value that is the script we're about to execute.
• int flags (in) — an OR'ed combo of flag bits for extra options. right now the supported ones are TCL_EVAL_GLOBAL and TCL_EVAL_DIRECT.
• const char *fileName (in) — name of a file that contains a Tcl script.
• Tcl_Size objc (in) — how many values live in the array objv points to. also = the number of words in the command. two truths, one number.
• Tcl_Obj **objv (in) — points to an array of pointers to values; each value holds one single word of the command we're executing.
• int numBytes (in) — how many bytes are in script, not counting any null terminator. if it's -1, then everything up to the first null byte gets used.
• const char *script (in) — points to the first byte of the script to execute. it's null-terminated and it's UTF-8.
• const char *part (in) — a string that forms part of a Tcl script.

---

🦋 DESCRIPTION 🦋

these procedures are how you execute Tcl scripts in literally every form you could want. Tcl_EvalObjEx is the core one, and a whole bunch of the others are just it in a little outfit.

Tcl_EvalObjEx executes the commands in the script stored in objPtr, and it keeps going until either an error happens or it reaches the end of the script. here's the cute part: if this is the first time objPtr has ever been executed, its commands get compiled into bytecode instructions, and then those get executed. the bytecodes get saved inside objPtr so that if that value ever gets evaluated again later, we can just skip the whole compilation step. caching queen. ✨

the return value from Tcl_EvalObjEx (and from every other procedure on this page) is a Tcl completion code, and it's one of TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE — or possibly some other integer value that originated in an extension. plus, a result value or an error message is left in interp's result, and you can grab it with Tcl_GetObjResult.

Tcl_EvalFile reads the file named by fileName and evaluates its contents as a Tcl script. it hands you back the same info as Tcl_EvalObjEx. if the file couldn't be read, you get a Tcl error back describing why it couldn't be read. heads up: the eofchar for files is "\x1A" (^Z) on all platforms. so if you need a "^Z" in code for string comparison, you can use "\x1A" and the Tcl interpreter will safely substitute it into "^Z". 🫶

Tcl_EvalObjv executes a single preparsed command instead of a whole script. the objc and objv arguments hold the values of the words for the Tcl command — one word per value in objv. it evaluates the command and returns a completion code and result exactly like Tcl_EvalObjEx. ⚠️ but bestie, listen: the caller of Tcl_EvalObjv has to manage the reference count of the elements of objv, making sure the values stay valid until Tcl_EvalObjv returns. no letting them evaporate mid-call.

Tcl_Eval is like Tcl_EvalObjEx, except the script comes in as a string instead of a value, and no compilation happens at all. the string should be a proper UTF-8 string as converted by Tcl_ExternalToUtfDString or Tcl_ExternalToUtf when it's known that it might possibly contain upper ASCII characters whose possible combinations might form a UTF-8 special code. the string gets parsed and executed directly (using Tcl_EvalObjv) instead of being compiled and run as bytecodes. and here's a lil tip that's actually in the docs: if you know the script is never gonna be executed again, Tcl_Eval may be faster than Tcl_EvalObjEx. one-shot energy. 💫 Tcl_Eval returns a completion code and result just like Tcl_EvalObjEx.

Tcl_EvalEx is the extended version of Tcl_Eval that takes the extra numBytes and flags arguments.

Tcl_GlobalEval and Tcl_GlobalEvalObj are the older procedures and they are now deprecated. 🚨 they're similar to Tcl_EvalEx and Tcl_EvalObjEx, except the script gets evaluated in the global namespace and its variable context consists of global variables only (it ignores any Tcl procedures that are active). these two are equivalent to using the TCL_EVAL_GLOBAL flag (see below).

Tcl_VarEval takes any number of string arguments of any length, concatenates them all into one single string, then calls Tcl_Eval to execute that string as a Tcl command. it returns the result of the command and also modifies the interpreter result the same way Tcl_Eval does. and the last argument to Tcl_VarEval must be (char *)NULL to mark the end of the arguments. don't forget it, fr fr.

---

🌈 FLAG BITS 🌈

any OR'ed combination of these values can go in the flags argument of procedures like Tcl_EvalObjEx:

• TCL_EVAL_DIRECT — this flag is only used by Tcl_EvalObjEx; every other procedure ignores it. if this bit is set, the script doesn't get compiled into bytecodes at all — instead it's executed directly, the same way Tcl_EvalEx does it. this flag is useful when the contents of a value are going to change immediately, meaning the bytecodes would never get reused in a future execution anyway. in that case, executing the script directly is faster. efficient queen. 👑
• TCL_EVAL_GLOBAL — if this flag is set, the script is evaluated in the global namespace instead of the current namespace, and its variable context consists of global variables only (it ignores any Tcl procedures that are active).

---

⭐ MISCELLANEOUS DETAILS ⭐

while a Tcl command is being processed, it's totally legal to make nested calls that evaluate other commands — that's literally how procedures and some control structures get implemented. 🪆 so if a code other than TCL_OK comes back from a nested Tcl_EvalObjEx invocation, the caller should normally return immediately, passing that same return code back up to its caller, and so on and so on until we hit the top-level application. a few commands, like for, will check for certain return codes, like TCL_BREAK and TCL_CONTINUE, and process them specially without returning. special treatment, deserved.

Tcl_EvalObjEx keeps track of how many nested Tcl_EvalObjEx invocations are in progress for interp. and if a code of TCL_RETURN, TCL_BREAK, or TCL_CONTINUE is about to be returned from the topmost Tcl_EvalObjEx invocation for interp, it converts that return code into TCL_ERROR and sets interp's result to an error message saying the return, break, or continue command was invoked in an inappropriate place. 💀 so basically: top-level applications should never see a return code from Tcl_EvalObjEx other than TCL_OK or TCL_ERROR. periodt.

---

💜 REFERENCE COUNT MANAGEMENT 💜

Tcl_EvalObjEx and Tcl_GlobalEvalObj both increment and decrement the reference count of their objPtr argument — which means you must not pass them any value with a reference count of zero. 🚫 they also manipulate the interpreter result, so you must not count on the interpreter result to hold the reference count of any value across these calls.

Tcl_EvalObjv may increment and decrement the reference count of any value passed via its objv argument — so again, you must not pass any value with a reference count of zero. this function also manipulates the interpreter result, so don't count on the interpreter result to hold the reference count of any value over this call either. 🫠

---

🔥 KEYWORDS 🔥

execute, file, global, result, script, value

---

okay that's the whole page, you're officially educated bestie 🎓✨ this was the Tcl_Eval(3) page from Tcl Library Procedures, version 8.1 — go forth and evaluate responsibly, mwah 💖🦋🌸