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-22-001 -->
回答“什么时候该用 `FMArray` 而不是普通 `array`,以及文档明确 `FMArray` 写法有哪些”。
## 核心规则
<!-- section-id: syntax-22-002 -->
- `fmarray[...]` 可以直接构造 `FMArray` 常量。
- `dataType(v)``FMArray` 返回 `27`
- `dataType(v, 1)` 可以读出 `FMArray` 单元格类型;本页文档类型包括 `0` 整型、`1` 浮点、`20` 64 位整型。
@@ -26,8 +30,12 @@
## 可直接照写示例
<!-- section-id: syntax-22-003 -->
### 常量构造与类型判断
<!-- section-id: syntax-22-004 -->
<!-- tags: 建 FMArray, 高性能数组, 字面量写法 -->
代码块身份:可直接照写示例
@@ -74,6 +82,8 @@ writeLn(f2[0,0], ',', f2[0,1], ',', f2[1,0], ',', f2[1,1]);
### `mInit`、`mInitDiag`、`mRand`
<!-- section-id: syntax-22-005 -->
<!-- tags: 初始化 FMArray, 对角阵, 随机矩阵 -->
代码块身份:可直接照写示例
@@ -105,6 +115,8 @@ writeLn(mcols(fr1));
### `arrayToFm`、`matrixToArray` 与单元格类型转换
<!-- section-id: syntax-22-006 -->
<!-- tags: 普通数组转 FMArray, 互转, 单元格类型 -->
代码块身份:可直接照写示例
@@ -135,6 +147,8 @@ writeLn(a2[0][0], ',', a2[0][1], ',', a2[1][0], ',', a2[1][1]);
### 尺寸与重构
<!-- section-id: syntax-22-007 -->
<!-- tags: FMArray 尺寸, 改形状, reshape, 三维 -->
二维和三维尺寸:
@@ -173,6 +187,8 @@ writeLn(r1[0], ',', r1[1], ',', r1[2], ',', r1[3], ',', r1[4], ',', r1[5]);
### 标量运算与基础算符
<!-- section-id: syntax-22-008 -->
<!-- tags: FMArray 加减乘除, 和数字运算 -->
代码块身份:可直接照写示例
@@ -200,6 +216,8 @@ writeLn(s2[0], ',', s2[1], ',', s2[2]);
### `union2` 与左值类型
<!-- section-id: syntax-22-009 -->
<!-- tags: FMArray 合并, 左值类型决定结果 -->
代码块身份:可直接照写示例
@@ -228,6 +246,8 @@ writeLn(u2[0], ',', u2[1], ',', u2[2], ',', u2[3], ',', u2[4], ',', u2[5]);
### 多维转置与维度交换
<!-- section-id: syntax-22-010 -->
<!-- tags: 三维转置, 换维度, 维度倒置 -->
三维 `FMArray` 上,反引号转置会把全部维度倒置:
@@ -272,6 +292,8 @@ writeLn(t[0,0,0], ',', t[0,1,0], ',', t[0,2,0], ';', t[1,0,0], ',', t[1,1,0], ',
### 矩阵连接 / 矩阵并右方:`union`、`|`、`:|`
<!-- section-id: syntax-22-011 -->
<!-- tags: FMArray 拼接, 按列连接, 补零对齐 -->
`union` 会按行拼接,不做去重:
@@ -366,6 +388,8 @@ writeLn(m2[2,0], ',', m2[2,1], ',', m2[2,2], ',', m2[2,3]);
### 排序
<!-- section-id: syntax-22-012 -->
<!-- tags: 排序, 从小到大, 按列排, sortArray -->
一维排序:
@@ -398,6 +422,8 @@ writeLn(f1[0,0], ',', f1[0,1], ';', f1[1,0], ',', f1[1,1], ';', f1[2,0], ',', f1
### TS-SQL 对 `FMArray` 的支持
<!-- section-id: syntax-22-013 -->
<!-- tags: 对 FMArray 做查询, mselect -->
代码块身份:可直接照写示例
@@ -422,6 +448,8 @@ writeLn(mcols(q2));
### `insert` / `delete` / `update`
<!-- section-id: syntax-22-014 -->
<!-- tags: FMArray 增删改, 写回 -->
`insert`
@@ -482,6 +510,8 @@ writeLn(u[0,0], ',', u[0,1], ';', u[1,0], ',', u[1,1], ';', u[2,0], ',', u[2,1])
## 本页不生成的范围
<!-- section-id: syntax-22-015 -->
- `mInitDiag` 更高维行为
- `mRand` 的随机分布参数变体
- `union` / `|` / `:|` 与普通 `array` 的更多混合边界
@@ -492,6 +522,8 @@ writeLn(u[0,0], ',', u[0,1], ';', u[1,0], ',', u[1,1], ';', u[2,0], ',', u[2,1])
## 默认生成模板
<!-- section-id: syntax-22-016 -->
需要 `FMArray` 常量时,优先从这个最短模板开始:
代码块身份:可直接照写示例
@@ -502,6 +534,8 @@ f := fmarray[1, 2, 3];
## 禁止项
<!-- section-id: syntax-22-017 -->
- 在一个 `FMArray` 常量里混用不同单元格类型。
-`FMArray` 当成支持字符串下标的 `array`
- 以为对 `FMArray` 做普通 `select` 后,结果还是 `dataType=27`