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:
csh
2026-07-31 10:05:15 +08:00
parent 21e688a436
commit 736d1a8ad7
30 changed files with 1635 additions and 137 deletions
@@ -4,10 +4,14 @@
## 本篇职责
<!-- section-id: syntax-07-001 -->
回答“`if``case``for``while``repeat``break``continue``try``raise` 这些流程结构在 TSL 里到底怎么写,哪些写法可以直接生成”。
## 核心规则
<!-- section-id: syntax-07-002 -->
- `if ... then ... else ...` 默认写成块式分支:`then begin ... end else begin ... end`
- 块式分支内部的普通语句必须用分号结尾。
- 控制流块的 `begin ... end` 后可以加分号也可以不加(语法都允许)。
@@ -26,6 +30,8 @@
## 可直接照写示例
<!-- section-id: syntax-07-003 -->
使用这些示例时遵守:
- 条件表达式、比较、布尔值和普通赋值的事实见 [06_expressions_and_operators.md](06_expressions_and_operators.md)。
@@ -34,6 +40,8 @@
### `if`、`while`、`repeat ... until`
<!-- section-id: syntax-07-004 -->
<!-- tags: 条件判断, 循环, 判断语句, 直到满足, 反复执行 -->
代码块身份:可直接照写示例
@@ -69,6 +77,8 @@ writeLn(counter);
### `for` 的几种主干写法
<!-- section-id: syntax-07-005 -->
<!-- tags: 循环写法, 遍历数组, 计数循环, 倒着循环, 遍历键值 -->
最基础的递增循环:
@@ -155,6 +165,8 @@ for i, value in numbers do
### `break` 与 `continue`
<!-- section-id: syntax-07-006 -->
<!-- tags: 跳出循环, 提前退出循环, 跳过本次, 结束循环 -->
`break`
@@ -216,6 +228,8 @@ writeLn(sum);
### `case` 语句形态
<!-- section-id: syntax-07-007 -->
<!-- tags: 多分支, 分支判断, switch 怎么写, 多条件选择 -->
普通分支:
@@ -305,6 +319,8 @@ mid
### `try ... except`
<!-- section-id: syntax-07-008 -->
<!-- tags: 捕获异常, 异常处理, 出错处理, 抓错误, 异常不中断 -->
代码块身份:可直接照写示例
@@ -364,6 +380,8 @@ end
### `try ... finally`
<!-- section-id: syntax-07-009 -->
<!-- tags: 收尾处理, 无论如何都执行, 释放资源, 清理动作 -->
正常路径:
@@ -425,6 +443,8 @@ finally
### `raise`
<!-- section-id: syntax-07-010 -->
<!-- tags: 抛异常, 主动报错, 中断执行, 扔错误 -->
代码块身份:可直接照写示例
@@ -448,6 +468,8 @@ before
## 默认生成模板
<!-- section-id: syntax-07-011 -->
最短条件分支的默认骨架如下:
代码块身份:可直接照写示例
@@ -466,6 +488,8 @@ end
## 禁止项
<!-- section-id: syntax-07-012 -->
-`else` 前面误加分号。
- 生成没有分号的裸分支赋值,例如 `then value := 1 else ...`;带 `else` 时用块式分支。
- 以为 `try ... finally` 会吞掉异常。