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 <cursoragent@cursor.com>
This commit is contained in:
1 parent
117a03ca8e
commit
2cb05fd838
12 files changed
+507
-128
No files matched your search
@@ -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**(执行)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+14
-10
@@ -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`。
|
||||
@@ -28,6 +28,8 @@ Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具
|
||||
|
||||
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
|
||||
|
||||
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
|
||||
|
||||
---
|
||||
|
||||
## 纠正:它不是什么
|
||||
|
||||
@@ -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 `>` 跨文件 |
|
||||
@@ -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、格式化、编译到原生
|
||||
- 完整表达式文法一次性做完(按测试增量加)
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: 分支示例
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
根据 `x` 的符号输出中文说明。使用 `+` 作为分支列表符;最后一臂 `*` 为 else。
|
||||
|
||||
`x` = 0
|
||||
|
||||
+ `x` > 0
|
||||
**正数**
|
||||
+ `x` < 0
|
||||
**负数**
|
||||
+ *
|
||||
**零**
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: 集合(表格)示例
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
用 GFM 单列表格定义序列,再 foreach 打印。
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
|
||||
- [果](篮子)
|
||||
**`果`**
|
||||
@@ -0,0 +1,5 @@
|
||||
# Hello World
|
||||
|
||||
本程序向标准输出打印一句问候。注释里的 **强调** 不会输出。
|
||||
|
||||
**Hello World!**
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Hello World
|
||||
description: 推荐风格入口——内嵌助手函数与调用(调用可写在定义之前,靠提升解析)
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
向标准输出打印一句问候。助手函数定义在 main 内部,避免名字泄露。
|
||||
|
||||
> 输出函数 输出内容=Hello World!
|
||||
|
||||
## 输出函数
|
||||
- 输出内容
|
||||
|
||||
**`输出内容`**
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: 循环示例
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
## while:倒数
|
||||
|
||||
`n` = 3
|
||||
|
||||
- `n` > 0
|
||||
**`n`**
|
||||
`n` = `n` - 1
|
||||
|
||||
## foreach:遍历篮子
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
|
||||
- [果](篮子)
|
||||
**今天吃`果`**
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 工具函数
|
||||
description: 供其它文件通过 frontmatter > 导入的公有模块
|
||||
---
|
||||
|
||||
# 加一
|
||||
- n
|
||||
|
||||
*`n` + 1*
|
||||
|
||||
# 问候
|
||||
- 谁
|
||||
|
||||
**你好,`谁`!**
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 跨文件导入示例
|
||||
> utils.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
frontmatter 中的 `> utils.mq.md` 导入同目录公有函数,再调用并打印返回值。
|
||||
|
||||
`y` = > 加一 n=41
|
||||
|
||||
**`y`**
|
||||
|
||||
> 问候 谁=Marqdo
|
||||
Reference in new issue
Block a user