From 2cb05fd838435103cf1d7c0217053e9d4b35f231 Mon Sep 17 00:00:00 2001 From: cflmy Date: Tue, 4 Aug 2026 10:42:36 +0800 Subject: [PATCH] Add v0 markup-as-syntax constitution, examples, and tech stack choice. Lock Markdown marker mappings, ship runnable-shaped examples, and select TypeScript + remark + Vitest for the reference implementation. Co-authored-by: Cursor --- README.md | 162 +++++----------- doc/README.md | 24 ++- doc/design/generated-yaml-manifest.md | 2 + doc/design/markdown-mapping.md | 266 ++++++++++++++++++++++++++ doc/design/tech-stack.md | 74 +++++++ examples/branch.mq.md | 16 ++ examples/collection.mq.md | 18 ++ examples/hello.mq.md | 5 + examples/index.mq.md | 15 ++ examples/loop.mq.md | 25 +++ examples/utils.mq.md | 14 ++ examples/with-import.mq.md | 14 ++ 12 files changed, 507 insertions(+), 128 deletions(-) create mode 100644 doc/design/markdown-mapping.md create mode 100644 doc/design/tech-stack.md create mode 100644 examples/branch.mq.md create mode 100644 examples/collection.mq.md create mode 100644 examples/hello.mq.md create mode 100644 examples/index.mq.md create mode 100644 examples/loop.mq.md create mode 100644 examples/utils.mq.md create mode 100644 examples/with-import.mq.md diff --git a/README.md b/README.md index ebb91fe..37ad3a1 100644 --- a/README.md +++ b/README.md @@ -2,149 +2,75 @@ **代码即文档。文档即代码。** -Marqdo 是一门正在设计中的编程语言:源文件既是可执行程序,也是可被 Markdown 渲染的文档。写法本身就是叙述;运行与阅读共用同一份文本,而不是两套彼此漂移的产物。 +Marqdo 是一门编程语言:源文件是可执行的程序,也是可被 Markdown 渲染的文档。语法由 Markdown **标记**本身承担(Markup-as-Syntax),而不是在文档里嵌入另一套关键字。 + +第一版语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 示例:[examples/](examples/) --- ## 为什么需要一门新语言 -传统工作流里,代码与文档是两套工件: +传统工作流里,代码与文档是两套工件,文档写完即开始过时。Literate Programming、注释生成文档、Markdown 围栏演示都无法做到「同一份文本既是程序又是说明」。 -| | 代码 | 文档 | -|---|---|---| -| 写给谁 | 机器 / 编译器 | 人 | -| 保真度 | 精确、可执行 | 易读、可解释 | -| 典型命运 | 持续演进 | 逐渐过时 | +Marqdo 的路径:**标记即语法**——标题是函数,粗体是输出,斜体是返回值,列表是控制流,表格是集合。 -我们用注释、README、Wiki、生成器去弥合裂缝,但裂缝从未真正消失——文档写完的那一刻,就开始落后于代码。 +--- -**Literate Programming** 把叙事与代码交织,仍是「文档里嵌代码」。 -**Markdown + 代码块** 适合演示,不适合构建真实系统。 -**注释生成文档** 能提取签名与说明,却无法保证叙事与实现同构。 +## 语法速览(v0) -Marqdo 想走第三条路:**语言的语法与语义从一开始就按「可渲染、可阅读、可执行」一起设计**,而不是事后把代码「翻译」成文档。 +| 标记 | 含义 | +|------|------| +| `#` / `##` | 函数与作用域 | +| `-` 纯名(函数头下) | 形参 | +| `-`(体内) | 循环 | +| `+` 或 `1.` | 分支(`*` 独行 = else) | +| `**…**` | 输出 | +| `*…*` | 返回值 | +| `` `name` `` | 变量;`=` 绑定,`==` 比较 | +| `>` | 调用;frontmatter 里 `> file.mq.md` 为跨文件导入 | +| 表格 | 集合 | + +```markdown +--- +title: Hello World +--- + +# main + +> 输出函数 输出内容=Hello World! + +## 输出函数 + - 输出内容 + +**`输出内容`** +``` + +更多:[examples/index.mq.md](examples/index.mq.md)、[examples/branch.mq.md](examples/branch.mq.md)、[examples/loop.mq.md](examples/loop.mq.md)。 --- ## 核心理念 -### 1. 同一份源,两种阅读 - -一份 `.mq.md` 源文件: - -- **对机器**:是完整的程序——可解析、可类型检查、可执行。 -- **对人 / 渲染器**:就是 Markdown——GitHub、编辑器预览、静态站点无需转换即可阅读。 - -后缀选用 `.mq.md`,刻意让「可被 Markdown 工具链直接渲染」成为默认能力,而不是可选插件。 - -**手写的只有源。** 依赖与模块元数据由工具链分析 `.mq.md` 后,生成 **OKF 风格的 YAML/Markdown 清单**(类比其它语言由工具维护的依赖描述),并可自动汇总成本项目的目录文档——不是给人填的配置文件。详见 [设计草案](doc/design/generated-yaml-manifest.md)。 - -不是「从代码生成文档」,也不是「从文档提取代码」。**源文本本身就是程序与说明**;生成清单只是全项目的结构化投影。 - -### 2. 语法即排版 - -若代码要自动成为好文档,语法就不能只对解析器友好。 - -Marqdo 的设计约束包括: - -- **结构即层级** — 模块、类型、函数的嵌套应对应文档的标题层级,而不是依赖额外的 `@section` 注解。 -- **命名即语义** — 标识符、契约、类型应能在渲染后直接读懂,少依赖旁白式注释。 -- **声明即说明** — 接口、不变量、副作用边界写在语言里,而不是散落在散文里。 -- **噪声极低** — 括号、分号、样板代码若无法帮助理解,就不应存在。 - -一门「看起来像 Markdown」却无法严肃编程的语言会沦为玩具;一门「能编程」却渲染成乱码的语言则失去初衷。Marqdo 必须同时成立。 - -### 3. 可读性是一等公民 - -多数语言把可读性交给风格指南与格式化工具。Marqdo 把可读性抬升为语言语义的一部分: - -- 良好的程序应当**读起来像一篇写清楚的说明**。 -- 糟糕的抽象、含糊的命名、隐式的副作用,不仅是工程问题,也是**文档失败**。 -- 工具链(格式化、诊断、预览)的目标是:打开源文件时,你已经在读文档;运行它时,你已经在跑程序。 - -### 4. 设计优先于实现 - -「代码即文档」听起来简单,落地极难。它要求我们在以下张力之间找到平衡: - -``` -表达力 ↔ 简洁性 -精确性 ↔ 可读性 -可组合性 ↔ 叙事流畅 -机器友好 ↔ 人类友好 -``` - -没有深思熟虑的语法、类型与模块设计,这门语言很容易退化成「带一点 Markdown 装饰的脚本」。因此 Marqdo 会**先把语言设计做对**,再推进解释器、编译器与生态——宁可慢,不可歪。 - ---- - -## 愿景一瞥 - -理想中的 Marqdo 程序,打开时像文档,运行时像程序: - -```markdown -# 购物车 - -维护一组商品行,并给出应付总额。 - -## 行项目 - -一行包含名称、单价与数量。 - -type Line = - name: Text - price: Number - qty: Number - -## 总额 - -总额是所有行的 `price × qty` 之和。 - -fn total(cart: [Line]) -> Number = - cart |> map(l => l.price * l.qty) |> sum -``` - -> 以上仅为思想示意,**不是**最终语法。真实语法将在设计文档中逐步敲定。 - -关键点不在于「看起来像 Markdown」,而在于: - -1. 叙事结构与程序结构同源; -2. 类型与函数是文档中的一等段落,而非被围栏隔离的异类; -3. 读者与执行者看到的是同一份真相。 - ---- - -## 我们关心的设计问题 - -后续设计将围绕这些问题展开(非完整列表): - -- **边界**:哪些 Markdown 结构是程序结构?哪些只是散文? -- **求值与排版**:同一文本如何无损地同时服务解析器与渲染器? -- **类型与证明**:类型信息如何既服务检查,又服务阅读? -- **模块与长文**:大型程序如何仍像一本可导航的书,而不是一堵墙? -- **交互文档**:渲染结果能否嵌入可运行示例、求值结果、实时预览? -- **互操作**:如何与现有语言、工具链、包生态共存? +1. **同一份源,两种阅读** — `.mq.md` 对人是 Markdown,对机器是程序。 +2. **手写源,生成清单** — 依赖/模块目录以 OKF 风格由工具生成,不是手填配置([说明](doc/design/generated-yaml-manifest.md))。 +3. **行首判别** — 有标记则执行,无标记则注释(注释内标记无语义)。 +4. **设计优先于实现** — 先定映射宪法,再选型实现。 --- ## 现状 -Marqdo 处于**思想与语言设计**阶段。各阶段开发文档集中在 [`doc/`](doc/): +- 语法映射 v0:**已定论** — [markdown-mapping.md](doc/design/markdown-mapping.md) +- 调研:[OKF](doc/research/okf-and-marqdo.md) +- 下一步:实现技术选型、解析器与测试 -- 设计原则与决策记录(ADR) -- 调研笔记(含对 [OKF](doc/research/okf-and-marqdo.md) 等相邻标准的借鉴) -- 语法草案与示例 -- 参考实现(解析 · 渲染 · 求值) -- 工具与编辑器支持 - -欢迎讨论理念与设计;实现会随后跟上。 +文档目录:[doc/](doc/) --- ## 命名 -**Marqdo** = **Marq**(mark / Markdown)+ **do**(行动、执行)。 - -标记是为了被人读懂;`do` 是为了被机器执行。两者不应再分家。 +**Marqdo** = **Marq**(mark / Markdown)+ **do**(执行)。 --- diff --git a/doc/README.md b/doc/README.md index 13cc449..8d2f6f0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,25 +1,29 @@ # Marqdo 开发文档 -本目录存放 Marqdo 各阶段的设计与调研文档,与实现代码分离,便于在语言定型前持续迭代思想。 +本目录存放各阶段设计与调研文档。 ## 目录约定 | 路径 | 用途 | |------|------| -| [`research/`](research/) | 外部标准、论文、相邻系统的调研与借鉴分析 | -| [`design/`](design/) | 语言设计草案、语法、语义、模块模型 | -| `adr/` | 架构决策记录(Architecture Decision Records,待建) | -| `roadmap/` | 阶段目标与里程碑(待建) | +| [`research/`](research/) | 外部标准与调研 | +| [`design/`](design/) | 语言设计(语法映射、清单模型等) | +| `adr/` | 架构决策记录(待建) | +| `roadmap/` | 里程碑(待建) | ## 当前文档 | 文档 | 摘要 | |------|------| -| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | Google OKF 调研,以及对 Marqdo 的可借鉴点 | -| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 机器生成的 OKF 风格 YAML 清单(依赖 / 项目文档,非配置文件) | +| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0 语法宪法**:Markup-as-Syntax 全映射 | +| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 机器生成的 OKF 风格依赖/文档清单 | +| [design/tech-stack.md](design/tech-stack.md) | 参考实现技术选型(TypeScript + remark + Vitest) | +| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | Google OKF 调研与借鉴 | + +示例程序见仓库 [`examples/`](../examples/)。 ## 写作原则 -1. **先思想,后实现** — 文档应说清「为什么」与「约束」,避免过早绑定未验证的语法细节。 -2. **可演进** — 草案用日期或版本标注;被否决的路径保留在 ADR,不默默删除。 -3. **与源文件同构** — 文档本身尽量用清晰 Markdown;示例源文件统一使用 `.mq.md` 后缀。 +1. 先思想,后实现。 +2. 草案可演进;否决项进 ADR。 +3. 示例统一 `.mq.md`。 diff --git a/doc/design/generated-yaml-manifest.md b/doc/design/generated-yaml-manifest.md index c9d672d..c7142f7 100644 --- a/doc/design/generated-yaml-manifest.md +++ b/doc/design/generated-yaml-manifest.md @@ -28,6 +28,8 @@ Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具 **唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。 +**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。 + --- ## 纠正:它不是什么 diff --git a/doc/design/markdown-mapping.md b/doc/design/markdown-mapping.md new file mode 100644 index 0000000..4c1ede8 --- /dev/null +++ b/doc/design/markdown-mapping.md @@ -0,0 +1,266 @@ +# Marqdo 语法映射 v0(Markup-as-Syntax) + +| | | +|---|---| +| 状态 | 已定论(第一版宪法) | +| 日期 | 2026-08-04 | +| 相关 | [生成式 YAML/OKF 清单](generated-yaml-manifest.md) · [OKF 调研](../research/okf-and-marqdo.md) | + +本文规定:Markdown **标记即 Marqdo 语法**。不在文中嵌入 `print` / `fn` / `import` 等外来关键字作为主路径。 + +--- + +## 1. 哲学 + +1. 源文件后缀 `.mq.md`:打开即渲染,运行即程序。 +2. **行首符号**区分代码与注释;注释内一切标记无语义(无副作用强调写在注释行)。 +3. **作用域唯一来源** = 标题 `#` 的个数;缩进不建立作用域。 +4. 工程入口:`index.mq.md`(对齐 OKF 的 index 角色)。 + +--- + +## 2. 行首判别 + +对每一行:跳过前导空白,看第一个非空白字符。 + +| 情况 | 分类 | +|------|------| +| 无非空白,或首字符为普通文字(含 CJK) | **注释** — 忽略行内一切 Markdown 标记 | +| 首字符开启 Markdown/Marqdo 标记 | **代码** — 按标记解释 | + +v0 标记字符至少包括:`#` `*` `>` `+` `-` `` ` `` `|`(表格)以及有序列表数字。 + +空行分隔结构,不执行。 + +--- + +## 3. 缩进政策 + +- **要识别**:CommonMark 列表嵌套缩进;行首先剥空白再认标记。 +- **不要**:把缩进做成 Python 式作用域(作用域只认 `#` 层级)。 +- **避免**:用 ≥4 空格缩进普通注释段(会变成 GFM 缩进代码块,破坏「打开即文档」)。v0 对此应警告或报错。 + +--- + +## 4. 映射总表 + +| 标记 | 语义 | +|------|------| +| `#` … `######` | 函数 / 代码块;层数 = 嵌套与作用域 | +| 函数头下 `-` 纯名 | 形参(每行一个) | +| 体内 `-` | **循环**(while / foreach) | +| 体内 `+` | **分支**(推荐) | +| 体内 `1.` `2.` … | **分支**(同样合法) | +| 分支臂整行恰为 `*` | else | +| `> 函数 形参=实参` | 调用 | +| frontmatter 中 `> path.mq.md` | **跨文件导入** | +| `**…**` | **输出**(stdout) | +| `*…*` | **返回值** | +| `` `name` `` | 变量;行首 `` `名` = … `` 为绑定 | +| `` `a` == `b` `` | 相等比较(比较不用单独 `=`) | +| GFM 表格 | 集合字面量 | +| 无标记行 | 注释 | +| ` ```lang ` 围栏 | 外联异种代码(FFI 细节后置) | + +--- + +## 5. Frontmatter 元信息与跨文件 + +```markdown +--- +title: 主程序 +description: 示例入口 +> utils.mq.md +> lib/math.mq.md +--- +``` + +- 可含普通 YAML 键值(`title`、`description` 等)与 **`>` 导入行**(Marqdo 扩展;实现按行扫描,勿假定整块为纯 YAML)。 +- `> path.mq.md`:导入目标文件顶层公有定义(顶层 `#`);`##` 及更内层默认不导出。 +- 路径相对当前文件。生成 OKF 依赖清单时可从这些行收集边。 +- 正文 `> 名字 …` 为调用;frontmatter `> ….mq.md` 为文件导入(以路径/后缀区分)。 + +源 frontmatter = 文稿/代码元信息 + 人手声明的导入;工程级 OKF 目录仍由工具生成(见 [generated-yaml-manifest.md](generated-yaml-manifest.md))。 + +--- + +## 6. 函数、作用域、提升 + +```markdown +# 输出函数 + - 输出内容 + +*`输出内容`* +``` + +- `#` 个数决定嵌套;内层可见外层;内层同名遮蔽外层。 +- **定义顺序不影响可调用性**:Pass1 收集标题树,Pass2 再执行(提升)。 +- **推荐**:非公有助手写成调用方下的 `##`,缩小作用域、减少泄露。 +- **公有**:与入口同级的顶层 `#`,可供其它文件在导入后 `>` 调用。 + +推荐写法(调用可出现在内嵌定义之前,靠提升;调用写在 `# main` 下、`##` 之前,以免落入子节): + +```markdown +# main + +> 输出函数 输出内容=Hello World! + +## 输出函数 + - 输出内容 + +**`输出内容`** +``` + +(上例「输出函数」体用 `**…**` 做输出;若交回值则用 `*…*`。) + +形参 `- 输出内容` 在体内以 `` `输出内容` `` 引用。 + +--- + +## 7. 输出与返回 + +| 构造 | 作用 | +|------|------| +| `**…**` | 输出到 stdout;可嵌 `` `变量` `` | +| `*…*` | 函数返回值;可嵌变量与表达式 | +| 注释行内的 `*` / `**` | 无语义 | + +else 消歧:分支臂**第一行整行恰好一个** `*` → else。 +`*中间有内容*` → 返回,不是 else。 + +```markdown +# 加一 + - n + +*`n` + 1* +``` + +绑定调用返回值(细写可后续收紧): + +```markdown +`y` = > 加一 n=3 +``` + +--- + +## 8. 绑定与比较 + +| 写法 | 含义 | +|------|------| +| `` `x` = 1 `` | 绑定 | +| `` `x` == 1 `` | 相等比较 | +| `` `x` = `y` `` | 绑定(右值为引用) | + +比较还支持 v0 最小集:`>` `<` `>=` `<=`(出现在臂头/while 头/表达式中时)。 + +--- + +## 9. 分支(`+` 或有序) + +自上而下找第一个条件为真的臂执行;else 必须在最后。 + +```markdown +`x` = 0 + ++ `x` > 0 + **正数** ++ `x` < 0 + **负数** ++ * + **零** +``` + +有序形式同等合法。v0 **不用** `*` 作为无序列表项目符(避免与 else、斜体冲突)。 + +--- + +## 10. 循环(仅 `-`) + +| 项头形状 | 种类 | +|----------|------| +| `[元素](集合)` | foreach:链接文字=循环变量,目标=集合名 | +| 布尔条件 | while | +| 其它 | 编译错误 | + +多项顶层 `-` = 依次执行多个循环。 + +```markdown +- [果](篮子) + **今天吃`果`** + +- `n` > 0 + **`n`** + `n` = `n` - 1 +``` + +--- + +## 11. 集合:GFM 表格 + +以 GFM 为准(纯 CommonMark 无表格)。须有表头行 + 分隔行。 + +```markdown +`篮子` = + +| 果 | +|----| +| 苹果 | +| 梨 | +``` + +| 形状 | 含义 | +|------|------| +| 单列多行 | 序列 | +| 单行多列 | 元组 / 向量 | +| 多列多行 | 记录序列;表头=字段名,行进入 foreach 后字段名进作用域 | +| 仅表头无数据 | 空集合 | + +`` `名` = `` 后紧跟表格块 → 表格为右值。单列/单行均合法。 + +--- + +## 12. 三种 `-` / 列表消歧 + +1. **形参**:紧跟函数标题,项为纯标识符名。 +2. **循环**:函数体内,项目符为 `-`,项头为链接或条件。 +3. **分支**:项目符为 `+`,或有序列表。 + +--- + +## 13. 求值入口 + +1. 加载 `index.mq.md` 与 frontmatter(含 `>` 导入)。 +2. Pass1:加载导入文件;收集所有函数定义树。 +3. Pass2:优先执行顶层 `# main`;若无,按文档序执行顶层可执行节点。 +4. 遇 `-` 列表 → 循环;遇 `+` / 有序 → 分支;遇 `>` / `**` / `*` / 绑定 / 表 → 相应动作。 + +--- + +## 14. v0 非目标 + +- `break` / `continue`、完整错误模型、标准输入 +- 静态类型系统、完整 FFI 约定 +- 用 `*` 作无序列表符 + +--- + +## 15. 已知后续 ADR + +- `>` 调用作右值的空白与多实参细写 +- 记录字段名遮蔽规则 +- frontmatter 字段正式 schema +- 表达式与运算符全文法 + +--- + +## 16. 示例索引 + +| 文件 | 说明 | +|------|------| +| [examples/hello.mq.md](../../examples/hello.mq.md) | 最小输出 | +| [examples/index.mq.md](../../examples/index.mq.md) | 推荐入口:main + 内嵌 + 调用 | +| [examples/branch.mq.md](../../examples/branch.mq.md) | `+` 分支 | +| [examples/loop.mq.md](../../examples/loop.mq.md) | while / foreach | +| [examples/collection.mq.md](../../examples/collection.mq.md) | 表格集合 | +| [examples/utils.mq.md](../../examples/utils.mq.md) | 供导入的公有函数 | +| [examples/with-import.mq.md](../../examples/with-import.mq.md) | frontmatter `>` 跨文件 | diff --git a/doc/design/tech-stack.md b/doc/design/tech-stack.md new file mode 100644 index 0000000..92cf05e --- /dev/null +++ b/doc/design/tech-stack.md @@ -0,0 +1,74 @@ +# 技术选型 v0(参考实现) + +| | | +|---|---| +| 状态 | 草案(选型结论) | +| 日期 | 2026-08-04 | +| 目标 | 能跑通 `examples/*.mq.md` 的解析 + 求值,并用测试锁定行为 | + +--- + +## 结论 + +**第一版参考实现采用 TypeScript(Node.js ≥ 20)+ 统一语系 Markdown 工具链 + Vitest。** + +| 层 | 选择 | 理由 | +|----|------|------| +| 语言 | TypeScript | 与 GFM/MD 生态最贴;类型利于 AST;后续可编译到 WASM/CLI | +| Markdown 解析 | `remark-parse` + `remark-gfm` + `mdast` | 得到标题/列表/强调/表格/引用的标准 AST,避免手写 GFM | +| 运行 | Node.js ESM | CLI 简单;`fs` 读 `.mq.md` | +| 测试 | Vitest | 快;用 fixtures 对照 `examples/` 期望 stdout | +| 包管理 | pnpm | 锁文件清晰(亦可用 npm) | + +**暂不采用:** Python 快速原型(后期两套实现成本高)、Rust 首版(MD 生态与迭代速度不如 TS 适合验证语法宪法)。语法稳定后再考虑 Rust 重写热路径或正式编译器。 + +--- + +## 架构草图 + +``` +.mq.md + → remark/GFM → mdast + → marqdo lower:行首判别、标题树、列表符语义(- / + / 1.) + → AST(函数、调用、输出、返回、分支、循环、表、绑定) + → Pass1 收集定义 + frontmatter `>` 导入 + → Pass2 求值 → stdout / 返回值 +``` + +包建议(仓库内): + +``` +packages/marqdo/ # 或暂用根目录 src/ + src/parse.ts + src/lower.ts + src/eval.ts + src/cli.ts + tests/fixtures/ +``` + +首版 CLI:`marqdo run examples/hello.mq.md` → 打印 `Hello World!` + +--- + +## 测试策略 + +1. **金样例**:每个 `examples/*.mq.md` 对应一份期望输出(`.stdout` 或测试内快照)。 +2. **单元**:行首判别、`-`/`+` 消歧、`*` else vs `*ret*`、表格绑定。 +3. **排查顺序**:先 hello → index → branch → loop → collection → with-import。 + +--- + +## 里程碑 + +1. 脚手架 + `run` hello +2. 函数 / 调用 / 输出 / 返回 +3. 分支 `+` 与循环 `-` +4. 表格集合 + foreach +5. frontmatter `>` 导入 + +--- + +## 非目标(本选型文档) + +- LSP、格式化、编译到原生 +- 完整表达式文法一次性做完(按测试增量加) diff --git a/examples/branch.mq.md b/examples/branch.mq.md new file mode 100644 index 0000000..6827a0d --- /dev/null +++ b/examples/branch.mq.md @@ -0,0 +1,16 @@ +--- +title: 分支示例 +--- + +# main + +根据 `x` 的符号输出中文说明。使用 `+` 作为分支列表符;最后一臂 `*` 为 else。 + +`x` = 0 + ++ `x` > 0 + **正数** ++ `x` < 0 + **负数** ++ * + **零** diff --git a/examples/collection.mq.md b/examples/collection.mq.md new file mode 100644 index 0000000..3d161b5 --- /dev/null +++ b/examples/collection.mq.md @@ -0,0 +1,18 @@ +--- +title: 集合(表格)示例 +--- + +# main + +用 GFM 单列表格定义序列,再 foreach 打印。 + +`篮子` = + +| 果 | +|----| +| 苹果 | +| 梨 | +| 桃 | + +- [果](篮子) + **`果`** diff --git a/examples/hello.mq.md b/examples/hello.mq.md new file mode 100644 index 0000000..a6c8245 --- /dev/null +++ b/examples/hello.mq.md @@ -0,0 +1,5 @@ +# Hello World + +本程序向标准输出打印一句问候。注释里的 **强调** 不会输出。 + +**Hello World!** diff --git a/examples/index.mq.md b/examples/index.mq.md new file mode 100644 index 0000000..894b98b --- /dev/null +++ b/examples/index.mq.md @@ -0,0 +1,15 @@ +--- +title: Hello World +description: 推荐风格入口——内嵌助手函数与调用(调用可写在定义之前,靠提升解析) +--- + +# main + +向标准输出打印一句问候。助手函数定义在 main 内部,避免名字泄露。 + +> 输出函数 输出内容=Hello World! + +## 输出函数 + - 输出内容 + +**`输出内容`** diff --git a/examples/loop.mq.md b/examples/loop.mq.md new file mode 100644 index 0000000..71d87cc --- /dev/null +++ b/examples/loop.mq.md @@ -0,0 +1,25 @@ +--- +title: 循环示例 +--- + +# main + +## while:倒数 + +`n` = 3 + +- `n` > 0 + **`n`** + `n` = `n` - 1 + +## foreach:遍历篮子 + +`篮子` = + +| 果 | +|----| +| 苹果 | +| 梨 | + +- [果](篮子) + **今天吃`果`** diff --git a/examples/utils.mq.md b/examples/utils.mq.md new file mode 100644 index 0000000..842210c --- /dev/null +++ b/examples/utils.mq.md @@ -0,0 +1,14 @@ +--- +title: 工具函数 +description: 供其它文件通过 frontmatter > 导入的公有模块 +--- + +# 加一 + - n + +*`n` + 1* + +# 问候 + - 谁 + +**你好,`谁`!** diff --git a/examples/with-import.mq.md b/examples/with-import.mq.md new file mode 100644 index 0000000..70fdffd --- /dev/null +++ b/examples/with-import.mq.md @@ -0,0 +1,14 @@ +--- +title: 跨文件导入示例 +> utils.mq.md +--- + +# main + +frontmatter 中的 `> utils.mq.md` 导入同目录公有函数,再调用并打印返回值。 + +`y` = > 加一 n=41 + +**`y`** + +> 问候 谁=Marqdo