📦 deps(playbook): sync playbook snapshot

2026-02-02 10:51:41 +08:00
parent 50ef706bbb b52102b7bd
commit 42fd6168e9
192 changed files with 109197 additions and 135276 deletions
@@ -0,0 +1,368 @@
+# TSL 基础语法完整版
+
+> 本文档是 `$tsl-guide` 的子文档，聚焦基础语法。代码风格与命名规范请见 `docs/tsl/code_style.md` 与 `docs/tsl/naming.md`。
+
+## 目录
+
+- [语言元素与注释](#语言元素与注释)
+- [变量与常量](#变量与常量)
+- [数据类型与字面量](#数据类型与字面量)
+- [数组与表数组](#数组与表数组)
+- [运算符与表达式](#运算符与表达式)
+- [函数](#函数)
+- [控制流](#控制流)
+- [异常处理](#异常处理)
+- [调试与性能相关语句](#调试与性能相关语句)
+
+---
+
+## 语言元素与注释
+
+### 标识符与关键字
+
+- 关键字为保留字（完整列表见 `docs/tsl/syntax_book/01_language_basics.md`）
+- 标识符用于变量、函数、类、unit 等命名
+
+### 注释
+
+```tsl
+// 行注释
+{ 块注释 }
+/* 另一种块注释 */
+```
+
+### 编译选项（语法级）
+
+```tsl
+{$Explicit+}  // 要求变量先声明再使用
+{$Explicit-}  // 关闭显式声明
+{$VarByRef-}  // 默认参数按值传递（可用 in/var/out 覆盖）
+```
+
+---
+
+## 变量与常量
+
+### 赋值
+
+```tsl
+a := 1;
+b := 2.5;
+s := "hello";
+```
+
+### 常量
+
+```tsl
+const kPi = 3.14159;
+const kMaxRetry = 3;
+```
+
+### 显式变量声明（配合 `{$Explicit+}`）
+
+```tsl
+{$Explicit+}
+
+var a, b;          // 多变量声明
+var c := 10;       // 声明并初始化
+var d: integer;    // 类型可写可省（类型信息不做强校验）
+```
+
+---
+
+## 数据类型与字面量
+
+常见类型（参考 `01_language_basics.md`）：
+
+| 类型             | 说明                 |
+| ---------------- | -------------------- |
+| Integer / Int64  | 整数                 |
+| Real             | 浮点数               |
+| Boolean          | 布尔值（true/false） |
+| TDateTime        | 日期时间             |
+| String           | 字符串               |
+| Binary           | 二进制               |
+| Array            | 数组                 |
+| Matrix / TMatrix | 矩阵                 |
+| NIL              | 空值                 |
+
+示例：
+
+```tsl
+i := 42;
+r := 3.14;
+b := true;
+t := Date();
+s := 'hello';
+n := nil;
+```
+
+字符串支持单引号或双引号，索引访问从 0 开始：
+
+```tsl
+s := "ABC";
+ch := s[0];
+```
+
+---
+
+## 数组与表数组
+
+### 一维数组（0-based）
+
+```tsl
+arr := array(2, 3, 5, 7, 11);
+first := arr[0];
+```
+
+### 字符串下标（表数组）
+
+```tsl
+row := array("Code": "0001", "Price": 12.3);
+code := row["Code"];
+```
+
+### 多维数组
+
+```tsl
+matrix := array((1, 2, 3), (4, 5, 6));
+value := matrix[0][1];
+```
+
+---
+
+## 运算符与表达式
+
+### 常用运算符
+
+- 赋值：`:=`, `+=`, `-=`, `*=`, `/=`
+- 算术：`+ - * / div mod ^`
+- 关系：`= <> < > <= >= like in`
+- 逻辑：`and or not`
+- 三目：`cond ? a : b`
+
+示例：
+
+```tsl
+c := a + b;
+ok := (a = b) or (a > 0);
+x := (a > b) ? a : b;
+```
+
+矩阵/数组相关的 `.=`、`.<` 等算符在扩展语法中说明（见 `06_extended_syntax.md`）。
+完整运算符清单见 `01_language_basics.md`。
+
+---
+
+## 函数
+
+### 基本结构
+
+```tsl
+function HelloTsl();
+begin
+    d := Date();
+    return DateToStr(d);
+end;
+```
+
+### 参数分隔与类型注解
+
+类型注解仅用于说明与阅读，编译器不做类型检查。
+
+- 无类型注解时用逗号分隔参数
+- 带类型注解时用分号分隔参数
+- 返回值类型写在 `)` 之后
+
+```tsl
+function F1(a, b);
+function F2(a: string; b: array of real);
+function F3(): void;
+```
+
+### 形参与实参（in/const/var/out）
+
+```tsl
+function Calc(in a, var b, out c);
+begin
+    b := b + a;
+    c := b * 2;
+    return c;
+end;
+```
+
+### 缺省参数（新一代语法）
+
+```tsl
+function Foo(a, b = a + 1);
+begin
+    return b;
+end;
+```
+
+### 命名参数（新一代语法）
+
+```tsl
+function FuncA(a, b, c);
+begin
+    return array(a, b, c);
+end;
+
+result := FuncA(1, c: 3); // b 默认为 nil
+```
+
+### 变参（`...`）与 Params
+
+```tsl
+function SumAll(...);
+begin
+    total := 0;
+    for i, v in Params do
+        total := total + v;
+    return total;
+end;
+```
+
+相关内置：`Params`, `ParamCount`, `RealParamCount`。
+
+### 返回与退出
+
+```tsl
+return value; // 返回
+exit;         // 退出函数
+```
+
+### 外部函数声明（external）
+
+```tsl
+function GetTickCount(): integer; stdcall; external "kernel32.dll" name "GetTickCount" keepresident;
+```
+
+更多外部接口与调用方式见 `03_functions.md`。
+
+---
+
+## 控制流
+
+### if / else if
+
+```tsl
+if x > 0 then
+    y := 1;
+else if x = 0 then
+    y := 0;
+else
+    y := -1;
+```
+
+### if 表达式（新一代语法）
+
+```tsl
+ret := if x > 0 then x * x else 0;
+```
+
+### case
+
+```tsl
+case age of
+    0: WriteLn("Baby");
+    1: WriteLn("Toddler");
+else
+    WriteLn("Other");
+end;
+```
+
+### while / repeat
+
+```tsl
+while cond do
+    DoSomething();
+
+repeat
+    DoSomething();
+until cond;
+```
+
+### for（to / downto / step）
+
+```tsl
+for i := 1 to 10 do
+    sum := sum + i;
+
+for i := 10 downto 1 step 2 do
+    sum := sum + i;
+```
+
+### for ... in（数组遍历）
+
+```tsl
+data := array('a': 1, 'b': 5, 'c': 3);
+sum := 0;
+
+for k, v in data do
+    sum := sum + v;
+```
+
+### break / continue / goto
+
+```tsl
+while cond do
+begin
+    if stop then break;
+    if skip then continue;
+    // ...
+end;
+
+goto found;
+label found;
+    WriteLn("jumped");
+```
+
+---
+
+## 异常处理
+
+### Try / Except
+
+```tsl
+try
+    v := StrToInt(s);
+except
+    v := 0;
+    WriteLn(ExceptObject.ErrInfo);
+end;
+```
+
+### Try / Finally
+
+```tsl
+try
+    DoWork();
+finally
+    Cleanup();
+end;
+```
+
+### Raise
+
+```tsl
+if a < 0 then raise "A 不能小于 0";
+```
+
+异常信息可通过 `ExceptObject.ErrInfo/ErrLine/ErrNo` 获取。
+
+---
+
+## 调试与性能相关语句
+
+```tsl
+debugreturn 1;
+```
+
+```tsl
+t1 := mtic;
+// ...
+elapsed := mtoc(t1);
+```
+
+更多调试/性能语法见 `02_control_flow.md` 与 `07_debug_and_profiler.md`。