✨ feat(tsl-syntax-reference): harden retrieval contracts
Add stable section IDs, structural and routing regressions, quickstart consistency checks, and CI enforcement. BREAKING CHANGE: replace heading-derived Section IDs with explicit syntax-NN-NNN identifiers.
This commit is contained in:
@@ -4,17 +4,24 @@
|
||||
|
||||
## 本篇职责
|
||||
|
||||
<!-- section-id: syntax-02-001 -->
|
||||
|
||||
回答“目标文件到底是 `.tsl` 脚本还是 `.tsf` 可复用声明文件,以及 `.tsl` 里的哪些内容会顺序执行、哪些内容只是后置声明”。
|
||||
|
||||
本页是文件模型的唯一事实源:后缀判断、语句区 / 声明区顺序、`.tsf` 顶层声明形态和文件名约束都在这里收口。函数体、类体、`unit` 内部的语法外形由各自专题页拥有。
|
||||
|
||||
## 文件模型核心规则
|
||||
|
||||
<!-- section-id: syntax-02-002 -->
|
||||
|
||||
<!-- tags: 该用哪种文件, tsl 还是 tsf, 后缀怎么选, 文件形态判断 -->
|
||||
|
||||
- 用户已给出 `.tsl` / `.tsf` 后缀时,后缀就是判断依据;未给后缀时,再按交付目标判断。
|
||||
<!-- quickstart-rule: file-choice -->
|
||||
- 未给后缀时,入口流程、脚本任务或一次性执行逻辑对应 `.tsl`;可复用交付物(函数、过程、类、模块或扩展文件)对应 `.tsf`;只是脚本内部封装函数或类时,仍按 `.tsl` 处理;仍不明确时向用户确认,不要把脚本入口和可复用模块合并成一个猜测文件。
|
||||
<!-- quickstart-rule: tsl-layout -->
|
||||
- `.tsl` 脚本按两段理解:语句区在前并按顺序执行;声明区在后,可放 `function / procedure` 或 `type Name = class`。写 `.tsl` 时先写语句区,需要函数、过程或类时把声明区放在语句区之后。
|
||||
<!-- quickstart-rule: tsf-layout -->
|
||||
- 写 `.tsf` 时只写顶层函数 / 过程 / 类声明,或 `unit`;不要写成会直接顺序执行的脚本入口。
|
||||
- `.tsf` 里的非 `unit` 顶层函数 / 过程可按函数扩展理解:部署到解释器 `funcext` 后,`.tsl` 可以直接调用;顶层类声明只按可复用声明理解;`unit` 按模块组织理解。
|
||||
- `uses` 可以出现在顶层,但这里只把它当成辅助语句,不把它当成主体声明;函数体和类定义体里的位置限制见 [09_units_and_scope.md](09_units_and_scope.md)。
|
||||
@@ -23,12 +30,14 @@
|
||||
- `unit` 默认先按完整形态理解;它也可以省略 `interface` / `implementation` 写成简写形态,见 [09_units_and_scope.md](09_units_and_scope.md)。
|
||||
- 不要把 `.tsl` 写成只有顶层函数的模块;如果用户要通用可复用函数,优先写 `.tsf`。
|
||||
- 不要把 `.tsf` 写成会直接执行脚本语句的入口;如果用户要顺序执行入口,优先写 `.tsl`。
|
||||
- `.tsf` 文件名(不含扩展名)必须与第一个顶层声明同名:
|
||||
- `UserAccount.tsf` 中的顶层声明必须是 `function UserAccount` 或 `type UserAccount = class` 或 `unit UserAccount`。
|
||||
- TSL 语言大小写无关,因此 `userAccount.tsf` 和 `UserAccount.tsf` 在语法层面都合法。
|
||||
<!-- quickstart-rule: tsf-filename -->
|
||||
- `.tsf` 文件名(不含扩展名)必须与第一个顶层声明同名;第一个声明可以是同名 `function`、`type Name = class` 或 `unit`。
|
||||
- TSL 语言大小写无关,因此 `userAccount.tsf` 和 `UserAccount.tsf` 在语法层面都合法。
|
||||
|
||||
## 文件模型示例
|
||||
|
||||
<!-- section-id: syntax-02-003 -->
|
||||
|
||||
使用这些示例时遵守:
|
||||
|
||||
- 可以模仿已经出现的文件模型、语句顺序和块级结构。
|
||||
@@ -38,6 +47,8 @@
|
||||
|
||||
### `.tsl` 文件模型
|
||||
|
||||
<!-- section-id: syntax-02-004 -->
|
||||
|
||||
<!-- tags: 可执行脚本, 顺序执行, 入口脚本, 语句区, 声明区, 脚本从哪开始跑 -->
|
||||
|
||||
`.tsl` 脚本语句区的最小形态:
|
||||
@@ -96,6 +107,8 @@ end;
|
||||
|
||||
### `.tsf` 文件模型
|
||||
|
||||
<!-- section-id: syntax-02-005 -->
|
||||
|
||||
<!-- tags: 可复用文件, 模块文件, 函数扩展, 别的脚本能调, funcext -->
|
||||
|
||||
`.tsf` 顶层函数的最小形态:
|
||||
@@ -165,6 +178,8 @@ end.
|
||||
|
||||
### 文件模型反例
|
||||
|
||||
<!-- section-id: syntax-02-006 -->
|
||||
|
||||
<!-- tags: 为什么编译失败, 顶层裸类, 文件写错了, invalid statement -->
|
||||
|
||||
顶层裸 `class` 声明:
|
||||
@@ -211,6 +226,8 @@ function:__main__:line 9: invalid statement
|
||||
|
||||
## 任务到文件模型的选择规则
|
||||
|
||||
<!-- section-id: syntax-02-007 -->
|
||||
|
||||
<!-- tags: 任务对应哪种文件, 起手形态怎么选, 该建什么文件 -->
|
||||
|
||||
已经确定任务目标时,按下表选择起手形态:
|
||||
@@ -231,6 +248,8 @@ function:__main__:line 9: invalid statement
|
||||
|
||||
## 文件模型禁止项
|
||||
|
||||
<!-- section-id: syntax-02-008 -->
|
||||
|
||||
<!-- tags: 不要这样写, 文件模型误用, 两种文件混着写 -->
|
||||
|
||||
- 把 `.tsl` 当成 `.tsf` 来写,只给一个顶层函数,不写任何会执行的脚本语句。
|
||||
|
||||
Reference in New Issue
Block a user