📝 docs(tsl): restructure agent-facing reference

Rework TSL syntax, catalog, modules, and routing docs around deterministic agent lookup and generation. Split large catalog pages into focused function fact pages, remove obsolete pending/verified/unavailable paths, and update consistency tests for the new structure.
2026-06-09 17:24:30 +08:00
parent 9c194170a1
commit 540b3c0a1b
192 changed files with 32929 additions and 13533 deletions
@@ -0,0 +1,219 @@
+# TSL 词法结构与编译选项
+
+文档类型：语法深水专题
+是否可直接用于生成代码：是
+是否含可直接照写示例：是
+是否含不可照写反例：是
+遇到不确定时：先按本页候选页继续判断；[17_types_and_conversions.md](17_types_and_conversions.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
+
+这一篇吸收语法手册里“词法层”和“编译期开关”相关内容：标识符、注释、条件编译和依赖编译选项。
+
+## 本篇职责
+
+回答“TSL 的词法层规则和编译期开关应该去哪里查，而不是把这些边界混进值、函数、类的正文里”。
+
+## 智能体词法/编译选项判断流程
+
+1. 先判断要写注释、标识符、条件编译，还是编译选项。
+2. 注释、大小写、条件编译指令只照本页文档明确形态写。
+3. `{$explicit+}` 会改变变量声明要求，生成代码前先判断是否需要 `var`。
+4. `{$varByRef+}` / `{$varByRef-}` 会影响未修饰形参传递语义，细节回看函数页。
+5. 没有对应代码块时不要发明词法/编译选项写法。
+
+## 核心规则
+
+- 标识符大小写无关；下划线可出现在标识符中。
+- `//` 是行注释；首行 `#!` 可作为 CGI 风格注释；`{ ... }` 与 `(* ... *)` 是块注释。
+- 条件编译指令使用 `{$define}`、`{$undef}`、`{$ifdef}`、`{$ifndef}`、`{$else}`、`{$endif}`。
+- 条件编译只编译命中的分支；未命中的分支不参与脚本编译。
+- `{$explicit+}` 开启后，后续变量必须先用 `var` 声明；`{$explicit-}` 可以在同一源文件里重新关闭这个要求。
+- `{$varByRef-}` 与 `{$varByRef+}` 会切换“未修饰形参”的默认传递方式，细节见 [05_functions_and_calls.md](05_functions_and_calls.md)。
+- `{$i}` / `{$include}` 不作为本页可生成的默认能力。
+- `{$dependency ...}` 这类编辑器辅助编译选项不作为本页正文事实。
+
+## 可直接照写示例
+
+### 标识符、注释与条件编译
+
+大小写无关与下划线标识符：
+
+代码块身份：可直接照写示例
+
+```tsl
+my_var := 7;
+writeLn(my_var);
+writeLn(MY_VAR);
+```
+
+结果说明：
+
+- 依次输出 `7`、`7`
+- 说明标识符大小写无关，下划线可以出现在标识符中
+
+代码块身份：输出片段
+
+```text
+7
+7
+```
+
+注释与条件编译：
+
+代码块身份：可直接照写示例
+
+```tsl
+#! shebang style comment
+
+a := 1; // line comment
+{
+    (* nested comment marker *)
+}
+writeLn(a);
+{$define FLAG}
+{$ifdef FLAG}
+writeLn(10);
+{$else}
+writeLn(20);
+{$endif}
+{$undef FLAG}
+{$ifndef FLAG}
+writeLn(30);
+{$else}
+writeLn(40);
+{$endif}
+```
+
+结果说明：
+
+- 依次输出 `1`、`10`、`30`
+- 说明首行 `#!`、`//`、`{ ... }`、`(* ... *)` 都属于文档明确注释形态
+- 说明 `define` / `undef` / `ifdef` / `ifndef` / `else` / `endif` 这一组条件编译指令可以正常生效
+
+### 显式变量声明开关
+
+`{$explicit+}` 的文档明确形态：
+
+代码块身份：可直接照写示例
+
+```tsl
+{$explicit+}
+var a;
+a := 1;
+writeLn(a);
+```
+
+结果说明：
+
+- 输出 `1`
+- 说明 `{$explicit+}` 开启后，配合 `var` 声明可以正常通过
+
+`{$explicit-}` 可以在同一源文件里关掉显式声明要求：
+
+代码块身份：可直接照写示例
+
+```tsl
+{$explicit+}
+var a;
+a := 1;
+{$explicit-}
+b := 2;
+writeLn(a + b);
+```
+
+结果说明：
+
+- 输出 `3`
+- 说明 `{$explicit-}` 会从出现位置开始取消“变量必须先声明”的限制
+
+### 条件编译分支边界
+
+条件编译不会去编译未命中的坏代码分支：
+
+代码块身份：可直接照写示例
+
+```tsl
+{$undef NEVER}
+{$ifdef NEVER}
+MissingFunction(
+{$else}
+writeLn(1);
+{$endif}
+```
+
+结果说明：
+
+- 输出 `1`
+- 说明未命中的条件编译分支不会参与脚本编译
+
+### 参数默认传递开关
+
+`{$varByRef-}` 与 `{$varByRef+}`：
+
+代码块身份：可直接照写示例
+
+```tsl
+x := 1;
+TouchDefault(x);
+writeLn(x);
+y := 1;
+TouchValue(y);
+writeLn(y);
+z := 1;
+TouchForcedVar(z);
+writeLn(z);
+r := 1;
+TouchRestored(r);
+writeLn(r);
+
+function TouchDefault(a);
+begin
+    a := 9;
+end;
+{$varByRef-}
+function TouchValue(a);
+begin
+    a := 8;
+end;
+function TouchForcedVar(var a);
+begin
+    a := 7;
+end;
+{$varByRef+}
+function TouchRestored(a);
+begin
+    a := 6;
+end;
+```
+
+结果说明：
+
+- 依次输出 `9`、`1`、`7`、`6`
+- 说明默认模式下，未修饰参数仍会写回调用方
+- 说明 `{$varByRef-}` 下，未修饰参数会改成按值传递
+- 说明 `var` 形参在 `{$varByRef-}` 下仍保持引用语义
+- 也说明 `{$varByRef+}` 可以把默认语义重新切回可写回模式
+
+## 禁止项
+
+- 不要在 `{$explicit+}` 后继续直接使用未声明变量。
+- 不要把 `{$i ...}` / `{$include ...}` 包含文件写法当成可用能力。
+- 不要把 `反例 / 不可照写` 代码块复制进正向示例。
+
+代码块身份：反例 / 不可照写
+
+```text
+{$explicit+}
+a := 1;
+```
+
+上面这种写法不作为可写事实；`{$explicit+}` 后必须先声明再使用变量。
+
+代码块身份：反例 / 不可照写
+
+```text
+writeLn(1);
+
+{$i "common.inc"}
+```
+
+上面这种包含文件写法不作为本页可生成的默认能力。