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-15-001 -->
回答“TSL 的词法层规则和编译期开关有哪些”:标识符与大小写、注释形态、保留字清单,以及 `{$...}` 编译开关的书写位置和作用范围。
## 核心规则
<!-- section-id: syntax-15-002 -->
- 标识符大小写无关;下划线可出现在标识符中。
- `//` 是行注释;首行 `#!` 可作为 CGI 风格注释;`{ ... }``(* ... *)` 是块注释。
- 条件编译指令使用 `{$define}``{$undef}``{$ifdef}``{$ifndef}``{$else}``{$endif}`
@@ -20,6 +24,8 @@
## 保留字/关键字速查
<!-- section-id: syntax-15-003 -->
<!-- tags: 关键字列表, 保留字, 哪些名字不能用 -->
TSL 关键字大小写无关;本表统一按文档推荐写法展示。生成代码时不要把这些名称用作普通标识符。
@@ -46,8 +52,12 @@ TSL 关键字大小写无关;本表统一按文档推荐写法展示。生成
## 可直接照写示例
<!-- section-id: syntax-15-004 -->
### 标识符、注释与条件编译
<!-- section-id: syntax-15-005 -->
<!-- tags: 注释怎么写, 大小写敏感吗, 变量命名, 下划线 -->
大小写无关与下划线标识符:
@@ -106,6 +116,8 @@ writeLn(40);
### 显式变量声明开关
<!-- section-id: syntax-15-006 -->
<!-- tags: 强制声明变量, explicit, 必须先 var -->
`{$explicit+}` 的文档明确形态:
@@ -144,6 +156,8 @@ writeLn(a + b);
### 条件编译分支边界
<!-- section-id: syntax-15-007 -->
<!-- tags: 条件编译, 未命中分支, ifdef 不编译 -->
条件编译不会去编译未命中的坏代码分支:
@@ -166,6 +180,8 @@ writeLn(1);
### `{$CompileOption}` 编译选项
<!-- section-id: syntax-15-008 -->
<!-- tags: 编译开关, 编译器选项, 改默认行为 -->
`{$CompileOption}` 用于设置编译期开关,改变编译器的默认行为:
@@ -192,6 +208,8 @@ echo 1 + 1;
### 参数默认传递开关
<!-- section-id: syntax-15-009 -->
<!-- tags: 全局改传参方式, varByRef 开关, 默认按值还是按引用 -->
`{$varByRef-}``{$varByRef+}`
@@ -242,6 +260,8 @@ end;
## 禁止项
<!-- section-id: syntax-15-010 -->
- 不要在 `{$explicit+}` 后继续直接使用未声明变量。
- 不要把 `{$i ...}` / `{$include ...}` 包含文件写法当成可用能力。
- 不要把 `反例 / 不可照写` 代码块复制进正向示例。