# Marqdo 语法映射 v0.2(Markup-as-Syntax) | | | |---|---| | 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) | | 日期 | 2026-08-07 | | 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 | | 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) | Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。 --- ## 1. 哲学 1. `.mq.md`:打开即文档,运行即程序。 2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。 3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。 4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。 5. **标识符默认反引号**:形参、绑定、引用写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。 **豁免:** - foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。 - 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。 - **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**(含调用实参与方法接收者);文本字面量须 `"…"` 或 `'…'` 或引号实参(`key="文本"`);`` `名` `` 仍合法。这是 **Python 统一命名空间**:裸点号 `a.b` 在 `a` 为局部变量时为方法调用,否则为库路径。 --- ## 2. 行首判别与成段注释 跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始): | 首字符 | 分类 | |--------|------| | 普通文字 / 空 | **注释** | | 标记字符 | **代码** | 标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。 **成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。 --- ## 3. 映射总表(v0.2) | 标记 | 语义 | |------|------| | `#` … `######` | **`#` = 对象/类型**(可 `# Child = > Parent`);**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) | | 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) | | 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) | | 体内 `-` | **循环**(`while` 条件,或 `[项](集合)` / `` [`项`](`集合`) `` 遍历) | | 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` | | `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) | | `` > `对象`.方法 … `` | 方法调用(独立 `>`;实例 map 须含 `_type`)。`*…*` 段内接收者裸名:`*x = > 对象.方法 …*` | | frontmatter `import bind:path.mq.md` / `导入` | 导入文件并绑定库名 | | frontmatter `import bind:lib.member` / `导入` | 将库路径成员绑为本地短名(与文件导入同形) | | `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) | | `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) | | `**…**` | **返回值**(架构级;函数结果) | | `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 | | 无标记行 / 成段续行 | 注释(空行分段,见 §2) | | GFM 表格 | 集合 | | 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 | | ` ```lang ` | 外联异种代码 | | 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) | ### `+` / `-` / `1.` 消歧 | 位置 | `+` | `1.` … | `-` | |------|-----|--------|-----| | 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) | | 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 | **分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。 ### 输出不是架构 | 错误(旧) | 正确(v0.2) | |------------|--------------| | `**Hello**` 表示打印 | `> print text=Hello` | | `+ `x` > 0` 作分支 | `1. `x` > 0` | | `- 谁` 作形参 | `` + `谁` `` | | `[果](篮子)` 裸名遍历 | **仍合法**(foreach 豁免);亦可用 `` [`果`](`篮子`) `` | `print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。 --- ## 4. 语句、返回、调用 ### 程序语句(斜体) ```markdown *x = 1* *y = x + 2* *answer = ev[^message]* *亦可用 = 1* ``` 斜体内部:裸标识符 = 变量;字符串写 `"…"` / `'…'`。行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。 ### 返回值(粗体) ```markdown ## 加一 + `n` **n + 1** **"ok"** **`n` + 1** ``` 粗体内部与斜体相同的值语法(裸词 = 变量;文本须引号)。 ### 输出(内置函数 `print`) ```markdown # main > print text=Hello World! ``` ### else 与斜体消歧 - 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。 - `*中间有内容*` → 程序语句。 - `**…**` → 返回(与 else 无关)。 --- ## 5. Frontmatter 与跨文件 文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。 **函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。 --- ## 6. 对象、函数、形参 - `# Name`:对象(构造体);`# main` 为入口对象。 - `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。 - `##` / `###` …:函数或方法;挂在对象下则为方法。 - 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。 ```markdown # main > print text=Hello World! ## 加问候 + `谁` **你好,`谁`** ``` 可选形参: ```markdown ## 问候 + `谁` + `礼貌`=False ``` 方法体内自动绑定 `` `自` `` / `` `self` ``。 --- ## 7. 绑定、比较与字符串 | 写法 | 含义 | |------|------| | `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 | | `` `x` == 1 `` | 相等比较 | | `"text"` | **双引号字符串**(复杂文本;见下) | | `hello` / `路径` | **裸 token**(无转义,按字面量) | ### 双引号字符串(复杂文本) 需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁: ```markdown > input prompt="你叫什么名字\n" *`msg` = "Hello, `name`!\n"* ``` | 转义 | 含义 | |------|------| | `\n` | 换行 | | `\t` | 制表 | | `\r` | 回车 | | `\\` | `\` | | `\"` | `"` | | `\'` | `'` | | `\xHH` | 十六进制字符(如 `\x22` → `"`) | | `\u{...}` | Unicode 码点(如 `\u{4e2d}` → `中`) | 引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。未知转义(如 `\q`)按字面保留,不报错。 --- ## 8. 分支与循环 分支(**有序列表** `1.` `2.` …),循环(`-`): ```markdown *`x` = 0* 1. `x` > 0 > print text=正数 2. `x` < 0 > print text=负数 3. * > print text=零 ``` ```markdown *`bool_value` = True* 1. `bool_value` == True > print text=True 2. * > print text=False ``` **一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`**(无论中间有无空行)开启**下一条**独立分支语句,不得并入上一段的臂列表: ```markdown 1. `a` > print text=A 2. * > print text=not-A 1. `b` > print text=B 2. * > print text=not-B ``` 上例为两次独立判断(先 `a` 再 `b`),不是「四个臂的一个分支」。臂序号在同一分支内递增(`1.` → `2.` → `3.` …);**不要**在同一分支中途把序号重置为 `1.`。 ```markdown - [果](篮子) > print text=今天吃`果` ``` 反引号形式等价:`` - [`果`](`篮子`) ``。两侧可混用。 `while`: ```markdown - `n` > 0 > print text=`n` *`n` = `n` - 1* ``` --- ## 9. 集合(表格) `` `名` = `` 后接 GFM 表;几何决定值类型(详见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md)): | 形状 | 值 | |------|-----| | **1 列**(竖表) | `List`(表头 = foreach 元素名,不进入元素) | | **≥2 列 + 1 行数据**(横表) | `Map`:键 = 表头,值 = 该列标量 | | **≥2 列 + ≥2 行数据** | `Map`:键 = 表头,值 = 该列 `List`(列向) | | **≥2 列 + 0 行数据** | `Map`:键存在,值为空列表 | | **首列表头 `@` / `行` / `row`** | **行向** `List` of `Map`(标记列不进入字段;任意数据行数) | | 重复表头 | 诊断错误 | **数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本;含 `/` 的 CSS 比率等请用引号 `"1/5"`,裸 `1/5` 为除法)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。 ```markdown *`k` = secret * `cfg` = | api_key | model | |---------|-------| | `k` | gpt-4o-mini | ``` 行向示例: ```markdown `订单` = | 行 | 品名 | 数量 | |----|------|------| | 1 | 苹果 | 2 | | 2 | 梨 | 3 | *`名` = `订单`[^1][^品名] * ``` **脚注取元**(表达式级;可链式): ```markdown *`第一` = 篮子[^1] * # 基名可省略反引号(`[^` 已标明取元) *`种` = 分类[^苹果] * *`第一种苹果` = 货架[^苹果][^1] * *`亦可用` = `分类`[^苹果] * # 反引号形式并存 ``` - **List**:标签须为纯数字(1-based);`[^0]` / 越界 → 报错。 - **Map**:标签为键文本(含 `"00"` 这类数字串键);缺键 → 报错。同一外形按接收值类型分派,不把 map 上的 `[^1]` 当成「第 1 个条目」。 - 基名:`` `名`[^键] `` 与 `` 名[^键] `` 等价;无 `` [^ `` 时裸词仍是**文本字面量**(不是变量)。 - **插值中的取元**:在调用实参值 / 引号字符串里,`` `变量` `` 后**紧跟**(无空白)`` [^…] `` 时按取元解析,而不是字面文本:`> print text=苹果单价:`水果价格`[^苹果]`;链式 `` `货架`[^苹果][^1] `` 同理。`` `变量` [^…] ``(有空白)则 `` [^…] `` 仍是文本。 - 文末 `[^1]: …` 定义块仍是注释,与取元无关。 - foreach:`List` 遍历元素;`Map` 遍历**键**(值用脚注取)。 --- ## 10. 求值入口 1. 加载 `index.mq.md` + 导入。 2. Pass1 收集定义。 3. Pass2 执行 `# main`。 4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。 --- ## 11. 函数体结束(`---` / `***` / 空返回) ```markdown # main > 问候 谁=World ## 问候 + `谁` > print text=Hello `谁`! --- ``` | 约定 | 说明 | |------|------| | `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** | | `****` / 空粗体 | 空返回(`None`),并结束本函数体 | | Frontmatter | 仅**文件开头**成对 `---` = 元信息 | --- ## 12. v0.2 非目标 - break/continue、完整错误模型、静态类型、完整 FFI - `+` 作分支、`+`/`-` 作形参(**不保留**) --- ## 13. 示例索引 见 [`tests/`](../../tests/)。