Files
marqdo/doc/tutorial/09-集合.md
cflmyandCursor c55aad775e docs: teach link-index and v0.3 markers in tutorial and Skill
Rewrite chapter 9 and Skill examples around [key](coll), bracket-marked
calls, and ** code / * return; keep footnote get as a transitional note.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 13:08:53 +08:00

4.3 KiB
Raw Permalink Blame History

第 9 章:集合(表格)

Marqdo 用 GFM 表格直接构造数据集合。表格的几何形状决定值的类型——这是 Marqdo 最有特色的部分:你看到的 Markdown 表格就是数据结构。

9.1 绑定一个集合

集合绑定用「空右侧赋值 + 表格」:

`名字` =

| 表头1 | 表头2 |
|-------|-------|
| 值    | 值    |

表格绑定变量名需要反引号(不在粗体代码 **…** 内时)。

9.2 单列竖表 → 列表(List)

恰好 1 列 → 列表:

`篮子` =

| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |

等价于 ["苹果", "梨", "桃"]。表头 果 是元素逻辑名(foreach 绑定名),不进入列表元素。

- [果](篮子)
  > print text=`果`

9.3 多列 + 一行 → 字典(Map)

≥2 列 + 恰好 1 行数据 → 字典,键 = 表头:

`分类` =

| 苹果 | 黄瓜 |
|------|------|
| 水果 | 蔬菜 |

等价于 {"苹果": "水果", "黄瓜": "蔬菜"}。

9.4 多列 + 多行 → 字典套列表

≥2 列 + ≥2 行数据 → 字典,值为该列的列表(列向聚合):

`货架` =

| 苹果 | 黄瓜 |
|------|------|
| 红富士 | 青瓜 |
| 嘎啦 | 黄瓜条 |

等价于:

{"苹果": ["红富士", "嘎啦"], "黄瓜": ["青瓜", "黄瓜条"]}

9.5 行向记录表 → 记录列表

首列表头为 @ / 行 / row 时,整表改为行向(SQL/CSV 风格):

`订单` =

| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |

等价于:

[{"品名": "苹果", "数量": 2}, {"品名": "梨", "数量": 3}]

标记列(行)不进入记录字段。

9.6 表格形状速查

形状 值类型
1 列 List
≥2 列 + 1 行 Map(标量值)
≥2 列 + ≥2 行 Map(值均为 List)
≥2 列 + 0 行 Map(键存在,值空列表)
首列 @/行/row List of Map(行向记录)

9.7 链接取元:[键](集合)

主语法与 foreach 同形:方括号 = 取出的名字,圆括号 = 从哪取(见 collection-access-link.md)。

从列表按下标取

下标是 1-based(与人类读表一致):

**第一 = [1](篮子)**
**打印 内容=`第一`**

从字典按键取

**种 = [苹果](分类)**
**打印 内容=`种`**

动态键

**名 = "拿铁"**
**价 = [`名`](菜单)**

嵌套取元

**第一种苹果 = [1]([苹果](货架))**

插值中的取元

在调用实参值 / 引号字符串里也可以写链接取元(或过渡期的脚注形):

> print text=苹果单价:[苹果](`水果价格`)
> print text=第一种:[1]([苹果](`货架`))

过渡:脚注取元 集合[^键]

旧写法 分类[^苹果] / `分类`[^苹果] 仍可解析;新代码与教程示例请用链接形。脚注兼容金样见 tests/structure/footnote*。

规则:

  • List:键须为纯数字(1-based);[0](…) 或越界 → 报错。
  • Map:键为键文本;缺键 → 报错。
  • 文末的 [^1]: … 定义块仍是注释,与取元无关。
  • ] 后紧邻 ( 才是取元;否则 [名字] 可能是方括号标记调用。

9.8 表格单元格是表达式

数据单元格支持表达式(与调用实参值语法相同):裸词、数字、`var`、算术、引号串。URL / gpt-4o-mini 等按路径/连字符折叠为文本。

**k = "secret"**

`cfg` =

| api_key | model |
|---------|-------|
| `k` | gpt-4o-mini |

9.9 完整示例

# main

`水果价格` =

| 苹果 | 香蕉 |
|------|------|
| 5 | 3 |

**打印 内容="苹果单价:" + [苹果](水果价格)**

`购物单` =

| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 香蕉 | 3 |

- [行](购物单)
  **打印 内容=[品名](行) + " × " + [数量](行)**

输出:

苹果单价:5
苹果 × 2
香蕉 × 3

9.10 下一步

你已经掌握 Marqdo 的数据组织了。接下来学习第 10 章:对象与方法。