📦 deps(tsl): sync tsl-playbook from a71480a4

Source-Commit: a71480a4ae
2026-08-12 08:38:08 +08:00
parent 683f83d17c
commit 670ba950a6
1496 changed files with 292667 additions and 220122 deletions
@@ -0,0 +1,168 @@
+# Builtin - 对象
+
+## `createObject(class_name, ...)`
+
+声明：function
+
+创建一个已在 TSL 语言中注册的对象，类名或类类型无效时调用出错
+
+<!-- tags: 对象 创建 实例 类 生成 object -->
+
+| 参数         | 类型              | 说明                                                           |
+| ------------ | ----------------- | -------------------------------------------------------------- |
+| `class_name` | string\|classtype | 已注册的对象类名，或通过 `class()`、`findClass()` 获得的类类型 |
+| `...`        | any               | 可选。按顺序传给类构造函数的参数                               |
+
+返回：tslobject
+
+### 示例
+
+范例01：向构造函数传递参数
+
+```tsl
+obj := createObject('CreationExample', 42);
+echo obj.value, "\n";
+
+type CreationExample = class
+public
+    value;
+    function create(initial_value);
+    begin
+        value := initial_value;
+    end;
+end;
+// 输出：42
+```
+
+## `findClass(class_name)`
+
+声明：function
+
+按名称查找类，找不到时返回 `0`
+
+<!-- tags: 对象 查找 搜索 lookup 获取 查询 实例 object -->
+
+| 参数         | 类型   | 说明   |
+| ------------ | ------ | ------ |
+| `class_name` | string | 类名称 |
+
+返回：tclass\|integer
+
+### 示例
+
+范例01：查找脚本中声明的类
+
+```tsl
+class_value := findClass("DemoClass");
+echo class_value <> 0;
+// 输出：1
+
+type DemoClass = class
+end;
+```
+
+## `findClass(class_name, obj)`
+
+声明：function
+
+将对象转换为指定类，类不匹配时返回 `0`
+
+<!-- tags: 对象 查找 搜索 lookup 转换 编码 实例 object -->
+
+| 参数         | 类型   | 说明         |
+| ------------ | ------ | ------------ |
+| `class_name` | string | 类名称       |
+| `obj`        | object | 要转换的对象 |
+
+返回：object\|integer
+
+### 示例
+
+范例01：转换为指定类
+
+```tsl
+obj := new DemoClass();
+typed_obj := findClass("DemoClass", obj);
+echo typed_obj <> 0;
+// 输出：1
+
+type DemoClass = class
+end;
+```
+
+## `objectstate(obj_name)`
+
+声明：function
+
+返回对象当前所处的生命周期状态
+
+<!-- tags: 对象 状态 生命周期 构造 析构 运行时 introspection object -->
+
+| 参数       | 类型   | 说明             |
+| ---------- | ------ | ---------------- |
+| `obj_name` | object | 要检查状态的对象 |
+
+返回：integer
+
+状态编码：`1` 表示构造中，`2` 表示构造完成，`3` 表示析构中，`4` 表示析构完成，`0` 表示未知状态，`-1` 表示参数不是对象
+
+### 示例
+
+```tsl
+obj := new StateProbe("ready");
+echo objectstate(obj), "\n";
+
+type StateProbe = class
+public
+    function create(value);
+    begin
+        echo objectstate(self), "\n";
+    end;
+end;
+// 输出：1
+// 输出：2
+```
+
+## `tslObjects(type)`
+
+声明：function
+
+获取当前运行环境中 TSL 对象的引用信息，可选取回对象本身
+
+<!-- tags: 对象 枚举 引用计数 生命周期 运行时 introspection object -->
+
+| 参数   | 类型    | 说明                                     |
+| ------ | ------- | ---------------------------------------- |
+| `type` | boolean | `0` 只返回引用计数，`1` 同时返回对象本身 |
+
+返回：array\|tablearray
+
+返回结果按类名分组，每个对象包含 `refs`、`orefs` 字段；`type` 为 `1` 时还包含 `obj` 字段
+
+### 示例
+
+```tsl
+first := new ObjectProbe(100);
+second := new ObjectProbe(101);
+objects := tslObjects(1);
+echo length(objects["ObjectProbe"]), "\n";
+restored := objects["ObjectProbe"][0, "obj"];
+echo restored is class(ObjectProbe), "\n";
+echo restored.add(1, 2), "\n";
+
+type ObjectProbe = class
+public
+    value;
+    function create(initial_value);
+    begin
+        value := initial_value;
+    end;
+    class function add(a, b);
+    begin
+        return a + b;
+    end;
+end;
+// 输出：2
+// 输出：1
+// 输出：3
+```