Files
marqdo/doc/design/markdown-mapping.md
T
cflmyandCursor 1f23e2ed93 Add module namespaces and harden L1/agent after the import redesign.
Bind imports to library names with bare path calls (and use), forward optional host args through mq wrappers, stabilize writeback replacement newlines, and document the M1/M2 decisions.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 13:28:32 +08:00

8.1 KiB
Raw Blame History

Marqdo 语法映射 v0.2(Markup-as-Syntax)

状态 已定论(修订:形参 +、分支 1.、标识符反引号、- 专用于循环)
日期 2026-08-07
取代 v0.1 中「函数头 - 形参 / 裸名形参与遍历变量 / + 分支」
相关 objects.md · code-vs-comment.md · return-hr-and-code-surface.md · module-namespace.md

Markdown 标记即语法。输出不是语言架构原语,而是内置函数 print(英文;见 keywords.md)。


1. 哲学

  1. .mq.md:打开即文档,运行即程序。
  2. 叙述注释以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
  3. 可执行靠标记:结构标记(# > + - 1. 表…)与 斜体语句 / 粗体返回。
  4. # = 对象/类型,##+ = 函数/方法(嵌套按标题深度);入口优先 # main(见 objects.md)。函数体可用 --- / *** 或空返回收束(见 §11)。
  5. 标识符一律反引号:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `名`,与 Markdown 无序列表/链接脱钩。

2. 行首判别与成段注释

跳过前导空白后,对段首行(空行之后的第一行,或文件起始):

首字符 分类
普通文字 / 空 注释
标记字符 代码

标记含:# * > + - ` |、有序数字 1.、围栏 `、以及函数体内的结束分割线 --- / ***(见 §11)。

成段注释(空行分段):段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 ` / - / * 等开头也不升级为代码。叙述与可执行代码之间必须空一行。例外:单独一行的 --- / *** / ****(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。


3. 映射总表(v0.2)

标记 语义
# … ###### # = 对象/类型;##+ = 函数/方法(层差=嵌套)。见 objects.md
函数头下 + `` 名`` 形参 / 构造参数(可选 `名`=默认值)
体内 1. 2. … 分支(有序列表臂;条件行或 else)
体内 - 循环(while 条件,或 [`项`](`集合`) 遍历)
分支臂头整行恰为 *(在 N. 后) else,如 2. *
> 函数 形参=实参 或 > 函数 实参 调用(具名 / 位置,见 call-arguments.md)
> `对象`.方法 … 方法调用(实例 map 须含 _type)
frontmatter > path.mq.md [as / 作为 name] 导入(绑定库名;默认 = 文件名茎)
frontmatter > use lib.member [as name] / 使用 将库路径成员绑为本地短名
> lib.member … / > lib.Type.member … 点号路径调用(路径段裸名、无反引号)
*…* 程序语句(绑定、表达式句、可写的调用句等)
**…** 返回值(架构级;函数结果)
**** / ** + 空白 + ** 空返回(None),并结束本函数体
无标记行 / 成段续行 注释(空行分段,见 §2)
GFM 表格 集合
空 RHS 赋值 + 后随 $$…$$(或同行 $$…$$) 公式赋值 → 运行时 formula(见 stdlib-math.md);叙述面无名 $$ 仅展示
```lang 外联异种代码
函数体内 --- / *** 结束本函数体(无返回值函数的收束;见 §11)

+ / - / 1. 消歧

位置 + 1. … -
函数标题后、首条体语句前 形参:+ `名` / + `名`=默认 (非法) (非法作形参)
函数体内 (非法作分支) 分支臂:1. 条件`` / 2. * 循环

分支从未使用 +。 自 v0 起即采用 GFM 有序列表;+ 在 v0.2 专用于形参,与 - 循环彻底分离。

输出不是架构

错误(旧) 正确(v0.2)
**Hello** 表示打印 > print text=Hello
+ x > 0 作分支 1. x > 0
- 谁 作形参 + `谁`
[果](篮子) 裸名遍历 [`果`](`篮子`)

print / input 为内置函数,完整表见 keywords.md。


4. 语句、返回、调用

程序语句(斜体)

*`x` = 1*

*`y` = `x` + 2*

行首已是结构标记的构造(# > + - |、1.)不必再包一层斜体;斜体用于「一般语句」槽位。

返回值(粗体)

## 加一
    + `n`

**`n` + 1**

输出(内置函数 print)

# main

> print text=Hello World!

else 与斜体消歧

  • 分支臂有序行 N. *(或 N. 后仅 *)→ else。
  • *中间有内容* → 程序语句。
  • **…** → 返回(与 else 无关)。

5. Frontmatter 与跨文件

文件头 --- 对为元信息。其中 > file.mq.md 为导入(绑定库名,成员不倒进全局);> use lib.member / > 使用 库.成员 引入本地短名。调用经裸点号路径(time.parse、agent.agent);实例方法须 > `var`.method。详见 module-namespace.md。

函数体内的 --- / *** 不解释为 frontmatter(见 §11)。


6. 对象、函数、形参

  • # Name:对象(构造体);# main 为入口对象。
  • ## / ### …:函数或方法;挂在对象下则为方法。
  • 标准库顶层 API 使用自由函数 ## name(见 objects.md)。
# main

> print text=Hello World!

## 加问候
    + `谁`

**你好,`谁`**

可选形参:

## 问候
    + `谁`
    + `礼貌`=False

方法体内自动绑定 `自` / `self`。


7. 绑定、比较与字符串

写法 含义
*x = 1* 或行首 `x` = 1 绑定
`x` == 1 相等比较
"text" 双引号字符串(复杂文本;见下)
hello / 路径 裸 token(无转义,按字面量)

双引号字符串(复杂文本)

需要转义或嵌入变量时用 "...";裸 token 不转义,保持文档简洁:

> input prompt="你叫什么名字\n"
*`msg` = "Hello, `name`!\n"*
转义 含义
\n 换行
\t 制表
\r 回车
\\ \
\" "

引号内仍可用 `变量` 插值。字面反斜杠+n 写 \\n(裸 token \\n 则就是两个字符)。


8. 分支与循环

分支(有序列表 1. 2. …),循环(-):

*`x` = 0*

1. `x` > 0
  > print text=正数
2. `x` < 0
  > print text=负数
3. *
  > print text=零
*`bool_value` = True*

1. `bool_value` == True
  > print text=True
2. *
  > print text=False
- [`果`](`篮子`)
  > print text=今天吃`果`

while:

- `n` > 0
  > print text=`n`
  *`n` = `n` - 1*

9. 集合(表格)

同 v0。`篮子` = 后接 GFM 表。


10. 求值入口

  1. 加载 index.mq.md + 导入。
  2. Pass1 收集定义。
  3. Pass2 执行 # main。
  4. * 语句、** 返回、> 调用、1. 分支、- 循环、表绑定按语义执行;> print 写 stdout。

11. 函数体结束(--- / *** / 空返回)

# main

> 问候 谁=World

## 问候
    + `谁`

> print text=Hello `谁`!

---
约定 说明
--- 或 *** 函数体顶层单独一行 → 结束本函数
**** / 空粗体 空返回(None),并结束本函数体
Frontmatter 仅文件开头成对 --- = 元信息

12. v0.2 非目标

  • break/continue、完整错误模型、静态类型、完整 FFI
  • + 作分支、+/- 作形参(不保留)

13. 示例索引

见 tests/。