# Marqdo 语法映射 v0.1(Markup-as-Syntax) | | | |---|---| | 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) | | 日期 | 2026-08-04 | | 取代 | v0 中「`**`=输出、`*`=返回」 | | 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) | Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。 --- ## 1. 哲学 1. `.mq.md`:打开即文档,运行即程序。 2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。 3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。 4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。 --- ## 2. 行首判别与成段注释 跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始): | 首字符 | 分类 | |--------|------| | 普通文字 / 空 | **注释** | | 标记字符 | **代码** | 标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。 **成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。 --- ## 3. 映射总表(v0.1) | 标记 | 语义 | |------|------| | `#` … `######` | 函数;层数 = 作用域 | | 函数头下 `-` 纯名 | 形参 | | 体内 `-` | 循环 | | 体内 `+` 或 `1.` | 分支 | | 分支臂头整行恰为 `*` | else | | `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) | | frontmatter `> path.mq.md` | 跨文件导入 | | `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) | | `**…**` | **返回值**(架构级;函数结果) | | `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 | | 无标记行 / 成段续行 | 注释(空行分段,见 §2) | | GFM 表格 | 集合 | | 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 | | ` ```lang ` | 外联异种代码 | | 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) | ### 输出不是架构 | 错误(旧) | 正确(v0.1) | |------------|--------------| | `**Hello**` 表示打印 | `> print text=Hello` | | 中文名 `输出`(已废弃) | 统一英文内置 `print` | | 输出与返回抢粗体 | 粗体只表示 **返回** | `print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。 --- ## 4. 语句、返回、调用 ### 程序语句(斜体) ```markdown *`x` = 1* *`y` = `x` + 2* ``` 行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。 ### 返回值(粗体) ```markdown # 加一 - n **`n` + 1** ``` ### 输出(内置函数 `print`) ```markdown # main > print text=Hello World! ``` ### else 与斜体消歧 - 分支臂**第一行整行只有一个** `*` → else。 - `*中间有内容*` → 程序语句。 - `**…**` → 返回(与 else 无关)。 --- ## 5. Frontmatter 与跨文件 同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。 **函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。 --- ## 6. 函数、作用域、提升 规则同 v0。推荐: ```markdown # main > print text=Hello World! ## 加问候 - 谁 **你好,`谁`** ``` (需要打印时对返回值再 `> print`,或直接 `> print`。) 形参 `- 名` → 体内 `` `名` ``。 --- ## 7. 绑定与比较 | 写法 | 含义 | |------|------| | `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) | | `` `x` == 1 `` | 相等比较 | v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。 --- ## 8. 分支与循环 分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`: ```markdown *`x` = 0* + `x` > 0 > print text=正数 + `x` < 0 > print text=负数 + * > print text=零 ``` ```markdown - [果](篮子) > print text=今天吃`果` ``` --- ## 9. 集合(表格) 同 v0。`` `篮子` = `` 后接 GFM 表。 --- ## 10. 求值入口 1. 加载 `index.mq.md` + 导入。 2. Pass1 收集定义。 3. Pass2 执行 `# main`。 4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。 --- ## 11. 函数体结束(`---` / `***` / 空返回) 无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数: ```markdown # main > 问候 谁=World ## 问候 - 谁 > print text=Hello `谁`! --- ``` | 约定 | 说明 | |------|------| | `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 | | `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 | | 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) | | Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 | | 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 | 曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。 --- ## 12. v0.1 非目标 - break/continue、完整错误模型、静态类型、完整 FFI - 用 `*` 作无序列表符 --- ## 13. 示例索引 见 [`tests/`](../../tests/)。