Files
marqdo/doc/tutorial/README.md
T
cflmy aeb5a2a43d docs(tutorial): 新增《常见陷阱手册》,并补 D8–D10、按实测收敛 D3
把 qdagent 重构期间踩到的坑整理成**使用向**手册 doc/tutorial/15-常见陷阱.md
(417 行,全部条目在 1.5.2 逐条实测,含现象/原因/改法三段式与提交前自查清单)。

手册要点:
- §1 写文档:行首数字必报错(2026 年 / 42 条 / 3 个要点 都中招);
  行首 + 报错;未闭合引号静默吞行(最危险)
- §2 变量作用域:模块级变量在 # main 与各 ## 之间不可见;
  顶层不许裸语句;table.put 不原地修改
- §3 函数:函数名含空格时定义成功但调用必崩
- §4 字符串:引号内 ** / | / # 实为安全,只有引号不配对才出事
- §5 导入:相对路径以当前文件为基准;标准库必须带库名前缀
- §6 易记错的函数签名(txt.contains 的 sub、table.put 的 in/at/value …)
- §7 结构:# main 体不被 ## 截断;1./2./3. 是 if/elif/else 链
- §8 自查清单(marqdo check + run 双跑)

同步修正缺陷实录 research/qdagent-refactor-defects-2026-10.md:
- D3 收敛:实测证明 - / > / | / [ 在叙述区**安全**,只有行首数字与 +
  会被当语句;判据是「该行能否被解析成完整语句」
- 新增 D8 函数名含空格:定义成功、调用必崩,check 却通过(不对称)
- 新增 D9 未闭合引号静默吞行,退出码 0(静默类最危险)
- 新增 D10 table.put 非原地,累积计数静默失效
- 同步复现清单与变更记录

索引:tutorial/README 增第 15 章;doc/README 增手册与缺陷实录两行。
手册内所有代码示例均实测跑通(含参数传递修法、if 链、标准库前缀)。
2026-10-22 09:46:17 +08:00

3.8 KiB
Raw Blame History

Marqdo 语法教程

代码即文档,文档即代码。 Marqdo 把 Markdown 的标记当作编程语法:同一个 .mq.md 文件既是给人读的文稿,也是给机器跑的程序。

本教程面向所有读者——从没写过代码的文档作者,到熟悉 Python 的工程师。每章都配有可直接运行的完整示例。

现行映射是 markup v0.3:**…** = 代码(赋值 / 调用),*…* = 返回;集合取元优先 [键](集合)。

目录

第一部分 · 入门

章节 内容 你能学会什么
第 1 章:Marqdo 是什么 理念、安装、第一个程序、运行 写出并运行你的第一个 .mq.md 程序
第 2 章:基本语法 文件结构、注释、标识符、字面量 看懂 .mq.md 里哪些是代码、哪些是注释

第二部分 · 变量与数据

章节 内容 你能学会什么
第 3 章:变量与赋值 绑定、变量引用、字符串 存取值,拼接文本
第 4 章:输出与输入 print / 打印、input / 输入 与用户交互
第 5 章:运算符与比较 算术、比较、逻辑 计算与判断

第三部分 · 流程控制

章节 内容 你能学会什么
第 6 章:函数 定义、参数、返回值、括号调用 封装可复用逻辑
第 7 章:条件分支 1. 2. 分支、else 让程序根据条件走不同路线
第 8 章:循环 - 遍历、- while 重复执行

第四部分 · 数据集合

章节 内容 你能学会什么
第 9 章:集合(表格) 列表、字典、记录、链接取元 用 Markdown 表格组织数据

第五部分 · 面向对象与模块

章节 内容 你能学会什么
第 10 章:对象与方法 # 类型、构造、方法、继承 面向对象编程
第 11 章:模块与导入 frontmatter、import、库路径、短名 组织大型项目

第六部分 · 进阶

章节 内容 你能学会什么
第 12 章:标准库 内置函数、lib/ 模块 直接使用官方能力
第 13 章:命令行工具 run / view / debug / catalog 运行、浏览、调试、发布
第 14 章:网络与 Web 扩展 lib/net、ext/web、鉴权、WebSocket 构建 HTTP 客户端与网页应用
第 15 章:常见陷阱 行首数字、作用域、空格函数名、导入路径等实测坑 避开高频错误,提交前自查

快速示例

一个完整的 Marqdo 程序长这样:

# main

礼貌 [问候] World

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

1. `礼貌`
  > print text=您好,`谁`!
2. *
  > print text=Hello, `谁`!

*None*

## 加一
    + `n`

*n + 1*
  • # main —— 入口
  • 礼貌 [问候] World —— 方括号标记调用(前导词 → 礼貌=True)
  • ## 问候 + + 谁`` —— 定义函数及其参数
  • > print text=… —— 输出(副作用,是普通函数)
  • *n + 1* —— 返回值(斜体)
  • *None* —— 无值收束并结束函数体

运行方式

marqdo run 文件.mq.md

更多运行、浏览、调试、发布方式见 第 13 章。

提示:语法宪法见 doc/design/markdown-mapping-v0.3.md;本教程是它的通俗讲解版。