Tcl C API 概览(一)
tcl解释器管理
解释器是Tcl的核心概念。这部分API用于创建、删除和管理Tcl解释器。
Tcl_CreateInterp
功能: 创建一个新的Tcl解释器
语法: Tcl_Interp *Tcl_CreateInterp(void)
返回值: 新创建的解释器的指针
说明:
- 创建一个新的Tcl解释器实例
- 必须使用Tcl_DeleteInterp释放
示例:
1Tcl_Interp *interp = Tcl_CreateInterp();
2if (interp == NULL) {
3 // 处理错误
4}
Tcl_DeleteInterp
功能: 删除Tcl解释器
语法: void Tcl_DeleteInterp(Tcl_Interp *interp)
参数:
interp: 要删除的解释器
说明:
- 释放与解释器相关的所有资源
- 调用所有已注册的退出处理程序
示例:
1Tcl_DeleteInterp(interp);
Tcl_InterpDeleted
功能: 检查解释器是否已被删除
语法: int Tcl_InterpDeleted(Tcl_Interp *interp)
参数:
interp: 要检查的解释器
返回值: 如果解释器已被删除返回1，否则返回0
说明:
- 用于检查解释器的状态，特别是在异步操作中
示例:
1if (Tcl_InterpDeleted(interp)) {
2// 解释器已被删除，进行相应处理
3}
Tcl_Preserve
功能: 增加对象的引用计数
语法: void Tcl_Preserve(ClientData data)
参数:
data: 要增加引用计数的对象
说明:
用于防止对象被过早删除
必须与Tcl_Release配对使用
示例:
1Tcl_Preserve(interp);
2// 使用interp
3Tcl_Release(interp);
Tcl_Release
功能: 减少对象的引用计数
语法: void Tcl_Release(ClientData data)
参数:
* data: 要减少引用计数的对象
说明:
- 与Tcl_Preserve配对使用
- 当引用计数降为0时，对象可能会被删除
示例:
1Tcl_Release(interp);
Tcl_GetMaster
功能: 获取从解释器的主解释器
语法: Tcl_Interp *Tcl_GetMaster(Tcl_Interp *interp)
参数:
interp: 从解释器
返回值: 主解释器的指针，如果没有则返回NULL
说明:
- 用于获取从解释器的主解释器
- 主要用于安全和限制操作
示例:
1Tcl_Interp *masterInterp = Tcl_GetMaster(slaveInterp);
2if (masterInterp != NULL) {
3// 使用主解释器
4}
Tcl_GetSlave
功能: 获取主解释器的指定从解释器
语法: Tcl_Interp *Tcl_GetSlave(Tcl_Interp *interp, const char *slaveName)
参数:
interp: 主解释器slaveName: 从解释器的名称
返回值: 从解释器的指针，如果不存在则返回NULL
说明:
- 用于获取指定名称的从解释器
- 主要用于管理多个解释器的场景
示例:
1Tcl_Interp *slaveInterp = Tcl_GetSlave(masterInterp, "slave1");
2if (slaveInterp != NULL) {
3// 使用从解释器
4}
Tcl_CreateSlave
功能: 创建一个新的从解释器
语法: Tcl_Interp *Tcl_CreateSlave(Tcl_Interp *interp, const char *slaveName, int isSafe)
参数:
interp: 主解释器slaveName: 新从解释器的名称isSafe: 是否创建安全解释器（0为否，1为是）
返回值: 新创建的从解释器的指针
说明:
- 创建一个新的从解释器，可以是安全或非安全的
- 安全解释器有限制，不能执行某些潜在危险的操作
示例:
1Tcl_Interp *safeSlaveInterp = Tcl_CreateSlave(masterInterp, "safeSlave", 1);
2if (safeSlaveInterp != NULL) {
3// 使用安全从解释器
4}
Tcl_MakeSafe
功能: 将解释器转换为安全模式
语法: int Tcl_MakeSafe(Tcl_Interp *interp)
参数:
interp: 要转换的解释器
返回值: 成功返回TCL_OK，失败返回TCL_ERROR
说明:
- 将现有解释器转换为安全模式
- 移除所有可能不安全的命令和功能
示例:
1if (Tcl_MakeSafe(interp) == TCL_OK) {
2// 解释器现在处于安全模式
3} else {
4// 转换失败，处理错误
5}
Tcl_LimitCheck
功能: 检查解释器是否超过了资源限制
语法: int Tcl_LimitCheck(Tcl_Interp *interp)
参数:
interp: 要检查的解释器
返回值: 如果超过限制返回1，否则返回0
说明:
- 用于检查解释器是否超过了预设的资源限制
- 主要用于防止脚本无限执行或消耗过多资源
示例:
1if (Tcl_LimitCheck(interp)) {
2// 解释器超过了资源限制，采取相应措施
3}
Tcl_SetRecursionLimit
功能: 设置解释器的递归限制
语法: int Tcl_SetRecursionLimit(Tcl_Interp *interp, int depth)
参数:
interp: 要设置的解释器depth: 新的递归深度限制
返回值: 旧的递归深度限制
说明:
- 用于防止过深的递归导致栈溢出
- 默认限制通常为1000
示例:
1int oldLimit = Tcl_SetRecursionLimit(interp, 500);
2printf("Old recursion limit was: %d\n", oldLimit);
脚本执行
这部分API用于在Tcl解释器中执行Tcl脚本和表达式。
Tcl_Eval
功能: 在解释器中执行Tcl脚本
语法: int Tcl_Eval(Tcl_Interp *interp, const char *script)
参数:
interp: 执行脚本的解释器script: 要执行的Tcl脚本字符串
返回值: TCL_OK表示成功，TCL_ERROR表示失败
说明:
- 执行给定的Tcl脚本
- 结果存储在解释器的结果中
示例:
1const char *script = "set x 10; incr x";
2if (Tcl_Eval(interp, script) == TCL_OK) {
3 printf("Result: %s\n", Tcl_GetStringResult(interp));
4} else {
5 printf("Error: %s\n", Tcl_GetStringResult(interp));
6}
Tcl_EvalEx
功能: 在解释器中执行Tcl脚本，带有额外选项
语法: int Tcl_EvalEx(Tcl_Interp *interp, const char *script, int length, int flags)
参数:
interp: 执行脚本的解释器script: 要执行的Tcl脚本字符串length: 脚本的长度（如果为-1，则使用strlen计算）flags: 执行标志（如TCL_EVAL_GLOBAL）
返回值: TCL_OK表示成功，TCL_ERROR表示失败
说明:
- 比Tcl_Eval更灵活，可以指定脚本长度和执行标志
- 常用于执行全局范围的脚本
示例:
1const char *script = "set x 20; return $x";
2int result = Tcl_EvalEx(interp, script, -1, TCL_EVAL_GLOBAL);
3if (result == TCL_OK) {
4printf("Result: %s\n", Tcl_GetStringResult(interp));
5}
Tcl_EvalObj
功能: 执行Tcl_Obj对象表示的脚本
语法: int Tcl_EvalObj(Tcl_Interp *interp, Tcl_Obj *objPtr)
参数:
interp: 执行脚本的解释器objPtr: 包含Tcl脚本的Tcl_Obj对象
返回值: TCL_OK表示成功，TCL_ERROR表示失败
说明:
- 用于执行存储在Tcl_Obj中的脚本
- 通常比Tcl_Eval更高效，特别是对于重复执行的脚本
示例:
1Tcl_Obj *scriptObj = Tcl_NewStringObj("expr 2 + 2", -1);
2if (Tcl_EvalObj(interp, scriptObj) == TCL_OK) {
3printf("Result: %s\n", Tcl_GetStringResult(interp));
4}
5Tcl_DecrRefCount(scriptObj);
Tcl_EvalObjEx
功能: 在指定的解释器中执行 Tcl 脚本对象
语法: int Tcl_EvalObjEx(Tcl_Interp *interp, Tcl_Obj *objPtr, int flags)
返回值: TCL_OK 表示成功,其他值表示错误
说明:
- 执行由 objPtr 表示的 Tcl 脚本
- flags 参数可以是 TCL_EVAL_GLOBAL 或 0
示例:
1Tcl_Obj *scriptObj = Tcl_NewStringObj("puts {Hello, World!}", -1);
2int result = Tcl_EvalObjEx(interp, scriptObj, 0);
3if (result != TCL_OK) {
4 // 处理错误
5}
6Tcl_DecrRefCount(scriptObj);
Tcl_GlobalEval
功能: 在全局范围内执行Tcl脚本
语法: int Tcl_GlobalEval(Tcl_Interp *interp, const char *script)
参数:
interp: 执行脚本的解释器script: 要执行的Tcl脚本字符串
返回值: TCL_OK表示成功，TCL_ERROR表示失败
说明:
- 在全局范围内执行脚本，忽略当前过程的局部变量
- 等同于在Tcl中使用
global命令
示例:
1const char *script = "set ::globalVar 100";
2if (Tcl_GlobalEval(interp, script) == TCL_OK) {
3printf("Global variable set\n");
4}
Tcl_GlobalEvalObj
功能: 在全局级别执行 Tcl 脚本对象
语法: int Tcl_GlobalEvalObj(Tcl_Interp *interp, Tcl_Obj *objPtr)
返回值: TCL_OK 表示成功,其他值表示错误
说明:
- 在全局级别执行脚本,忽略当前过程调用栈
- 等同于在顶层调用 Tcl_EvalObjEx 并设置 TCL_EVAL_GLOBAL 标志
示例:
1Tcl_Obj *scriptObj = Tcl_NewStringObj("set ::globalVar 42", -1);
2int result = Tcl_GlobalEvalObj(interp, scriptObj);
3if (result != TCL_OK) {
4 // 处理错误
5}
6Tcl_DecrRefCount(scriptObj);
Tcl_VarEval
功能: 连接多个字符串并作为Tcl脚本执行
语法: int Tcl_VarEval(Tcl_Interp *interp, ...)
参数:
interp: 执行脚本的解释器...: 可变数量的字符串参数，以NULL结束
返回值: TCL_OK表示成功，TCL_ERROR表示失败
说明:
- 将多个字符串连接成一个脚本并执行
- 最后一个参数必须是NULL
示例:
1if (Tcl_VarEval(interp, "set x 10; ", "incr x; ", "return $x", NULL) == TCL_OK) {
2printf("Result: %s\n", Tcl_GetStringResult(interp));
3}
Tcl_ExprObj
功能: 计算Tcl表达式
语法: int Tcl_ExprObj(Tcl_Interp *interp, Tcl_Obj *objPtr, Tcl_Obj **resultPtrPtr)
参数:
interp: 执行表达式的解释器objPtr: 包含表达式的Tcl_Obj对象resultPtrPtr: 指向Tcl_Obj指针的指针，用于存储结果
返回值: TCL_OK表示成功，TCL_ERROR表示失败
说明:
- 计算Tcl表达式并返回结果
- 结果存储在
resultPtrPtr指向的Tcl_Obj中
示例:
1Tcl_Obj *exprObj = Tcl_NewStringObj("2 * (3 + 4)", -1);
2Tcl_Obj *resultObj;
3if (Tcl_ExprObj(interp, exprObj, &resultObj) == TCL_OK) {
4int result;
5Tcl_GetIntFromObj(interp, resultObj, &result);
6printf("Result: %d\n", result);
7}
8Tcl_DecrRefCount(exprObj);
Tcl_ExprString
功能: 计算字符串形式的Tcl表达式
语法: int Tcl_ExprString(Tcl_Interp *interp, const char *expr)
参数:
interp: 执行表达式的解释器expr: 包含表达式的字符串
返回值: TCL_OK表示成功，TCL_ERROR表示失败
说明:
- 计算字符串形式的Tcl表达式
- 结果存储在解释器的结果中
示例:
1const char *expr = "5 + 3 * 2";
2if (Tcl_ExprString(interp, expr) == TCL_OK) {
3printf("Result: %s\n", Tcl_GetStringResult(interp));
4}
Tcl_ExprLong
功能: 计算 Tcl 表达式并返回长整型结果
语法: int Tcl_ExprLong(Tcl_Interp *interp, const char *expr, long *longPtr)
返回值: TCL_OK 表示成功,其他值表示错误
说明:
- 计算字符串形式的 Tcl 表达式
- 结果存储在 longPtr 指向的位置 示例:
1long result;
2int status = Tcl_ExprLong(interp, "2 + 3 * 4", &result);
3if (status == TCL_OK) {
4 printf("Result: %ld\n", result);
5} else {
6 // 处理错误
7}
Tcl_ExprDouble
功能: 计算 Tcl 表达式并返回双精度浮点型结果
语法: int Tcl_ExprDouble(Tcl_Interp *interp, const char *expr, double *doublePtr)
返回值: TCL_OK 表示成功,其他值表示错误
说明:
- 计算字符串形式的 Tcl 表达式
- 结果存储在 doublePtr 指向的位置
示例:
1double result;
2int status = Tcl_ExprDouble(interp, "3.14 * 2.0", &result);
3if (status == TCL_OK) {
4 printf("Result: %f\n", result);
5} else {
6 // 处理错误
7}
Tcl_ExprBoolean
功能: 计算 Tcl 表达式并返回布尔结果
语法: int Tcl_ExprBoolean(Tcl_Interp *interp, const char *expr, int *boolPtr)
返回值: TCL_OK 表示成功,其他值表示错误
说明:
- 计算字符串形式的 Tcl 表达式
- 结果存储在 boolPtr 指向的位置(0 表示 false,1 表示 true)
示例:
1int result;
2int status = Tcl_ExprBoolean(interp, "5 > 3", &result);
3if (status == TCL_OK) {
4 printf("Result: %s\n", result ? "true" : "false");
5} else {
6 // 处理错误
7}
Tcl_SubstObj
功能: 对 Tcl 对象进行替换处理
语法: Tcl_Obj *Tcl_SubstObj(Tcl_Interp *interp, Tcl_Obj *objPtr, int flags)
返回值: 新的 Tcl 对象,包含替换后的结果
说明:
- 对给定的 Tcl 对象进行变量和命令替换
- flags 参数控制替换的类型(TCL_SUBST_VARIABLES, TCL_SUBST_COMMANDS 等)
示例:
1Tcl_Obj *originalObj = Tcl_NewStringObj("Hello, $name!", -1);
2Tcl_Obj *resultObj = Tcl_SubstObj(interp, originalObj, TCL_SUBST_VARIABLES);
3if (resultObj != NULL) {
4 char *result = Tcl_GetString(resultObj);
5 printf("Substituted: %s\n", result);
6 Tcl_DecrRefCount(resultObj);
7}
8Tcl_DecrRefCount(originalObj);
命令创建和管理
这部分API用于创建新的Tcl命令、管理现有命令，以及处理命令相关的操作。
Tcl_CreateCommand
功能: 创建一个新的 Tcl 命令
语法: Tcl_Command Tcl_CreateCommand(Tcl_Interp *interp, const char *cmdName, Tcl_CmdProc *proc, ClientData clientData, Tcl_CmdDeleteProc *deleteProc)
返回值: 新创建的命令的令牌
说明:
- 在解释器中创建一个新的 Tcl 命令
- proc 是命令的实现函数
- clientData 是传递给 proc 和 deleteProc 的任意数据
示例:
1int HelloCmd(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
2 Tcl_SetResult(interp, "Hello, World!", TCL_STATIC);
3 return TCL_OK;
4}
5Tcl_CreateCommand(interp, "hello", HelloCmd, NULL, NULL);
Tcl_CreateObjCommand
功能: 创建一个新的Tcl命令
语法: Tcl_Command Tcl_CreateObjCommand(Tcl_Interp *interp, const char *cmdName, Tcl_ObjCmdProc *proc, ClientData clientData, Tcl_CmdDeleteProc *deleteProc)
参数:
interp: 解释器cmdName: 新命令的名称proc: 实现命令的C函数clientData: 传递给命令处理函数的客户端数据deleteProc: 命令被删除时调用的函数（可为NULL）
返回值: 新创建命令的令牌
说明:
- 创建一个新的Tcl命令，该命令可以从Tcl脚本中调用
proc函数接收Tcl_Obj参数，通常比Tcl_CreateCommand更高效
示例:
1int HelloCmd(ClientData clientData, Tcl_Interp *interp, int objc, Tcl_Obj *const objv[]) {
2 Tcl_SetObjResult(interp, Tcl_NewStringObj("Hello, World!", -1));
3 return TCL_OK;
4}
5Tcl_CreateObjCommand(interp, "hello", HelloCmd, NULL, NULL);
Tcl_DeleteCommand
功能: 删除一个Tcl命令
语法: int Tcl_DeleteCommand(Tcl_Interp *interp, const char *cmdName)
参数:
interp: 解释器cmdName: 要删除的命令名称
返回值: 成功返回0，失败返回-1
说明:
- 从解释器中删除指定的命令
- 如果命令不存在，返回-1
示例:
1if (Tcl_DeleteCommand(interp, "hello") == 0) {
2printf("Command 'hello' deleted successfully\n");
3} else {
4printf("Failed to delete command 'hello'\n");
5}
Tcl_GetCommandInfo
功能: 获取命令的信息
语法: int Tcl_GetCommandInfo(Tcl_Interp *interp, const char *cmdName, Tcl_CmdInfo *infoPtr)
参数:
interp: 解释器cmdName: 命令名称infoPtr: 指向Tcl_CmdInfo结构的指针，用于存储命令信息
返回值: 如果命令存在返回1，否则返回0
说明:
- 获取指定命令的详细信息，包括实现函数、客户端数据等
- 信息存储在infoPtr指向的结构中
示例:
1Tcl_CmdInfo info;
2if (Tcl_GetCommandInfo(interp, "hello", &info)) {
3printf("Command 'hello' exists\n");
4// 使用info中的信息
5} else {
6printf("Command 'hello' does not exist\n");
7}
Tcl_SetCommandInfo
功能: 修改现有命令的信息
语法: int Tcl_SetCommandInfo(Tcl_Interp *interp, const char *cmdName, const Tcl_CmdInfo *infoPtr)
参数:
interp: 解释器cmdName: 命令名称infoPtr: 指向包含新信息的Tcl_CmdInfo结构的指针
返回值: 成功返回1，失败返回0
说明:
- 修改指定命令的实现函数、客户端数据等信息
- 通常用于重新定义现有命令的行为
示例:
1Tcl_CmdInfo info;
2Tcl_GetCommandInfo(interp, "hello", &info);
3info.objProc = NewHelloCmd; // 假设NewHelloCmd是一个新的命令处理函数
4if (Tcl_SetCommandInfo(interp, "hello", &info)) {
5printf("Command 'hello' updated\n");
6} else {
7printf("Failed to update command 'hello'\n");
8}
Tcl_GetCommandName
功能: 获取命令的名称
语法: const char *Tcl_GetCommandName(Tcl_Interp *interp, Tcl_Command command)
参数:
interp: 解释器command: 命令令牌
返回值: 命令的名称（字符串）
说明:
- 根据命令令牌获取命令的名称
- 通常用于从命令令牌反向查找命令名
示例:
1Tcl_Command cmd = Tcl_FindCommand(interp, "hello", NULL, 0);
2if (cmd != NULL) {
3const char *name = Tcl_GetCommandName(interp, cmd);
4printf("Command name: %s\n", name);
5}
Tcl_GetCommandFullName
功能: 获取命令的完整名称
语法: void Tcl_GetCommandFullName(Tcl_Interp *interp, Tcl_Command command, Tcl_Obj *objPtr)
返回值: 无
说明:
- 获取指定命令的完整名称,包括命名空间
- 结果存储在 objPtr 中
示例:
1Tcl_Command cmd = Tcl_FindCommand(interp, "hello", NULL, 0);
2Tcl_Obj *nameObj = Tcl_NewObj();
3Tcl_GetCommandFullName(interp, cmd, nameObj);
4printf("Full name: %s\n", Tcl_GetString(nameObj));
5Tcl_DecrRefCount(nameObj);
Tcl_CreateEnsemble
功能: 创建一个命令集合
语法: Tcl_Command Tcl_CreateEnsemble(Tcl_Interp *interp, const char *name, Tcl_Namespace *namespacePtr, int flags)
参数:
interp: 解释器name: 集合的名称namespacePtr: 集合所属的命名空间（可为NULL）flags: 控制集合行为的标志
返回值: 新创建集合的命令令牌
说明:
- 创建一个命令集合，可以包含多个子命令
- 使用集合可以组织相关的命令，提高可读性和可维护性
示例:
1Tcl_Command ensemble = Tcl_CreateEnsemble(interp, "math", NULL, 0);
2Tcl_Obj *subcommands = Tcl_NewListObj(0, NULL);
3Tcl_ListObjAppendElement(interp, subcommands, Tcl_NewStringObj("add", -1));
4Tcl_ListObjAppendElement(interp, subcommands, Tcl_NewStringObj("subtract", -1));
5Tcl_SetEnsembleSubcommandList(interp, ensemble, subcommands);
Tcl_FindCommand
功能: 查找指定名称的命令
语法: Tcl_Command Tcl_FindCommand(Tcl_Interp *interp, const char *name, Tcl_Namespace *contextNsPtr, int flags)
参数:
interp: 解释器name: 要查找的命令名称contextNsPtr: 搜索的上下文命名空间（可为NULL）flags: 控制查找行为的标志
返回值: 找到的命令的令牌，如果未找到则返回NULL
说明:
- 在指定的上下文中查找命令
- 可以用于检查命令是否存在，或获取命令的令牌以进行进一步操作
示例:
1Tcl_Command cmd = Tcl_FindCommand(interp, "hello", NULL, 0);
2if (cmd != NULL) {
3printf("Command 'hello' found\n");
4} else {
5printf("Command 'hello' not found\n");
6}
Tcl_TraceCommand
功能: 为命令添加跟踪
语法: int Tcl_TraceCommand(Tcl_Interp *interp, const char *cmdName, int flags, Tcl_CmdTraceProc *proc, ClientData clientData)
返回值: TCL_OK 表示成功,TCL_ERROR 表示失败
说明:
- 为指定的命令添加跟踪回调
- flags 指定何时调用跟踪过程(TCL_TRACE_RENAME, TCL_TRACE_DELETE 等)
示例:
1int CmdTraceProc(ClientData clientData, Tcl_Interp *interp, const char *oldName, const char *newName, int flags) {
2 printf("Command %s traced\n", oldName);
3 return TCL_OK;
4}
5Tcl_TraceCommand(interp, "hello", TCL_TRACE_RENAME | TCL_TRACE_DELETE, CmdTraceProc, NULL);
Tcl_UntraceCommand
功能: 移除命令的跟踪
语法: void Tcl_UntraceCommand(Tcl_Interp *interp, const char *cmdName, int flags, Tcl_CmdTraceProc *proc, ClientData clientData)
返回值: 无
说明:
- 移除之前通过 Tcl_TraceCommand 添加的跟踪
- 参数必须与添加跟踪时使用的参数完全匹配
示例:
1Tcl_UntraceCommand(interp, "hello", TCL_TRACE_RENAME | TCL_TRACE_DELETE, CmdTraceProc, NULL);
变量操作
这部分API用于在Tcl环境中创建、修改、获取和删除变量。
Tcl_SetVar
功能: 设置Tcl变量的值
语法: const char *Tcl_SetVar(Tcl_Interp *interp, const char *varName, const char *newValue, int flags)
参数:
interp: 解释器varName: 变量名newValue: 新的变量值flags: 控制变量设置行为的标志（如TCL_GLOBAL_ONLY）
返回值: 成功返回变量的新值，失败返回NULL
说明:
- 设置或创建一个Tcl变量
- 可以通过flags参数控制变量的作用域和行为
示例:
1const char *result = Tcl_SetVar(interp, "x", "100", TCL_GLOBAL_ONLY);
2if (result != NULL) {
3 printf("Variable 'x' set to: %s\n", result);
4} else {
5 printf("Failed to set variable 'x'\n");
6}
Tcl_SetVar2
功能: 设置数组元素或嵌套变量的值
语法: const char *Tcl_SetVar2(Tcl_Interp *interp, const char *part1, const char *part2, const char *newValue, int flags)
参数:
interp: 解释器part1: 变量名或数组名part2: 数组索引或嵌套变量名（可为NULL）newValue: 新的变量值flags: 控制变量设置行为的标志
返回值: 成功返回变量的新值，失败返回NULL
说明:
- 用于设置数组元素或嵌套变量的值
- 如果part2为NULL，则行为与Tcl_SetVar相同
示例:
1const char *result = Tcl_SetVar2(interp, "arr", "index", "value", TCL_GLOBAL_ONLY);
2if (result != NULL) {
3printf("Array element 'arr(index)' set to: %s\n", result);
4} else {
5printf("Failed to set array element\n");
6}
Tcl_SetVar2Ex
功能: 设置变量的值
语法: Tcl_Obj *Tcl_SetVar2Ex(Tcl_Interp *interp, const char *part1, const char *part2, Tcl_Obj *newValuePtr, int flags)
返回值: 指向变量新值的 Tcl_Obj 指针,如果出错则返回 NULL
说明:
- 设置一个变量的值,可以是标量或数组元素
- part1 是变量名,part2 用于数组元素(可以为 NULL)
- flags 控制变量的查找和设置方式
示例:
1Tcl_Obj *value = Tcl_NewIntObj(42);
2Tcl_SetVar2Ex(interp, "myVar", NULL, value, TCL_LEAVE_ERR_MSG);
Tcl_GetVar
功能: 获取Tcl变量的值
语法: const char *Tcl_GetVar(Tcl_Interp *interp, const char *varName, int flags)
参数:
interp: 解释器varName: 变量名flags: 控制变量获取行为的标志
返回值: 成功返回变量的值，失败返回NULL
说明:
- 获取指定Tcl变量的值
- 可以通过flags参数控制变量的作用域和行为
示例:
1const char *value = Tcl_GetVar(interp, "x", TCL_GLOBAL_ONLY);
2if (value != NULL) {
3printf("Value of 'x': %s\n", value);
4} else {
5printf("Variable 'x' not found\n");
6}
Tcl_GetVar2
功能: 获取数组元素或嵌套变量的值
语法: const char *Tcl_GetVar2(Tcl_Interp *interp, const char *part1, const char *part2, int flags)
参数:
interp: 解释器part1: 变量名或数组名part2: 数组索引或嵌套变量名（可为NULL）flags: 控制变量获取行为的标志
返回值: 成功返回变量的值，失败返回NULL
说明:
- 用于获取数组元素或嵌套变量的值
- 如果part2为NULL，则行为与Tcl_GetVar相同
示例:
1const char *value = Tcl_GetVar2(interp, "arr", "index", TCL_GLOBAL_ONLY);
2if (value != NULL) {
3printf("Value of 'arr(index)': %s\n", value);
4} else {
5printf("Array element not found\n");
6}
Tcl_GetVar2Ex
功能: 获取变量的值
语法: Tcl_Obj *Tcl_GetVar2Ex(Tcl_Interp *interp, const char *part1, const char *part2, int flags)
返回值: 指向变量值的 Tcl_Obj 指针,如果变量不存在则返回 NULL
说明:
- 获取一个变量的值,可以是标量或数组元素
- part1 是变量名,part2 用于数组元素(可以为 NULL)
- flags 控制变量的查找方式
示例:
1Tcl_Obj *value = Tcl_GetVar2Ex(interp, "myVar", NULL, TCL_LEAVE_ERR_MSG);
2if (value) {
3 int intValue;
4 Tcl_GetIntFromObj(interp, value, &intValue);
5 printf("Value: %d\n", intValue);
6}
Tcl_UnsetVar
功能: 删除Tcl变量
语法: int Tcl_UnsetVar(Tcl_Interp *interp, const char *varName, int flags)
参数:
interp: 解释器varName: 要删除的变量名flags: 控制变量删除行为的标志
返回值: 成功返回TCL_OK，失败返回TCL_ERROR
说明:
- 删除指定的Tcl变量
- 可以通过flags参数控制变量的作用域和行为
示例:
1if (Tcl_UnsetVar(interp, "x", TCL_GLOBAL_ONLY) == TCL_OK) {
2printf("Variable 'x' unset successfully\n");
3} else {
4printf("Failed to unset variable 'x'\n");
5}
Tcl_UnsetVar2
功能: 删除变量
语法: int Tcl_UnsetVar2(Tcl_Interp *interp, const char *part1, const char *part2, int flags)
返回值: TCL_OK 表示成功,TCL_ERROR 表示失败
说明:
- 删除一个变量,可以是标量或数组元素
- part1 是变量名,part2 用于数组元素(可以为 NULL)
- flags 控制变量的查找和删除方式
示例:
1int result = Tcl_UnsetVar2(interp, "myVar", NULL, TCL_LEAVE_ERR_MSG);
2if (result != TCL_OK) {
3 // 处理错误
4}
Tcl_LinkVar
功能: 将C变量链接到Tcl变量
语法: int Tcl_LinkVar(Tcl_Interp *interp, const char *varName, char *addr, int type)
参数:
interp: 解释器varName: Tcl变量名addr: C变量的地址type: 变量类型（如TCL_LINK_INT, TCL_LINK_DOUBLE等）
返回值: 成功返回TCL_OK，失败返回TCL_ERROR
说明:
- 建立Tcl变量和C变量之间的双向链接
- 当一方变化时，另一方会自动更新
示例:
1int cVar = 42;
2if (Tcl_LinkVar(interp, "tclVar", (char *)&cVar, TCL_LINK_INT) == TCL_OK) {
3printf("Variable linked successfully\n");
4} else {
5printf("Failed to link variable\n");
6}
Tcl_UnlinkVar
功能: 解除C变量与Tcl变量的链接
语法: void Tcl_UnlinkVar(Tcl_Interp *interp, const char *varName)
参数:
interp: 解释器varName: 要解除链接的Tcl变量名
说明:
- 解除之前通过Tcl_LinkVar建立的变量链接
- 解除链接后，Tcl变量和C变量将不再同步
示例:
1Tcl_UnlinkVar(interp, "tclVar");
2printf("Variable 'tclVar' unlinked\n");
Tcl_UpdateLinkedVar
功能: 更新链接变量的值
语法: void Tcl_UpdateLinkedVar(Tcl_Interp *interp, const char *varName)
参数:
interp: 解释器varName: 要更新的Tcl变量名
说明:
- 强制更新链接变量的值，将C变量的值同步到Tcl变量
- 通常在C代码中修改链接变量后调用
示例:
1cVar = 100; // 修改C变量
2Tcl_UpdateLinkedVar(interp, "tclVar");
3printf("Linked variable updated\n");
Tcl_TraceVar
功能: 为变量添加跟踪
语法: int Tcl_TraceVar(Tcl_Interp *interp, const char *varName, int flags, Tcl_VarTraceProc *proc, ClientData clientData)
返回值: TCL_OK 表示成功,TCL_ERROR 表示失败
说明:
- 为指定的变量添加跟踪回调
- flags 指定何时调用跟踪过程(TCL_TRACE_READS, TCL_TRACE_WRITES 等)
示例:
1char *VarTraceProc(ClientData clientData, Tcl_Interp *interp, const char *name1, const char *name2, int flags) {
2 printf("Variable %s traced\n", name1);
3 return NULL;
4}
5Tcl_TraceVar(interp, "myVar", TCL_TRACE_READS | TCL_TRACE_WRITES, VarTraceProc, NULL);
Tcl_UntraceVar
功能: 移除变量的跟踪
语法: void Tcl_UntraceVar(Tcl_Interp *interp, const char *varName, int flags, Tcl_VarTraceProc *proc, ClientData clientData)
返回值: 无
说明:
- 移除之前通过 Tcl_TraceVar 添加的跟踪
- 参数必须与添加跟踪时使用的参数完全匹配
示例:
1Tcl_UntraceVar(interp, "myVar", TCL_TRACE_READS | TCL_TRACE_WRITES, VarTraceProc, NULL);
Tcl_VarTraceInfo
功能: 获取变量的跟踪信息
语法: ClientData Tcl_VarTraceInfo(Tcl_Interp *interp, const char *varName, int flags, Tcl_VarTraceProc *procPtr, ClientData prevClientData)
返回值: 下一个跟踪的 ClientData,如果没有更多跟踪则返回 NULL
说明:
- 获取变量上的跟踪信息
- 可以用来遍历所有与变量相关的跟踪
示例:
1ClientData clientData = NULL;
2while ((clientData = Tcl_VarTraceInfo(interp, "myVar", TCL_TRACE_READS, VarTraceProc, clientData)) != NULL) {
3 printf("Found trace for myVar\n");
4}
结果处理
这部分API用于设置、获取和操作Tcl命令的结果。在Tcl中，每个命令执行后都会产生一个结果，这些API允许C代码设置和检索这些结果。
Tcl_SetResult
功能: 设置解释器的结果
语法: void Tcl_SetResult(Tcl_Interp *interp, char *result, Tcl_FreeProc *freeProc)
参数:
interp: 解释器result: 要设置的结果字符串freeProc: 用于释放结果内存的函数（可以是TCL_STATIC, TCL_VOLATILE, TCL_DYNAMIC, 或自定义函数）
说明:
- 设置命令执行的结果
freeProc参数决定了结果字符串的内存管理方式
示例:
1Tcl_SetResult(interp, "Command executed successfully", TCL_STATIC);
Tcl_SetObjResult
功能: 设置解释器的结果为Tcl对象
语法: void Tcl_SetObjResult(Tcl_Interp *interp, Tcl_Obj *objPtr)
参数:
interp: 解释器objPtr: 要设置为结果的Tcl对象
说明:
- 设置命令执行的结果为Tcl对象
- 比Tcl_SetResult更高效，特别是对于非字符串类型的结果
示例:
1Tcl_Obj *resultObj = Tcl_NewIntObj(42);
2Tcl_SetObjResult(interp, resultObj);
Tcl_AppendResult
功能: 向解释器的结果追加一个或多个字符串
语法: void Tcl_AppendResult(Tcl_Interp *interp, ...)
参数:
interp: 解释器...: 要追加的字符串，以NULL结束
说明:
- 向现有结果追加一个或多个字符串
- 最后一个参数必须是NULL
示例:
1Tcl_AppendResult(interp, "First part", ", ", "Second part", NULL);
Tcl_AppendElement
功能: 向解释器的结果追加一个列表元素
语法: void Tcl_AppendElement(Tcl_Interp *interp, const char *element)
参数:
interp: 解释器element: 要追加的列表元素
说明:
- 将给定的字符串作为一个列表元素追加到结果中
- 自动处理引号和空格等特殊字符
示例:
1Tcl_AppendElement(interp, "element with spaces");
Tcl_GetObjResult
功能: 获取解释器的结果对象
语法: Tcl_Obj *Tcl_GetObjResult(Tcl_Interp *interp)
参数:
interp: 解释器
返回值: 当前的结果对象
说明:
- 获取当前命令执行的结果对象
- 返回的对象是共享的，不应该直接修改
示例:
1Tcl_Obj *resultObj = Tcl_GetObjResult(interp);
2int intResult;
3if (Tcl_GetIntFromObj(interp, resultObj, &intResult) == TCL_OK) {
4printf("Result as integer: %d\n", intResult);
5}
Tcl_GetStringResult
功能: 获取解释器结果的字符串表示
语法: const char *Tcl_GetStringResult(Tcl_Interp *interp)
参数:
interp: 解释器
返回值: 结果的字符串表示
说明:
- 获取当前命令执行结果的字符串形式
- 返回的字符串不应被修改或释放
示例:
1const char *result = Tcl_GetStringResult(interp);
2printf("Command result: %s\n", result);
Tcl_ResetResult
功能: 重置解释器的结果
语法: void Tcl_ResetResult(Tcl_Interp *interp)
参数:
interp: 解释器
说明:
- 清除当前的结果，将其重置为空字符串
- 同时清除任何错误信息
示例:
1Tcl_ResetResult(interp);
2printf("Result has been reset\n");
Tcl_SetReturnOptions
功能: 设置命令返回的选项
语法: int Tcl_SetReturnOptions(Tcl_Interp *interp, Tcl_Obj *options)
参数:
interp: 解释器options: 包含返回选项的字典对象
返回值: 成功返回TCL_OK，失败返回TCL_ERROR
说明:
- 设置命令返回的附加信息，如错误代码、错误信息等
- 通常用于高级错误处理和异常管理
示例:
1Tcl_Obj *options = Tcl_NewDictObj();
2Tcl_DictObjPut(interp, options, Tcl_NewStringObj("-code", -1), Tcl_NewIntObj(1));
3Tcl_DictObjPut(interp, options, Tcl_NewStringObj("-errorinfo", -1), Tcl_NewStringObj("Error occurred", -1));
4if (Tcl_SetReturnOptions(interp, options) == TCL_OK) {
5printf("Return options set successfully\n");
6}
Tcl_GetReturnOptions
功能: 获取命令返回的选项
语法: Tcl_Obj *Tcl_GetReturnOptions(Tcl_Interp *interp, int result)
参数:
interp: 解释器result: 命令的返回代码
返回值: 包含返回选项的字典对象
说明:
- 获取命令执行后的返回选项
- 通常用于错误处理和获取额外的返回信息
示例:
1int result = /* 某个Tcl命令的执行结果 */;
2Tcl_Obj *options = Tcl_GetReturnOptions(interp, result);
3Tcl_Obj *errorInfo;
4if (Tcl_DictObjGet(interp, options, Tcl_NewStringObj("-errorinfo", -1), &errorInfo) == TCL_OK) {
5printf("Error info: %s\n", Tcl_GetString(errorInfo));
6}