# 表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划) | | | |---|---| | 状态 | **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) | 正交 |