Add GFM link-shaped index as the primary get surface, keep footnote index as transitional compatibility, and align the coffee example. Co-authored-by: Cursor <cursoragent@cursor.com>
307 lines
9.3 KiB
Markdown
307 lines
9.3 KiB
Markdown
# 表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **T0–T5 已落地**(单元格表达式见 [table-cell-expressions.md](../design/table-cell-expressions.md)) |
|
||
| 日期 | 2026-08-12 |
|
||
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) §9 · [table-cell-expressions.md](../design/table-cell-expressions.md) · [objects.md](../design/objects.md) · [stdlib.md](../design/stdlib.md)(`lib/table`) · [keywords.md](../design/keywords.md) |
|
||
| 现状金样 | [tests/structure/collection.mq.md](../../tests/structure/collection.mq.md) |
|
||
|
||
---
|
||
|
||
## 1. 问题
|
||
|
||
### 1.1 今日表格 =「竖表 → 列表」
|
||
|
||
```markdown
|
||
`篮子` =
|
||
|
||
| 果 |
|
||
|----|
|
||
| 苹果 |
|
||
| 梨 |
|
||
| 桃 |
|
||
```
|
||
|
||
语义(已落地):绑定为**列表**(列值);表头名供 `` [`果`](`篮子`) `` 遍历。
|
||
单列表头是当前唯一一等集合外形;**没有**一等「横表 = 字典」。
|
||
|
||
### 1.2 缺字典外形与嵌套
|
||
|
||
用户期望:GFM 表的两种几何对应两种结构,并允许嵌套——这样「多行表格」才有稳定、可教的含义。
|
||
|
||
### 1.3 不能按下标 / 键直接取元
|
||
|
||
今日要从列表取第 *n* 项,往往只能遍历或走 `lib/table`(`row_at` 等),**语言级**缺少与 Markdown 同构的取元语法。字典亦然。
|
||
|
||
---
|
||
|
||
## 2. 目标
|
||
|
||
1. **竖表**继续表示列表(兼容现有金样)。
|
||
2. **横表**(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。
|
||
3. 用 **Markdown 脚注外形** 做列表下标 / 字典键的取元(表达式级)。
|
||
4. 不引入 `[]` 下标关键字风暴;少而精,与「标记即语法」一致。
|
||
|
||
非目标:
|
||
|
||
- 完整电子表格公式引擎
|
||
- 用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开)
|
||
- 破坏现有单列竖表金样
|
||
|
||
---
|
||
|
||
## 3. 表格几何 → 值(锁定提案)
|
||
|
||
判定在 **绑定右侧的 GFM 表** 上做(`` `名` = `` 后接表)。
|
||
|
||
### 3.1 竖表 → 列表(现状,保留)
|
||
|
||
**形状:** 恰好 **1** 列。
|
||
|
||
```markdown
|
||
`篮子` =
|
||
|
||
| 果 |
|
||
|----|
|
||
| 苹果 |
|
||
| 梨 |
|
||
| 桃 |
|
||
```
|
||
|
||
| 结果 | 说明 |
|
||
|------|------|
|
||
| 值 | `List`:`["苹果","梨","桃"]` |
|
||
| 表头 | 元素逻辑名(foreach 绑定名);不进入列表元素 |
|
||
|
||
### 3.2 横表单数据行 → 字典
|
||
|
||
**形状:** ≥2 列,且 **恰好 1 行数据**(表头 + 分隔 + 一行)。
|
||
|
||
```markdown
|
||
`分类` =
|
||
|
||
| 苹果 | 黄瓜 | 鼠标 |
|
||
|------|------|------|
|
||
| 水果 | 蔬菜 | 数码用品 |
|
||
```
|
||
|
||
| 结果 | 说明 |
|
||
|------|------|
|
||
| 值 | `Map`:`苹果→水果`, `黄瓜→蔬菜`, `鼠标→数码用品` |
|
||
| 键 | 表头单元格文本(规范化空白后) |
|
||
| 值 | 唯一数据行对应列 |
|
||
|
||
### 3.3 横表多数据行 → 字典套列表(默认)
|
||
|
||
**形状:** ≥2 列,且 **≥2 行数据**。
|
||
|
||
```markdown
|
||
`货架` =
|
||
|
||
| 苹果 | 黄瓜 |
|
||
|------|------|
|
||
| 红富士 | 青瓜 |
|
||
| 嘎啦 | 黄瓜条 |
|
||
```
|
||
|
||
**默认语义(锁定):列向聚合**
|
||
|
||
```text
|
||
{
|
||
"苹果": ["红富士", "嘎啦"],
|
||
"黄瓜": ["青瓜", "黄瓜条"]
|
||
}
|
||
```
|
||
|
||
即:**键 = 表头,值 = 该列数据行组成的列表**。
|
||
这与竖表「一列 = 一列表」在多列时自然推广,嵌套外形稳定。
|
||
|
||
**备选语义(不默认):行向记录列表**
|
||
|
||
```text
|
||
[
|
||
{"苹果":"红富士","黄瓜":"青瓜"},
|
||
{"苹果":"嘎啦","黄瓜":"黄瓜条"}
|
||
]
|
||
```
|
||
|
||
更像 SQL / CSV。若未来需要,用显式标记区分(见 §3.5),**不得**与默认列向字典静默混用。
|
||
|
||
### 3.4 单列多行 vs 多列
|
||
|
||
| 列数 | 数据行 | 值类型 |
|
||
|------|--------|--------|
|
||
| 1 | ≥0 | `List` |
|
||
| ≥2 | 1 | `Map`(标量值) |
|
||
| ≥2 | ≥2 | `Map`(值均为 `List`) |
|
||
| ≥2 | 0 | `Map`(键存在,值空列表或错误——开工时锁定为「空列表」) |
|
||
|
||
### 3.5 显式形态标记(行向记录)— **已落地**
|
||
|
||
首列表头为下列之一时,整表改为**行向**(不静默混用列向默认):
|
||
|
||
| 标记 | 说明 |
|
||
|------|------|
|
||
| `@` | ASCII 短标记 |
|
||
| `行` | 中文 |
|
||
| `row` | 英文 |
|
||
|
||
规则:
|
||
|
||
1. 标记列**不进入**记录字段(数据格可写行号给人看)。
|
||
2. 其余列 → 每行一个 `Map`;整体为 `List`。
|
||
3. 须至少有一列字段(仅 `| 行 |` → 诊断)。
|
||
4. 数据行数任意(含 0 → 空列表;1 行仍是 `List` of one `Map`,不是列向 `Map`)。
|
||
|
||
```markdown
|
||
`订单` =
|
||
|
||
| 行 | 品名 | 数量 |
|
||
|----|------|------|
|
||
| 1 | 苹果 | 2 |
|
||
| 2 | 梨 | 3 |
|
||
```
|
||
|
||
→ `[{品名: 苹果, 数量: 2}, {品名: 梨, 数量: 3}]`。取元:`` `订单`[^1][^品名] ``。
|
||
|
||
---
|
||
|
||
## 4. 脚注取元(历史 · 过渡保留)
|
||
|
||
> **主语法已切换为链接形** `[键](集合)`,见 [collection-access-link.md](../design/collection-access-link.md)。
|
||
> 本节 `` 集合[^键] `` 仍由运行时接受;**新代码请写链接形**。
|
||
|
||
### 4.1 为何曾用脚注外形
|
||
|
||
- Markdown 已有 `[^…]` 引用形态,读者不陌生。
|
||
- 避免 `篮子[0]` 与链接 / 图片语法纠缠。
|
||
- 与「标识符反引号」组合清晰:`` `篮子`[^1] ``。
|
||
|
||
### 4.2 列表:按下标
|
||
|
||
```markdown
|
||
*`第一` = `篮子`[^1] *
|
||
> print text=`第一`
|
||
```
|
||
|
||
| 约定 | 选择(提案) |
|
||
|------|----------------|
|
||
| 下标基准 | **1-based**(与 Markdown / 人类表格行语感一致;脚注 `[^1]` 即第一项) |
|
||
| `[^0]` | 报错(保留 0 不用)或日后表示「最后一项」—— v1 **报错** |
|
||
| 越界 | 清晰诊断 `path:line:col` |
|
||
|
||
### 4.3 字典:按键
|
||
|
||
键为脚注标签文本(推荐与表头一致;**允许纯数字键**,如基矢标签 `00`)。基名可写 `` `概率`[^00] `` 或 `` 概率[^00] ``(紧跟 `[^` 时可省略反引号):
|
||
|
||
```markdown
|
||
*`种` = `分类`[^苹果] *
|
||
*`p00` = `概率`[^00] *
|
||
> print text=`种`
|
||
```
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| `[^苹果]` | 键文本 `苹果` |
|
||
| `[^00]` / `[^1]` | 键文本 `00` / `1`(**不是**「第 n 个 map 条目」) |
|
||
| 含空格的键 | 允许 `[^数码用品]`;极端键用引号策略开工前定 |
|
||
| 缺失键 | 报错或 `None`——建议 v1 **报错**(少静默) |
|
||
|
||
### 4.4 嵌套取元
|
||
|
||
列向字典套列表:
|
||
|
||
```markdown
|
||
*`货架` = …多行横表… *
|
||
*`第一种苹果` = `货架`[^苹果][^1] *
|
||
```
|
||
|
||
从左到右:先键、再下标。
|
||
类型不对(对 List 用非数字键名脚注)→ 诊断。Map 上的纯数字标签按**键名**解析。
|
||
|
||
### 4.5 与 GFM「定义脚注」正文
|
||
|
||
标准 Markdown 文末 `[^1]: 说明` 是**注释/文献**,不是取元。
|
||
|
||
规则:
|
||
|
||
- **表达式位置**的 `` `名`[^…] `` → 取元。
|
||
- **文末脚注定义块** → 仍作注释(或不支持,避免混用)。
|
||
- 不要求为每个 `[^1]` 写定义;Marqdo 取元**不依赖**定义块。
|
||
|
||
### 4.6 与 `lib/table` 关系
|
||
|
||
| 层 | 职责 |
|
||
|----|------|
|
||
| 语言脚注取元 | 一等、短、金样覆盖 |
|
||
| `lib/table` | 行列切片、整表变换;可逐步把 `row_at` 文档改为「等价于脚注」 |
|
||
|
||
---
|
||
|
||
## 5. foreach 与字典
|
||
|
||
今日:`` [果](篮子) `` / `` [`果`](`篮子`) `` 遍历列表(裸名与反引号均可)。
|
||
|
||
扩展草案:
|
||
|
||
| 集合 | 遍历 |
|
||
|------|------|
|
||
| List | 不变,项为元素 |
|
||
| Map | `` [`键`](`映射`) `` 遍历键;或 `` [`对`](`映射`) `` 若引入对类型—— v1 建议 **遍历键**,值用 `` `映射`[^…] `` / 辅助 |
|
||
|
||
具体键值对遍历语法开工前写一小段进 mapping;避免与链接外形 `` [`x`](`y`) `` 冲突(今日已是 foreach)。
|
||
|
||
---
|
||
|
||
## 6. 推荐落地顺序
|
||
|
||
```text
|
||
T0 横表单行 → Map;金样;竖表回归 ✅
|
||
T1 横表多行 → Map of List(列向);嵌套金样 ✅
|
||
T2 脚注取元:List [^n]、Map [^键]、链式 ✅
|
||
T3 文档:markdown-mapping §9;Skill / examples;table 库 ✅
|
||
T4 行向记录表:首列 `@` / `行` / `row` ✅
|
||
T5 数据单元格 = 表达式(同调用实参值语法) ✅
|
||
```
|
||
|
||
验收:
|
||
|
||
1. `tests/structure/collection.mq.md` 行为不变。
|
||
2. 新金样:`collection-map.mq.md`、`collection-map-list.mq.md`、`footnote-index.mq.md`。
|
||
3. 错误下标 / 缺键带 `line:col`。
|
||
4. 双后端(tree / bytecode)一致。
|
||
5. **T5:** 单元格 `` `var` `` / 算术;URL 与 `gpt-4o-mini` 仍为文本;设计见 [table-cell-expressions.md](../design/table-cell-expressions.md)。
|
||
|
||
---
|
||
|
||
## 7. 教学对照(写入 Skill 的素材)
|
||
|
||
| 几何 | 含义 | 取元 |
|
||
|------|------|------|
|
||
| 单列竖表 | 列表 | `` `a`[^1] `` |
|
||
| 多列 + 一行 | 字典 | `` `m`[^键] `` |
|
||
| 多列 + 多行 | 字典 → 列表 | `` `m`[^键][^1] `` |
|
||
| 首列 `@`/`行`/`row` | 记录列表 | `` `r`[^1][^字段] `` |
|
||
|
||
竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。
|
||
|
||
---
|
||
|
||
## 8. 开放点
|
||
|
||
1. 表头重复列名:报错还是后缀 `_2`?建议 **报错**。
|
||
2. 数字表头:字典键为文本 `"1"` 还是整数?建议 **文本**(与单元格一致)。
|
||
3. 脚注 1-based 与宿主语言习惯(0-based)的文档警示。
|
||
4. 字节码:`Index` / `KeyGet` 操作码是否与 T2 同批。
|
||
|
||
---
|
||
|
||
## 9. 与其它规划的关系
|
||
|
||
| 文档 | 关系 |
|
||
|------|------|
|
||
| [object-inheritance.md](object-inheritance.md) | 正交;表不表示类字段 schema |
|
||
| [agent-streaming.md](agent-streaming.md) | 正交;事件列表可用竖表金样演示 foreach |
|
||
| [okf-near-match.md](okf-near-match.md) | 正交 |
|