Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
7848180454 | ||
|
|
69fecaeaab | ||
|
|
04098db74c | ||
|
|
96a7c6ce76 |
No files matched your search
@@ -0,0 +1,50 @@
|
||||
# Build public/ with marqdo and publish to the gh-pages branch.
|
||||
name: User docs site
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, master]
|
||||
paths:
|
||||
- "public/**"
|
||||
- "src/**"
|
||||
- "Cargo.toml"
|
||||
- "Cargo.lock"
|
||||
- ".github/workflows/pages.yml"
|
||||
- "scripts/build-public.*"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build-and-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Build & export site
|
||||
run: |
|
||||
cargo build --release
|
||||
find public -name '*.mq.md' ! -name 'utils.mq.md' -print0 \
|
||||
| xargs -0 -n1 ./target/release/marqdo run
|
||||
./target/release/marqdo view output public -o public
|
||||
|
||||
- name: Verify site shape
|
||||
run: |
|
||||
if grep -R "tests/errors" public --include='*.html' ; then
|
||||
echo "user site must not include tests/errors fixtures" >&2
|
||||
exit 1
|
||||
fi
|
||||
test -f public/index.html
|
||||
test -f public/00-welcome.mq.md
|
||||
|
||||
- name: Deploy to gh-pages
|
||||
uses: peaceiris/actions-gh-pages@v4
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./public
|
||||
publish_branch: gh-pages
|
||||
force_orphan: true
|
||||
@@ -4,6 +4,11 @@
|
||||
.vscode/
|
||||
*.pdb
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
/public/index.html
|
||||
/public/pages/
|
||||
|
||||
# Python spike venv (local)
|
||||
spike/.venv/
|
||||
|
||||
Generated
+1
-1
@@ -210,7 +210,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "0.1.0"
|
||||
version = "0.0.3"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.0.1"
|
||||
version = "0.0.3"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程序。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 示例布局:[examples-and-tests.md](doc/design/examples-and-tests.md) · 浏览:[view.md](doc/design/view.md) · 示例:[examples/](examples/)
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 测试布局:[examples-and-tests.md](doc/design/examples-and-tests.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
|
||||
|
||||
---
|
||||
|
||||
@@ -48,19 +48,22 @@ Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程
|
||||
|
||||
- 映射 v0.1:[markdown-mapping.md](doc/design/markdown-mapping.md)
|
||||
- 解释器路线图:[interpreter.md](doc/roadmap/interpreter.md)
|
||||
- **Phase I(树遍历)已通**:`examples/structure/` 与 `examples/keywords/` 金样例均可 `marqdo run`
|
||||
- **view**:`marqdo view examples` 按 AST 浏览结构与输出
|
||||
- **Phase I(树遍历)已通**:`tests/structure/` 与 `tests/keywords/` 金样例均可 `marqdo run`
|
||||
- **view**:`marqdo view public` 浏览用户文档;金样例用 `marqdo view tests`
|
||||
- **用户静态站**:可执行文稿在 `public/`(无 errors);`view output` 生成 HTML(ignore),CI 发布到 `gh-pages` — 见 [user-site.md](doc/design/user-site.md)
|
||||
- 依赖(Rust,无 Flex/Bison):[dependencies.md](doc/design/dependencies.md)
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
|
||||
```bash
|
||||
cargo run -- run examples/structure/hello.mq.md
|
||||
cargo run -- run examples/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view examples --no-open
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
cargo run -- run tests/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view public --no-open
|
||||
cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
cargo run -- catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
当前发布:**v0.0.1**(Phase I 树遍历 + `view` + M5 字节码原型)。M5 见 [bytecode.md](doc/design/bytecode.md);errors 见 `examples/errors/`。
|
||||
|
||||
文档:用户站见 [public/](public/) 与 [user-site.md](doc/design/user-site.md);设计文稿见 [doc/](doc/);`view` 皮肤见 [view.md](doc/design/view.md);OKF 清单见 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+5
-3
@@ -24,15 +24,17 @@
|
||||
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置 `print` `input`** |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **示例即金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` 源结构浏览器** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
|
||||
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
|
||||
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
|
||||
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
|
||||
| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
|
||||
示例与验收集:[`examples/`](../examples/)。Spike 存档:[`spike/`](../spike/)。
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
## 写作原则
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@
|
||||
## 后果
|
||||
|
||||
- 正式代码以 Cargo 工程生长;不把 Flex/Bison/LLVM 列入 v1 依赖。
|
||||
- 金样例仍为 `examples/`;行为与宪法一致。
|
||||
- 金样例仍为 `tests/`;行为与宪法一致。
|
||||
- 此前「Python 作参考实现」的倾向由本修订取代;Spike 结论(行扫描等)仍然有效并迁入 Rust。
|
||||
|
||||
---
|
||||
|
||||
@@ -68,7 +68,7 @@
|
||||
| `structure/nested-call` | ✅ | ✅ |
|
||||
| `structure/positional-call` | ✅ | ✅ |
|
||||
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
|
||||
| `examples/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
|
||||
| `tests/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
|
||||
|
||||
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
|
||||
|
||||
|
||||
@@ -47,4 +47,4 @@ positional ::= value_token
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `examples/structure/positional-call.mq.md` 与更新后的 `examples/structure/import/`。
|
||||
见 `tests/structure/positional-call.mq.md` 与更新后的 `tests/structure/import/`。
|
||||
@@ -0,0 +1,128 @@
|
||||
# OKF 兼容清单:`marqdo catalog`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0 命令落地) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
|
||||
| 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 决策(重申)
|
||||
|
||||
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
||||
|
||||
本文件规定 **CLI 与 v0 落盘格式**。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
# 别名(与早期草案一致)
|
||||
marqdo sync [PATH] -o OUT_DIR
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件) |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物(v0)
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
catalog.yaml # 机器向总清单(OKF 风格字段)
|
||||
index.md # 人/Agent 可读总览(含 YAML frontmatter)
|
||||
modules/
|
||||
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
|
||||
```
|
||||
|
||||
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
|
||||
|
||||
`structure/import/main.mq.md` → `modules/structure__import__main.md`
|
||||
|
||||
### 3.1 `catalog.yaml`(示意)
|
||||
|
||||
```yaml
|
||||
# GENERATED by marqdo — do not edit by hand
|
||||
type: Marqdo Catalog
|
||||
title: marqdo-project
|
||||
generated:
|
||||
by: marqdo/0.0.1
|
||||
# at: 可选 ISO8601;CI 比对时可忽略
|
||||
modules:
|
||||
- id: structure/hello
|
||||
resource: structure/hello.mq.md
|
||||
title: Hello World # 来自源 frontmatter title,缺省用文件名
|
||||
imports: []
|
||||
exports:
|
||||
- name: Hello World
|
||||
kind: fn
|
||||
- id: structure/import/main
|
||||
resource: structure/import/main.mq.md
|
||||
imports:
|
||||
- utils.mq.md
|
||||
exports:
|
||||
- name: main
|
||||
kind: fn
|
||||
```
|
||||
|
||||
字段约定(v0 最小集):
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
|
||||
| `modules[].resource` | 相对 `PATH` 的源路径 |
|
||||
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
|
||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
|
||||
| `generated.by` | `marqdo/<crate version>` |
|
||||
|
||||
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
|
||||
|
||||
### 3.2 模块概念页 frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Module
|
||||
title: …
|
||||
resource: structure/hello.mq.md
|
||||
depends: [] # imports 列表
|
||||
exports: [Hello World]
|
||||
generated:
|
||||
by: marqdo/0.0.1
|
||||
---
|
||||
```
|
||||
|
||||
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view output` 的分工
|
||||
|
||||
| 命令 | 产物 | 受众 |
|
||||
|------|------|------|
|
||||
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
|
||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
|
||||
|
||||
二者都从同一源树生成,互不替代。发布用户文档时可同时:
|
||||
|
||||
```bash
|
||||
marqdo view output public -o public
|
||||
marqdo catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。
|
||||
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
|
||||
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
||||
4. `marqdo sync` 与 `catalog` 行为一致。
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐 |
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
@@ -11,12 +11,19 @@
|
||||
|
||||
| 层 | 形态 | 角色 |
|
||||
|----|------|------|
|
||||
| **叙述面** | 无标记行 | 注释;内部标记无语义 |
|
||||
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
|
||||
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
|
||||
| **外联面** | ` ```lang ` | 其它语言(FFI) |
|
||||
|
||||
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
|
||||
|
||||
### 成段注释
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` 等开头)。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
## 语句 vs 返回 vs 输出
|
||||
@@ -25,4 +32,6 @@
|
||||
|-----------|------|------------|
|
||||
| `*…*` | 程序语句 | 是 |
|
||||
| `**…**` | 返回值 | 是 |
|
||||
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
|
||||
| `> print …` | 打印副作用 | 否(内置函数) |
|
||||
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
|
||||
@@ -1,4 +1,4 @@
|
||||
# Marqdo 实现依赖说明(Rust 参考解释器)
|
||||
# Marqdo 实现依赖说明(Rust 参考解释器)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -94,7 +94,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **rust 自带** `#[test]` | 单元测试 |
|
||||
| **insta** 或手写金文件 | examples 期望 stdout 快照(可选) |
|
||||
| **insta** 或手写金文件 | tests 期望 stdout 快照(可选) |
|
||||
| **assert_cmd** / **predicates** | CLI 集成测试(可选) |
|
||||
|
||||
#### Phase II(字节码 VM,后加)
|
||||
@@ -142,8 +142,8 @@ crates/marqdo/ # 或根包 marqdo
|
||||
interp/ # Phase I
|
||||
bytecode/ # Phase II
|
||||
runtime/
|
||||
tests/
|
||||
examples/ # 金样例(已有)
|
||||
tests/ # gold.rs + structure|keywords|errors
|
||||
public/ # 用户可执行文档
|
||||
spike/ # Python 风险探测存档(可保留,非运行时依赖)
|
||||
```
|
||||
|
||||
@@ -152,7 +152,7 @@ spike/ # Python 风险探测存档(可保留,非运行
|
||||
```bash
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run examples/structure/nested-call.mq.md
|
||||
cargo run -- run tests/structure/nested-call.mq.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -4,33 +4,37 @@
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **示例即金样例**:`examples/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view` 也可直接浏览 |
|
||||
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目录
|
||||
|
||||
只保留 **`tests/`**,用子目录区分类别(不再另设 `examples/`):
|
||||
|
||||
```
|
||||
examples/
|
||||
README.md # 本树说明
|
||||
tests/
|
||||
README.md
|
||||
gold.rs # 集成测试入口
|
||||
structure/ # 代码基础结构(Markup 架构)
|
||||
hello.mq.md
|
||||
nested-call.mq.md # 原 index:嵌套函数 + 调用
|
||||
positional-call.mq.md # 位置实参
|
||||
nested-call.mq.md
|
||||
positional-call.mq.md
|
||||
branch.mq.md
|
||||
loop.mq.md
|
||||
collection.mq.md
|
||||
import/
|
||||
main.mq.md # 原 with-import
|
||||
main.mq.md
|
||||
utils.mq.md
|
||||
keywords/ # 关键字与内置名
|
||||
print.mq.md
|
||||
bool-logic.mq.md # True/False/None、and/or/not
|
||||
bool-logic.mq.md
|
||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
||||
.gitkeep
|
||||
…
|
||||
```
|
||||
|
||||
Rust 集成测试:`tests/gold.rs` 扫描约定路径,比对 stdout。
|
||||
面向访客的可执行介绍在 [`public/`](../../public/)(无 `errors/`),见 [user-site.md](user-site.md)。
|
||||
开发设计文稿在 [`doc/`](../)(单数)。
|
||||
|
||||
---
|
||||
|
||||
@@ -42,7 +46,7 @@ Rust 集成测试:`tests/gold.rs` 扫描约定路径,比对 stdout。
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
未单独建夹、但应覆盖的其它测试(放 `tests/` 单测或日后 `examples/runtime/`):
|
||||
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
|
||||
|
||||
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
|
||||
- **CLI**:默认 `index.mq.md`、退出码
|
||||
@@ -53,24 +57,12 @@ Rust 集成测试:`tests/gold.rs` 扫描约定路径,比对 stdout。
|
||||
|
||||
## 3. 金样例约定
|
||||
|
||||
每个可执行 `.mq.md` 在 `tests/gold.rs`(或旁路 `.out` 文件)登记期望 stdout。
|
||||
每个可执行 `.mq.md` 在 `tests/gold.rs` 登记期望 stdout。
|
||||
`errors/` 内文件登记期望 stderr 子串与非零退出码。
|
||||
|
||||
Frontmatter 可写:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: …
|
||||
expect_stdout: |
|
||||
line1
|
||||
line2
|
||||
---
|
||||
```
|
||||
|
||||
(可选;v0 先以测试代码内嵌期望为主。)
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view` 的关系
|
||||
## 4. 与 `view` / `public` 的关系
|
||||
|
||||
`marqdo view examples` 按上述文件夹生成侧栏索引;`structure` / `keywords` 为一级分组。
|
||||
- `marqdo view tests`:开发者浏览金样例(含 errors)。
|
||||
- `marqdo view public`:用户文档站源;**不要**把 `tests/errors` 编进 `public/`。
|
||||
@@ -149,11 +149,11 @@ Marqdo 有两层「文档」,不要混为一谈:
|
||||
|
||||
## 待决问题(后续 ADR)
|
||||
|
||||
- [ ] 生成物落盘路径(例如 `.marqdo/` vs `docs/catalog/`)及是否提交进 git
|
||||
- [ ] 单文件是否仍写入「生成型 frontmatter」,还是全部集中在工程级 OKF 包
|
||||
- [ ] 与 `Cargo.toml` 式「可手写包身份(name/version)」的边界:是否允许极少量非生成的包清单,与全自动 OKF 目录如何分工
|
||||
- [ ] `marqdo sync` / `marqdo doc` 命令的具体行为
|
||||
- [ ] 是否沿用 OKF v0.2 的 `generated` / `sources` 字段描述溯源
|
||||
- [x] 生成物默认路径:`.marqdo/`(`-o` 可改)— 见 [catalog-cli.md](catalog-cli.md)
|
||||
- [x] `marqdo catalog` / `sync`;静态用户文档:`marqdo view output` — 见 [view.md](view.md)
|
||||
- [ ] 是否提交生成物进 git(项目自定;CI 可校验干净生成)
|
||||
- [ ] 与「可手写包身份 name/version」的边界
|
||||
- [ ] 是否沿用 OKF v0.2 的 `sources` 等溯源字段
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **英文标识**:内置与字面量用英文,便于工具高亮与国际协作。
|
||||
3. **学 Python 的边界**:Python 3 里 [`print` / `input` 是内置函数,不是关键字](https://realpython.com/python-keywords/);布尔与空值是字面量关键字。Marqdo 同样区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:前期只列执行 examples 所需;要加再进 ADR。
|
||||
4. **宁少勿多**:前期只列执行金样例所需;要加再进 ADR。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
|
||||
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -14,22 +14,24 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
## 1. 哲学
|
||||
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **无标记行 = 叙述注释**(内部任何标记无语义)。
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。
|
||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 行首判别
|
||||
## 2. 行首判别与成段注释
|
||||
|
||||
跳过前导空白后:
|
||||
跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始):
|
||||
|
||||
| 首字符 | 分类 |
|
||||
|--------|------|
|
||||
| 普通文字 / 空 | **注释** |
|
||||
| 标记字符 | **代码** |
|
||||
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的分割线 `---` / `***`(见 §11)。
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||||
|
||||
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
|
||||
|
||||
---
|
||||
|
||||
@@ -46,10 +48,11 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
| 无标记行 | 注释 |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| 无标记行 / 成段续行 | 注释(空行分段,见 §2) |
|
||||
| GFM 表格 | 集合 |
|
||||
| ` ```lang ` | 外联异种代码 |
|
||||
| `---` / `***` | **可选**:框住分支/循环块(美化/分组;v0.1 不强制,见 §11) |
|
||||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
|
||||
|
||||
### 输出不是架构
|
||||
|
||||
@@ -176,36 +179,42 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
|
||||
|
||||
---
|
||||
|
||||
## 11. 分割线框住分支/循环(可选、非强制)
|
||||
## 11. 函数体结束(`---` / `***` / 空返回)
|
||||
|
||||
允许用 `---` 或 `***` 将分支/循环块视觉框起来,便于阅读:
|
||||
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
|
||||
|
||||
```markdown
|
||||
---
|
||||
+ `x` > 0
|
||||
> print text=正
|
||||
+ *
|
||||
> print text=其它
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| v0.1 | **不强制**;无框同样合法 |
|
||||
| 语义 | 若使用,框内仍是原列表语义;分割线本身不产生控制流 |
|
||||
| 保留 | 日后若缺「块」类关键语法,可升级分割线为强制块边界 |
|
||||
| 消歧 | 仅文件开头的 `---` 对 = frontmatter;函数体内成对/成段的 `---`/`***` = 可选框 |
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
|
||||
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
|
||||
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
|
||||
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
|
||||
|
||||
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
|
||||
|
||||
---
|
||||
|
||||
## 12. v0.1 非目标
|
||||
|
||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||||
- 强制分割线框
|
||||
- 用 `*` 作无序列表符
|
||||
|
||||
---
|
||||
|
||||
## 13. 示例索引
|
||||
|
||||
见 [`examples/`](../../examples/)。
|
||||
见 [`tests/`](../../tests/)。
|
||||
@@ -1,4 +1,4 @@
|
||||
# 解释器流水线可视调试
|
||||
# 解释器流水线可视调试
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -43,7 +43,7 @@ marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||||
## 3. 横幅示例
|
||||
|
||||
```
|
||||
=== marqdo: lines (examples/hello.mq.md) ===
|
||||
=== marqdo: lines (tests/structure/hello.mq.md) ===
|
||||
1 Blank
|
||||
2 Comment | # Hello World
|
||||
3 Blank
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已决议(并入 mapping v0.1 + keywords) |
|
||||
| 状态 | 已决议(并入 mapping v0.1 + keywords;2026-08-04 修订函数收束) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
@@ -10,9 +10,10 @@
|
||||
## 决议
|
||||
|
||||
1. **`*…*` = 程序语句**。
|
||||
2. **`**…**` = 返回值**(架构级)。
|
||||
2. **`**…**` = 返回值**(架构级);空粗体 `****` / `** **` = 空返回(`None`)并结束函数体。
|
||||
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
|
||||
4. **`---` / `***`**:可选框住分支/循环,不强制。
|
||||
5. **否决**:无标记行 = 默认代码。
|
||||
4. **`---` / `***`(函数体顶层)**:结束本函数体(无返回值函数收束);**不是**分支/循环装饰框。
|
||||
5. **成段注释**:空行分段;段内续行不因首字符升级为代码。
|
||||
6. **否决**:无标记行 = 默认代码。
|
||||
|
||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)。
|
||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)、[code-vs-comment.md](code-vs-comment.md)。
|
||||
@@ -1,4 +1,4 @@
|
||||
# 参考实现:技术选型分析(尚未拍板)
|
||||
# 参考实现:技术选型分析(尚未拍板)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -18,7 +18,7 @@
|
||||
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
|
||||
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
|
||||
4. **两遍**:收集定义 + 导入 → 求值
|
||||
5. **CLI** + **金样例测试**(`examples/`)
|
||||
5. **CLI** + **金样例测试**(`tests/`)
|
||||
|
||||
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
|
||||
|
||||
@@ -51,7 +51,7 @@
|
||||
→ Marqdo AST
|
||||
→ 语义:导入图、提升、作用域
|
||||
→ 后端:解释器(v0)/日后编译
|
||||
→ 测试:examples → 期望 stdout
|
||||
→ 测试:tests 金样例 → 期望 stdout
|
||||
```
|
||||
|
||||
**前端可复用成熟 GFM 库,也可自研**;Middle/后端必须自研(这是语言本体)。
|
||||
@@ -130,7 +130,7 @@
|
||||
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
|
||||
- 候选 B:Rust + comrak/pulldown — 同上。
|
||||
- (可选)C 或 D 若团队有偏好再做。
|
||||
2. **对照验收用例**(固定):`examples/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
|
||||
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
|
||||
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
|
||||
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
|
||||
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# 用户静态文档站(public / gh-pages)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 分工
|
||||
|
||||
| 路径 | 是否入库 | 职责 |
|
||||
|------|----------|------|
|
||||
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / 特性迭代) |
|
||||
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
|
||||
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
|
||||
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
|
||||
|
||||
**禁止**把 `tests/errors/` 编进用户站。
|
||||
|
||||
---
|
||||
|
||||
## 2. 生成
|
||||
|
||||
```bash
|
||||
cargo run --release -- view output public -o public
|
||||
# 或
|
||||
./scripts/build-public.sh
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
产物写在源旁:
|
||||
|
||||
```
|
||||
public/
|
||||
*.mq.md / structure/ / … # 入库源
|
||||
index.html # 生成(ignore)
|
||||
pages/… # 生成(ignore)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 发布分支
|
||||
|
||||
将构建后的 `public/` 推到 **`gh-pages`**。CI:`.github/workflows/pages.yml`。
|
||||
|
||||
仓库 Settings → Pages → Source = Deploy from branch → `gh-pages` / root。
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收
|
||||
|
||||
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
|
||||
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
|
||||
3. 主分支跟踪 `public/**/*.mq.md`;不提交 `public/index.html` / `public/pages/`。
|
||||
+73
-79
@@ -1,24 +1,44 @@
|
||||
# `marqdo view` — 源结构浏览器
|
||||
# `marqdo view` — 源结构浏览器与静态文档导出
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(实现中) |
|
||||
| 状态 | 已定(v0.0.2 方向) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [pipeline-debug.md](pipeline-debug.md) · AST(`src/ast.rs`) |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 既是文档也是程序。需要一种**可读渲染**,而不仅是纯文本或 `run` 的 stdout:
|
||||
`.mq.md` 既是文档也是程序。需要:
|
||||
|
||||
- 按语法树展示函数、分支、循环、调用、返回;
|
||||
- 同页展示**执行结果**;
|
||||
- 支持打开**单个文件**或**文件夹**(扫描全部 `.mq.md` + 结构索引)。
|
||||
1. **本地浏览**:按 AST 展示结构 + 执行结果;
|
||||
2. **静态导出**:同一套渲染写成 HTML,作为**用户文档站点**(勿手写第二套站点);
|
||||
3. **启动快**:样式极简,无外链字体/厚主题,避免 view 冷启动慢。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
## 2. 视觉(Apple HIG / Docs 极简)
|
||||
|
||||
对齐 [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) 的 **clarity / deference / white space**,并参考常见 docs 布局(sticky 侧栏 + 居中主栏,见 Nextra / Docusaurus 类站点):**系统灰底、白内容面、浅分隔线、系统字体**。作者站 [id.cflmy.cn](https://id.cflmy.cn) 仍作克制感参考,但不强行纯黑描边。
|
||||
|
||||
| 规则 | 要求 |
|
||||
|------|------|
|
||||
| 色板 | 页底 `#f5f5f7`;内容面 `#ffffff`;正文 `#1d1d1f`;次要字 `#6e6e73`;分隔 `#d2d2d7`;选中侧栏项反白 |
|
||||
| 布局 | 壳层 `max-width ≈ 1400px` 居中;侧栏 ≈280px sticky;主内容 `max-width ≈ 58rem`(宽屏可读、不过窄);**≤800px 侧栏收起**,顶栏汉堡(checkbox,无 JS) |
|
||||
| 默认页 | 打开目录时 **直接展示排序后的第一个 `.mq.md`**(实时 `/` 与静态 `index.html` 同),不要求用户先从欢迎页点选 |
|
||||
| 字体 | 仅系统栈:`-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif`;等宽 `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
|
||||
| 外链 | **禁止** Google Fonts / CDN 样式;CSS 全部内联于 HTML |
|
||||
| 装饰 | 无多层阴影、无渐变、无发光;圆角 ≈12px;结构区为分组列表(底部分隔),非堆叠厚卡片 |
|
||||
| 诊断路径 | 展示时去掉 Windows `\\?\` 前缀,并优先用相对 view 根的路径 |
|
||||
|
||||
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `40rem` 方案。
|
||||
|
||||
---
|
||||
|
||||
## 3. CLI
|
||||
|
||||
### 3.1 实时浏览
|
||||
|
||||
```bash
|
||||
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
||||
@@ -26,94 +46,68 @@ marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | `.mq.md` 文件,或目录(递归扫描 `*.mq.md`) |
|
||||
| `--port` | `7429` | HTTP 端口 |
|
||||
| `--host` | `127.0.0.1` | 仅本地 |
|
||||
| `--no-open` | 关 | 不尝试打开系统浏览器 |
|
||||
| `PATH` | `.` | `.mq.md` 或目录 |
|
||||
| `--port` | `7429` | |
|
||||
| `--host` | `127.0.0.1` | |
|
||||
| `--no-open` | 关 | 不打开浏览器 |
|
||||
|
||||
### 3.2 静态导出(文档生成)
|
||||
|
||||
```bash
|
||||
marqdo view output [PATH] -o OUT_DIR [--no-exec]
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 与 `view` 相同扫描范围 |
|
||||
| `-o` / `--out` | (必填) | 输出目录(不存在则创建) |
|
||||
| `--no-exec` | 关 | 不跑程序,执行区显示「skipped」 |
|
||||
|
||||
**产物布局:**
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
index.html # 默认 = 排序后第一个 .mq.md 的完整页(侧栏高亮该项)
|
||||
pages/
|
||||
<相对路径>.html # 每个 .mq.md 一页;路径中的 `/` 保留为子目录
|
||||
# 例:structure/hello.mq.md → pages/structure/hello.mq.md.html
|
||||
```
|
||||
|
||||
- 页内链接一律**相对路径**,可用任意静态服务器或 `file://`(同目录结构下)打开。
|
||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||||
|
||||
示例:
|
||||
|
||||
```bash
|
||||
marqdo view examples/structure/hello.mq.md
|
||||
marqdo view examples
|
||||
marqdo view examples/keywords --port 8080
|
||||
marqdo view output public -o public
|
||||
marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
```
|
||||
|
||||
启动后打印 `http://127.0.0.1:7429/`,阻塞直至 Ctrl+C。
|
||||
|
||||
---
|
||||
|
||||
## 3. 信息架构
|
||||
## 4. 信息架构(不变)
|
||||
|
||||
### 3.1 目录模式
|
||||
|
||||
```
|
||||
┌─────────────┬──────────────────────────────────┐
|
||||
│ 索引 │ 选中文件 / 欢迎页 │
|
||||
│ structure/ │ │
|
||||
│ hello │ [源码结构] [执行结果] [原始文本] │
|
||||
│ branch │ │
|
||||
│ keywords/ │ │
|
||||
└─────────────┴──────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 侧栏:相对 `PATH` 的目录树;只列出 `.mq.md`。
|
||||
- 点击文件:主区切换为该文件的三栏/三节视图。
|
||||
|
||||
### 3.2 单文件模式
|
||||
|
||||
无侧栏列表(或仅当前文件);主区同「选中文件」视图。仍提供「执行」结果。
|
||||
侧栏索引 + 主区三节:结构(AST+注释插回)· 执行 · 源码。表达式为表面语法,非 Debug。
|
||||
|
||||
---
|
||||
|
||||
## 4. 主区三节
|
||||
|
||||
### 4.1 源码结构(AST 渲染)
|
||||
|
||||
不依赖浏览器 Markdown 猜测语义,而用服务端已解析的 AST:
|
||||
|
||||
| AST 节点 | 视觉 |
|
||||
|----------|------|
|
||||
| `Function` | 卡片:标题层级、形参芯片、子函数嵌套;**中间的注释行仍展示**(来自源行分类,不在 AST 内) |
|
||||
| `Stmt::*` | 绑定 / 返回 / 调用 / 分支 / 循环;表达式用**表面语法**(如 `` `x` > 0 ``),不用 Debug |
|
||||
|
||||
样式:清晰分区,避免「通用仪表盘」堆砌;结构层级一眼可读。
|
||||
|
||||
### 4.2 执行结果
|
||||
|
||||
服务端对该文件跑与 `marqdo run` 相同的管线,**捕获 stdout/stderr** 与退出状态,展示在「输出」区。
|
||||
含 `input` 的程序:view 中标注「需交互,未在 view 执行」或提供只读说明(v0:跳过/失败信息)。
|
||||
|
||||
### 4.3 原始文本
|
||||
|
||||
等宽展示源文件;可选行分类着色(Code / Comment / Blank),与 `--dump-lines` 一致。
|
||||
|
||||
---
|
||||
|
||||
## 5. HTTP API(实现细节)
|
||||
## 5. HTTP(实时模式)
|
||||
|
||||
| 方法 | 路径 | 含义 |
|
||||
|------|------|------|
|
||||
| `GET` | `/` | 索引 HTML |
|
||||
| `GET` | `/file?path=…` | 单文件页(path 相对根,防 `..` 逃逸) |
|
||||
| `GET` | `/api/tree` | JSON 文件树 |
|
||||
| `GET` | `/api/file?path=…` | JSON:`{ source, ast_html 或 ast_json, stdout, stderr, ok }` |
|
||||
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
|
||||
| `GET` | `/file?path=…` | 单文件页 |
|
||||
| `GET` | `/api/tree` | JSON 树(可选) |
|
||||
|
||||
v0 可全部服务端渲染 HTML,API 可选。
|
||||
|
||||
安全:根目录锁死为 CLI 给定的 `PATH`(若为文件则其父目录为根、仅一文件);拒绝根外路径。
|
||||
根目录锁死;拒绝 `..` 逃逸。
|
||||
|
||||
---
|
||||
|
||||
## 6. 依赖
|
||||
## 6. 验收
|
||||
|
||||
本地同步 HTTP 即可(如 `tiny_http`),无强制前端构建;HTML/CSS/少量 JS 内嵌于 Rust。
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收
|
||||
|
||||
1. `marqdo view examples/structure/hello.mq.md` 显示结构 + `Hello World!` 输出。
|
||||
2. `marqdo view examples` 侧栏含 `structure/` 与 `keywords/` 分组。
|
||||
3. 分支/循环样例在结构区可区分臂与循环体。
|
||||
4. 路径逃逸被拒绝。
|
||||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件。
|
||||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||||
4. 冷启动无明显外网依赖。
|
||||
+3
-2
@@ -33,7 +33,7 @@ cd marqdo
|
||||
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run examples/structure/hello.mq.md
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
```
|
||||
|
||||
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
|
||||
@@ -75,7 +75,8 @@ proxy = "http://127.0.0.1:7897"
|
||||
| `src/lex` | 行分类 / 词法(自研) |
|
||||
| `src/parse` | 递归下降语法 |
|
||||
| `src/diagnostics` | 诊断 |
|
||||
| `examples/` | 金样例(宪法) |
|
||||
| `tests/` | 金样例 + 集成测试(`structure` / `keywords` / `errors`) |
|
||||
| `public/` | 用户可执行文档(无 errors) |
|
||||
| `spike/` | 旧 Python 风险探测,非运行时依赖 |
|
||||
| `doc/` | 设计与路线图 |
|
||||
|
||||
|
||||
+10
-10
@@ -1,4 +1,4 @@
|
||||
# Marqdo 参考实现:正经解释器路线图
|
||||
# Marqdo 参考实现:正经解释器路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -67,7 +67,7 @@ index.mq.md (+ 导入的 .mq.md)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 4a. 树遍历解释器 │ ← Phase I(必须先完成,跑通全部 examples)
|
||||
│ 4a. 树遍历解释器 │ ← Phase I(必须先完成,跑通全部 tests 金样例)
|
||||
│ 或 │
|
||||
│ 4b. 字节码编译+VM │ ← Phase II(性能与「更像真语言实现」)
|
||||
└─────────┬─────────┘
|
||||
@@ -86,7 +86,7 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
|
||||
- 包名:`marqdo`(`src/marqdo/` 或 `marqdo/`)
|
||||
- CLI:`marqdo run <file.mq.md>`,默认找目录下 `index.mq.md`
|
||||
- 诊断:带文件名、行号、列号
|
||||
- 测试:每个 `examples/*.mq.md` 有期望 stdout(金样例);CI 可跑
|
||||
- 测试:每个 `tests/{structure,keywords}/*.mq.md` 有期望 stdout(金样例);CI 可跑
|
||||
|
||||
### Phase I — 可运行的语言核心(树遍历)
|
||||
|
||||
@@ -96,7 +96,7 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
|
||||
2. **语法 → AST**:函数、形参、`*` 语句、`**` 返回、`>` 调用、`+` 分支、`-` 循环、表格集合、绑定与 `==`。
|
||||
3. **语义**:提升、嵌套作用域、`##` 私有、frontmatter 导入公有顶层。
|
||||
4. **运行时**:环境、调用栈、值(文/数/表/记录)、内置 `print`。
|
||||
5. **验收**:`examples/structure/*` 与 `examples/keywords/*` 全部 `marqdo run` 通过。
|
||||
5. **验收**:`tests/structure/*` 与 `tests/keywords/*` 全部 `marqdo run` 通过。
|
||||
|
||||
### Phase II — 字节码 VM(正经化)
|
||||
|
||||
@@ -140,11 +140,11 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
|
||||
|
||||
```
|
||||
Cargo.toml
|
||||
crates/marqdo/ # 或根包
|
||||
src/lex/ parse/ ast/ sema/ interp/ bytecode/ runtime/
|
||||
tests/
|
||||
examples/
|
||||
spike/ # Python 存档,非运行时依赖
|
||||
tests/ # gold.rs + structure|keywords|errors 夹具
|
||||
public/ # 用户可执行文档
|
||||
doc/ # 设计文稿
|
||||
spike/ # Python 存档,非运行时依赖
|
||||
```
|
||||
|
||||
---
|
||||
@@ -170,9 +170,9 @@ spike/ # Python 存档,非运行时依赖
|
||||
在仓库根或任意含 `index.mq.md` 的目录:
|
||||
|
||||
```bash
|
||||
marqdo run examples/structure/nested-call.mq.md
|
||||
marqdo run tests/structure/nested-call.mq.md
|
||||
# 或
|
||||
marqdo run examples/structure/import/main.mq.md
|
||||
marqdo run tests/structure/import/main.mq.md
|
||||
```
|
||||
|
||||
输出与金样例一致;错误带位置;新增语法必须加金样例与单测。这才是「一门解释型语言」的最低合格线。
|
||||
@@ -1,15 +0,0 @@
|
||||
# Marqdo examples(金样例)
|
||||
|
||||
本目录即测试夹具,见 [doc/design/examples-and-tests.md](../doc/design/examples-and-tests.md)。
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| [`structure/`](structure/) | 函数、调用、分支、循环、表、导入、位置实参 |
|
||||
| [`keywords/`](keywords/) | `print`、布尔与 `and`/`or`/`not` |
|
||||
| [`errors/`](errors/) | 期望失败(未定义名 / 未知函数 / 实参 / 语法) |
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
marqdo run examples/structure/hello.mq.md
|
||||
marqdo view examples
|
||||
```
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
title: 欢迎使用 Marqdo
|
||||
description: 用户文档首页 — 代码即文档
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
阅读到这里的朋友你好!我是marqdo的开发者,很高兴你看到这个网站,marqdo是一个代码即文档的编程语言,作者想要做这个项目来源于一个小小的想法,AI输出的首选语言是markdown,为什么不能基于markdown创建一个新式的编程语言,不再区分文档和代码,代码写出来就是一份文档,文档也是代码(这个项目的野心实际更大些,项目立项之处就调研了谷歌OKF规范,计划自动生成YAML使得代码和文档能够自动的变成知识库,与此同时还有更多可能,例如规范化生成的PPT)。
|
||||
|
||||
所以marqdo产生了,为了确保我们的新语言能够百分百被markdown渲染,这门语言甚至采用了`.mq.md`的双层嵌套后缀,所以不需要有压力使用这门语言,就算出现了巨大的问题,就当让ai写文档好了,如果成功了,试想这样一种场景,你不再需要让ai生成代码的文档,ai写的代码能够便捷的被你读懂,至少能省点token,毕竟烧了太多,钱包容易饿瘦。
|
||||
|
||||
这门语言还是起步阶段,目前计划是制作一个解释型的语言,现在的marqdo支持一些特定的语法结构和关键字,并且允许自由的输出调试信息,以及直接通过前端预览各个代码块,生成静态文件,是的,没错,这个网站就是marqdo制作的,至少我相信marqdo会成为一个博客工具。
|
||||
|
||||
除了部分内置的关键字,marqdo并不限制必须使用英文编程,当然这并不意味着我要开发一个中文编程系统,事实上,这是由于文档即代码、代码即文档的结构决定的,如果只支持英文,那还有什么作用?还要掌握一门语言,这并不是让人愉悦的阅读体验,所以marqdo会长期支持多语言编程的可能。
|
||||
|
||||
欢迎各位加入开源库,共同建设和完成这个项目[marqdo的github仓库链接](https://github.com/cflmy/marqdo)
|
||||
|
||||
最后,引用所有程序员的开始欢迎各位:
|
||||
|
||||
> 问候 marqdo
|
||||
|
||||
如果你是一个敏锐的程序员应该会察觉到一个小问题,这个问题的解决方案是像下面这样的,我其实并不知道这样解决是否正确,但是我暂且放在这里,欢迎你,敏锐的程序元朋友。
|
||||
|
||||
> 问候 谁=marqdo user
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=欢迎,`谁`!
|
||||
|
||||
---
|
||||
@@ -0,0 +1,26 @@
|
||||
# 用户文档(可执行 · 可下载)
|
||||
|
||||
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
|
||||
|
||||
| 路径 | 内容 |
|
||||
|------|------|
|
||||
| [`00-welcome.mq.md`](00-welcome.mq.md) | 首页 |
|
||||
| [`structure/`](structure/) | 基本结构 |
|
||||
| [`keywords/`](keywords/) | 关键字与内置 `print` |
|
||||
| [`features/`](features/) | 特性迭代说明 |
|
||||
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`,避免用户站出现红色执行失败。
|
||||
|
||||
开发文档(语言设计等)在 [`doc/`](../doc/),与本目录分离。
|
||||
|
||||
## 浏览与生成 HTML
|
||||
|
||||
```bash
|
||||
cargo run -- view public
|
||||
cargo run -- view output public -o public
|
||||
# 或
|
||||
./scripts/build-public.sh
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
生成的 `index.html` 与 `pages/` 默认被 ignore;CI 构建后推到 `gh-pages`。详见 [user-site.md](../doc/design/user-site.md)。
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Phase I — 树遍历解释器
|
||||
description: 词法 · 语法 · 语义 · 树遍历已贯通
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:Phase I(树遍历)。
|
||||
|
||||
流水线:加载 → 行分类 → 递归下降语法 → 语义检查 → 树遍历执行。实现不用 Flex/Bison。
|
||||
|
||||
本页本身即可运行,证明「文档即程序」在解释器里已落地:
|
||||
|
||||
> print text=Phase I:tree-walk interpreter is live.
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: 字节码后端
|
||||
description: --backend bytecode 与树遍历共用语义
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:字节码原型。
|
||||
|
||||
同一套 .mq.md 可用树遍历或字节码 VM 执行。命令示例:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
下面这段在两种后端下输出一致:
|
||||
|
||||
> print text=Bytecode backend:same program, alternate engine.
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: view 与用户文档站
|
||||
description: 本地浏览与静态导出由解释器生成
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:marqdo view 与 view output。
|
||||
|
||||
本地浏览:marqdo view public
|
||||
|
||||
静态导出:marqdo view output public -o public
|
||||
|
||||
用户可执行文档就在 public/;生成的 HTML(index.html / pages/)供静态托管,CI 发布到 gh-pages。
|
||||
|
||||
> print text=Docs site:generated by the Marqdo interpreter, not hand-written HTML.
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: 布尔与逻辑
|
||||
description: True / False / None 与 and / or / not
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
关键字:`True`、`False`、`None`,以及 `and` / `or` / `not`。
|
||||
|
||||
*`a` = True*
|
||||
*`b` = False*
|
||||
|
||||
+ `a` and not `b`
|
||||
> print text=ok
|
||||
+ *
|
||||
> print text=fail
|
||||
|
||||
*`probe` = 1*
|
||||
|
||||
+ None
|
||||
> print text=none-truthy
|
||||
+ *
|
||||
> print text=none-falsy
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 内置 print
|
||||
description: 具名与位置两种写法
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
内置 print 接受具名或位置实参:
|
||||
|
||||
> print text=named form
|
||||
|
||||
> print positional
|
||||
|
||||
这里的设计思路是具名实参允许空格的传入,位置实参则不允许。
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Hello World
|
||||
description: 最简单的可执行文档
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
普通段落是注释。print 是内置函数,不是语法架构。
|
||||
|
||||
注释里的粗体与斜体标记若出现在行首会被当成代码,所以叙述行请用普通文字开头。
|
||||
|
||||
> print text=Hello World!
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: 函数与具名调用
|
||||
description: `#` 定义函数,`>` 调用;`-` 下列纯名为形参
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
用 `#` / `##` 定义函数。形参写在函数头下方的 `-` 纯名行。
|
||||
|
||||
调用用 `>`:具名实参写作 `形参=值`。
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=Hello `谁`!
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: 位置实参
|
||||
description: 按形参顺序传参;也可继续用具名
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
位置实参:按形参声明顺序绑定,不必写 `谁=`。
|
||||
|
||||
> 问候 Marqdo
|
||||
|
||||
具名形式仍然可用:
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=Hello `谁`!
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: 分支
|
||||
description: `+` 臂;整行 `*` 为 else
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
斜体行是程序语句。分支用 `+`;臂头单独一行 `*` 表示 else。
|
||||
|
||||
*`x` = 0*
|
||||
|
||||
+ `x` > 0
|
||||
> print text=正数
|
||||
+ `x` < 0
|
||||
> print text=负数
|
||||
+ *
|
||||
> print text=零
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: 循环
|
||||
description: 条件循环与表格遍历
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
函数体内的 `-` 是循环(不是形参)。
|
||||
|
||||
倒数:
|
||||
|
||||
*`n` = 3*
|
||||
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*`n` = `n` - 1*
|
||||
|
||||
遍历篮子(表格是集合):
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
|
||||
- [果](篮子)
|
||||
> print text=今天吃`果`
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
title: 集合(表格)
|
||||
description: GFM 表格即集合
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Markdown 表格在 Marqdo 里就是集合,可用循环逐行取出。
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
|
||||
- [果](篮子)
|
||||
> print text=`果`
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: 跨文件导入
|
||||
description: frontmatter 中 `> 文件.mq.md` 导入模块
|
||||
> utils.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
文件头 YAML 里写 `> utils.mq.md` 即可导入同目录模块。
|
||||
|
||||
导入后:用返回值绑定,再输出;并直接调用问候。
|
||||
|
||||
*`y` = > 加一 n=41*
|
||||
|
||||
> print text=`y`
|
||||
|
||||
> 问候 谁=Marqdo
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 工具模块
|
||||
description: 被 main 导入;粗体是返回值
|
||||
---
|
||||
|
||||
# 加一
|
||||
- n
|
||||
|
||||
**`n` + 1**
|
||||
|
||||
# 问候
|
||||
- 谁
|
||||
|
||||
> print text=你好,`谁`!
|
||||
@@ -0,0 +1,6 @@
|
||||
# Generate HTML next to public/*.mq.md via the Marqdo interpreter.
|
||||
$ErrorActionPreference = "Stop"
|
||||
Set-Location (Split-Path $PSScriptRoot -Parent)
|
||||
cargo build --release -q
|
||||
& .\target\release\marqdo.exe view output public -o public
|
||||
Write-Host "OK → public/index.html + public/pages/ (sources: public/**/*.mq.md)"
|
||||
@@ -0,0 +1,7 @@
|
||||
#!/usr/bin/env bash
|
||||
# Generate HTML next to public/*.mq.md via the Marqdo interpreter.
|
||||
set -euo pipefail
|
||||
cd "$(dirname "$0")/.."
|
||||
cargo build --release -q
|
||||
./target/release/marqdo view output public -o public
|
||||
echo "OK → public/index.html + public/pages/ (sources: public/**/*.mq.md)"
|
||||
@@ -0,0 +1,149 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Create a GitHub release from Cargo.toml version and upload Windows binaries."""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import re
|
||||
import subprocess
|
||||
import urllib.error
|
||||
import urllib.request
|
||||
from pathlib import Path
|
||||
|
||||
REPO = "cflmy/marqdo"
|
||||
|
||||
|
||||
def crate_version() -> str:
|
||||
text = Path("Cargo.toml").read_text(encoding="utf-8")
|
||||
m = re.search(r'(?m)^version\s*=\s*"([^"]+)"', text)
|
||||
if not m:
|
||||
raise SystemExit("version not found in Cargo.toml")
|
||||
return m.group(1)
|
||||
|
||||
|
||||
def git_token() -> str:
|
||||
proc = subprocess.run(
|
||||
["git", "credential", "fill"],
|
||||
input="protocol=https\nhost=github.com\n\n",
|
||||
text=True,
|
||||
capture_output=True,
|
||||
check=True,
|
||||
)
|
||||
for line in proc.stdout.splitlines():
|
||||
if line.startswith("password="):
|
||||
return line[len("password=") :]
|
||||
raise SystemExit("no github password from git credential fill")
|
||||
|
||||
|
||||
def api(method: str, url: str, token: str, data: bytes | None = None, content_type: str | None = None):
|
||||
req = urllib.request.Request(url, data=data, method=method)
|
||||
req.add_header("Accept", "application/vnd.github+json")
|
||||
req.add_header("Authorization", f"Bearer {token}")
|
||||
req.add_header("X-GitHub-Api-Version", "2022-11-28")
|
||||
req.add_header("User-Agent", "marqdo-release-script")
|
||||
if content_type:
|
||||
req.add_header("Content-Type", content_type)
|
||||
try:
|
||||
with urllib.request.urlopen(req) as resp:
|
||||
body = resp.read()
|
||||
return resp.status, json.loads(body.decode()) if body else {}
|
||||
except urllib.error.HTTPError as e:
|
||||
err = e.read().decode("utf-8", errors="replace")
|
||||
raise SystemExit(f"HTTP {e.code} {url}: {err}") from e
|
||||
|
||||
|
||||
def main() -> None:
|
||||
ver = crate_version()
|
||||
tag = f"v{ver}"
|
||||
stem = f"marqdo-{ver}-x86_64-pc-windows-msvc"
|
||||
assets = [
|
||||
Path(f"target/dist/{stem}.exe"),
|
||||
Path(f"target/dist/{stem}.zip"),
|
||||
]
|
||||
for p in assets:
|
||||
if not p.exists():
|
||||
raise SystemExit(f"missing asset: {p}")
|
||||
|
||||
notes = f"""## Marqdo {tag}
|
||||
|
||||
### Highlights
|
||||
- Function body end via `---` / `***` or empty `****` return
|
||||
- Blank-line paragraph comments (lex + view rendering)
|
||||
- Brand logo / favicon from s3.cflmy.cn
|
||||
- Welcome docs and call-arg spaced named values
|
||||
|
||||
### Assets
|
||||
- `{stem}.exe` — Windows x64 binary
|
||||
- `{stem}.zip` — same binary zipped
|
||||
|
||||
```text
|
||||
marqdo --version
|
||||
marqdo run public/00-welcome.mq.md
|
||||
marqdo view public
|
||||
```
|
||||
"""
|
||||
|
||||
token = git_token()
|
||||
|
||||
existing = None
|
||||
try:
|
||||
_, existing = api(
|
||||
"GET",
|
||||
f"https://api.github.com/repos/{REPO}/releases/tags/{tag}",
|
||||
token,
|
||||
)
|
||||
except SystemExit as e:
|
||||
if "404" not in str(e):
|
||||
raise
|
||||
|
||||
if existing:
|
||||
release_id = existing["id"]
|
||||
upload_url = existing["upload_url"].split("{", 1)[0]
|
||||
print(f"reuse release id={release_id}")
|
||||
else:
|
||||
payload = json.dumps(
|
||||
{
|
||||
"tag_name": tag,
|
||||
"name": tag,
|
||||
"body": notes,
|
||||
"draft": False,
|
||||
"prerelease": False,
|
||||
}
|
||||
).encode("utf-8")
|
||||
_, created = api(
|
||||
"POST",
|
||||
f"https://api.github.com/repos/{REPO}/releases",
|
||||
token,
|
||||
data=payload,
|
||||
content_type="application/json",
|
||||
)
|
||||
release_id = created["id"]
|
||||
upload_url = created["upload_url"].split("{", 1)[0]
|
||||
print(f"created release id={release_id}")
|
||||
|
||||
_, rel = api(
|
||||
"GET",
|
||||
f"https://api.github.com/repos/{REPO}/releases/{release_id}",
|
||||
token,
|
||||
)
|
||||
want = {p.name for p in assets}
|
||||
for asset in rel.get("assets", []):
|
||||
if asset["name"] in want:
|
||||
api(
|
||||
"DELETE",
|
||||
f"https://api.github.com/repos/{REPO}/releases/assets/{asset['id']}",
|
||||
token,
|
||||
)
|
||||
print(f"deleted old asset {asset['name']}")
|
||||
|
||||
for path in assets:
|
||||
data = path.read_bytes()
|
||||
url = f"{upload_url}?name={path.name}"
|
||||
ctype = "application/zip" if path.suffix == ".zip" else "application/octet-stream"
|
||||
_, uploaded = api("POST", url, token, data=data, content_type=ctype)
|
||||
print(f"uploaded {path.name} -> {uploaded.get('browser_download_url')}")
|
||||
|
||||
print(f"OK https://github.com/{REPO}/releases/tag/{tag}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
+312
@@ -0,0 +1,312 @@
|
||||
//! OKF-compatible catalog generation: `marqdo catalog` / `sync`.
|
||||
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use anyhow::{Context, Result};
|
||||
|
||||
use crate::lex::{classify_source, LineKind};
|
||||
use crate::parse::parse_source;
|
||||
|
||||
pub struct CatalogOptions {
|
||||
pub path: PathBuf,
|
||||
pub out_dir: PathBuf,
|
||||
}
|
||||
|
||||
struct ModuleInfo {
|
||||
id: String,
|
||||
resource: String,
|
||||
title: String,
|
||||
imports: Vec<String>,
|
||||
exports: Vec<String>,
|
||||
}
|
||||
|
||||
pub fn write_catalog(opts: CatalogOptions) -> Result<()> {
|
||||
let root = if opts.path.is_file() {
|
||||
opts.path
|
||||
.parent()
|
||||
.map(|p| p.to_path_buf())
|
||||
.unwrap_or_else(|| PathBuf::from("."))
|
||||
} else {
|
||||
opts.path.clone()
|
||||
};
|
||||
let root = root.canonicalize().unwrap_or(root);
|
||||
|
||||
let mut files = Vec::new();
|
||||
if opts.path.is_file() {
|
||||
files.push(opts.path.canonicalize().unwrap_or(opts.path.clone()));
|
||||
} else {
|
||||
collect_mq_md(&root, &root, &mut files)?;
|
||||
files.sort();
|
||||
}
|
||||
|
||||
fs::create_dir_all(opts.out_dir.join("modules"))
|
||||
.with_context(|| format!("create {}", opts.out_dir.display()))?;
|
||||
|
||||
let version = env!("CARGO_PKG_VERSION");
|
||||
let mut modules = Vec::new();
|
||||
let mut had_err = false;
|
||||
|
||||
for abs in &files {
|
||||
let rel = abs
|
||||
.strip_prefix(&root)
|
||||
.unwrap_or(abs)
|
||||
.to_string_lossy()
|
||||
.replace('\\', "/");
|
||||
match inspect_file(abs, &rel) {
|
||||
Ok(info) => modules.push(info),
|
||||
Err(e) => {
|
||||
eprintln!("catalog: skip {rel}: {e:#}");
|
||||
had_err = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let catalog_yaml = render_catalog_yaml(&modules, version);
|
||||
fs::write(opts.out_dir.join("catalog.yaml"), catalog_yaml)?;
|
||||
|
||||
let index_md = render_index_md(&modules, version);
|
||||
fs::write(opts.out_dir.join("index.md"), index_md)?;
|
||||
|
||||
for m in &modules {
|
||||
let stem = m.resource.replace('/', "__").replace('\\', "__");
|
||||
let stem = stem.trim_end_matches(".mq.md");
|
||||
let path = opts.out_dir.join("modules").join(format!("{stem}.md"));
|
||||
fs::write(&path, render_module_md(m, version))?;
|
||||
}
|
||||
|
||||
eprintln!(
|
||||
"marqdo catalog: {} module(s) → {}",
|
||||
modules.len(),
|
||||
opts.out_dir.display()
|
||||
);
|
||||
if had_err {
|
||||
anyhow::bail!("catalog completed with errors");
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn collect_mq_md(root: &Path, dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
|
||||
for entry in fs::read_dir(dir)? {
|
||||
let entry = entry?;
|
||||
let p = entry.path();
|
||||
if p.is_dir() {
|
||||
collect_mq_md(root, &p, out)?;
|
||||
} else if p
|
||||
.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.map(|s| s.ends_with(".mq.md"))
|
||||
.unwrap_or(false)
|
||||
{
|
||||
out.push(p);
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn inspect_file(abs: &Path, rel: &str) -> Result<ModuleInfo> {
|
||||
let source = fs::read_to_string(abs)?;
|
||||
let imports = extract_frontmatter_imports(&source);
|
||||
let title = extract_frontmatter_title(&source)
|
||||
.unwrap_or_else(|| rel.trim_end_matches(".mq.md").to_string());
|
||||
|
||||
let mut exports = Vec::new();
|
||||
// Prefer parse for accurate top-level fn names
|
||||
match parse_source(&source) {
|
||||
Ok(module) => {
|
||||
for f in &module.functions {
|
||||
exports.push(f.name.clone());
|
||||
}
|
||||
}
|
||||
Err(_) => {
|
||||
for line in classify_source(&source) {
|
||||
if line.kind != LineKind::Code {
|
||||
continue;
|
||||
}
|
||||
let t = line.text.trim();
|
||||
if let Some(rest) = t.strip_prefix("# ") {
|
||||
if !rest.starts_with('#') {
|
||||
exports.push(rest.to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let id = rel.trim_end_matches(".mq.md").to_string();
|
||||
Ok(ModuleInfo {
|
||||
id,
|
||||
resource: rel.to_string(),
|
||||
title,
|
||||
imports,
|
||||
exports,
|
||||
})
|
||||
}
|
||||
|
||||
fn extract_frontmatter_imports(source: &str) -> Vec<String> {
|
||||
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
|
||||
let mut imports = Vec::new();
|
||||
let lines: Vec<&str> = source.lines().collect();
|
||||
if lines.first().map(|l| l.trim()) != Some("---") {
|
||||
return imports;
|
||||
}
|
||||
for line in lines.iter().skip(1) {
|
||||
let t = line.trim();
|
||||
if t == "---" {
|
||||
break;
|
||||
}
|
||||
if let Some(rest) = t.strip_prefix('>') {
|
||||
let path = rest.trim();
|
||||
if path.ends_with(".mq.md") {
|
||||
imports.push(path.to_string());
|
||||
}
|
||||
}
|
||||
}
|
||||
imports
|
||||
}
|
||||
|
||||
fn extract_frontmatter_title(source: &str) -> Option<String> {
|
||||
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
|
||||
let lines: Vec<&str> = source.lines().collect();
|
||||
if lines.first().map(|l| l.trim()) != Some("---") {
|
||||
return None;
|
||||
}
|
||||
for line in lines.iter().skip(1) {
|
||||
let t = line.trim();
|
||||
if t == "---" {
|
||||
break;
|
||||
}
|
||||
if let Some(v) = t.strip_prefix("title:") {
|
||||
return Some(v.trim().trim_matches('"').to_string());
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn yaml_escape(s: &str) -> String {
|
||||
if s.is_empty()
|
||||
|| s.contains(':')
|
||||
|| s.contains('#')
|
||||
|| s.contains('"')
|
||||
|| s.contains('\'')
|
||||
|| s.contains('\n')
|
||||
|| s.starts_with(' ')
|
||||
{
|
||||
format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
|
||||
} else {
|
||||
s.to_string()
|
||||
}
|
||||
}
|
||||
|
||||
fn render_catalog_yaml(modules: &[ModuleInfo], version: &str) -> String {
|
||||
let mut out = String::new();
|
||||
out.push_str("# GENERATED by marqdo — do not edit by hand\n");
|
||||
out.push_str("type: Marqdo Catalog\n");
|
||||
out.push_str("title: marqdo-project\n");
|
||||
out.push_str("generated:\n");
|
||||
out.push_str(&format!(" by: marqdo/{version}\n"));
|
||||
out.push_str("modules:\n");
|
||||
for m in modules {
|
||||
out.push_str(&format!(" - id: {}\n", yaml_escape(&m.id)));
|
||||
out.push_str(&format!(" resource: {}\n", yaml_escape(&m.resource)));
|
||||
out.push_str(&format!(" title: {}\n", yaml_escape(&m.title)));
|
||||
if m.imports.is_empty() {
|
||||
out.push_str(" imports: []\n");
|
||||
} else {
|
||||
out.push_str(" imports:\n");
|
||||
for i in &m.imports {
|
||||
out.push_str(&format!(" - {}\n", yaml_escape(i)));
|
||||
}
|
||||
}
|
||||
if m.exports.is_empty() {
|
||||
out.push_str(" exports: []\n");
|
||||
} else {
|
||||
out.push_str(" exports:\n");
|
||||
for e in &m.exports {
|
||||
out.push_str(&format!(" - name: {}\n", yaml_escape(e)));
|
||||
out.push_str(" kind: fn\n");
|
||||
}
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn render_index_md(modules: &[ModuleInfo], version: &str) -> String {
|
||||
let mut out = String::new();
|
||||
out.push_str("---\n");
|
||||
out.push_str("type: Marqdo Catalog\n");
|
||||
out.push_str("title: marqdo catalog\n");
|
||||
out.push_str("generated:\n");
|
||||
out.push_str(&format!(" by: marqdo/{version}\n"));
|
||||
out.push_str("---\n\n");
|
||||
out.push_str("# Catalog\n\n");
|
||||
out.push_str("> Generated by Marqdo. Do not edit by hand.\n\n");
|
||||
out.push_str("| Module | Resource | Imports |\n");
|
||||
out.push_str("|--------|----------|--------|\n");
|
||||
for m in modules {
|
||||
let stem = m.resource.replace('/', "__");
|
||||
let stem = stem.trim_end_matches(".mq.md");
|
||||
out.push_str(&format!(
|
||||
"| [{}](modules/{stem}.md) | `{}` | {} |\n",
|
||||
m.title,
|
||||
m.resource,
|
||||
if m.imports.is_empty() {
|
||||
"—".into()
|
||||
} else {
|
||||
m.imports.join(", ")
|
||||
}
|
||||
));
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn render_module_md(m: &ModuleInfo, version: &str) -> String {
|
||||
let mut out = String::new();
|
||||
out.push_str("---\n");
|
||||
out.push_str("type: Marqdo Module\n");
|
||||
out.push_str(&format!("title: {}\n", m.title));
|
||||
out.push_str(&format!("resource: {}\n", m.resource));
|
||||
if m.imports.is_empty() {
|
||||
out.push_str("depends: []\n");
|
||||
} else {
|
||||
out.push_str("depends:\n");
|
||||
for i in &m.imports {
|
||||
out.push_str(&format!(" - {i}\n"));
|
||||
}
|
||||
}
|
||||
if m.exports.is_empty() {
|
||||
out.push_str("exports: []\n");
|
||||
} else {
|
||||
out.push_str("exports:\n");
|
||||
for e in &m.exports {
|
||||
out.push_str(&format!(" - {e}\n"));
|
||||
}
|
||||
}
|
||||
out.push_str("generated:\n");
|
||||
out.push_str(&format!(" by: marqdo/{version}\n"));
|
||||
out.push_str("---\n\n");
|
||||
out.push_str(&format!("# {}\n\n", m.title));
|
||||
out.push_str(&format!(
|
||||
"> Auto-generated from [`{}`](../../{}). Do not edit by hand.\n\n",
|
||||
m.resource, m.resource
|
||||
));
|
||||
out.push_str("## Dependencies\n\n");
|
||||
if m.imports.is_empty() {
|
||||
out.push_str("_None_\n\n");
|
||||
} else {
|
||||
for i in &m.imports {
|
||||
out.push_str(&format!("- `{i}`\n"));
|
||||
}
|
||||
out.push('\n');
|
||||
}
|
||||
out.push_str("## Exports\n\n");
|
||||
if m.exports.is_empty() {
|
||||
out.push_str("_None_\n");
|
||||
} else {
|
||||
out.push_str("| Symbol | Kind |\n|--------|------|\n");
|
||||
for e in &m.exports {
|
||||
out.push_str(&format!("| `{e}` | fn |\n"));
|
||||
}
|
||||
}
|
||||
out
|
||||
}
|
||||
+51
-1
@@ -23,6 +23,24 @@ impl fmt::Display for Span {
|
||||
}
|
||||
}
|
||||
|
||||
/// Format a path for user-facing diagnostics.
|
||||
///
|
||||
/// Strips the Windows extended-length prefix (`\\?\` / `\\?\UNC\`) that
|
||||
/// `canonicalize` often adds, so messages stay readable.
|
||||
pub fn display_path(path: &Path) -> String {
|
||||
let raw = path.display().to_string();
|
||||
if let Some(rest) = raw.strip_prefix(r"\\?\UNC\") {
|
||||
format!(r"\\{rest}")
|
||||
} else if let Some(rest) = raw.strip_prefix(r"\\?\") {
|
||||
rest.to_string()
|
||||
} else if let Some(rest) = raw.strip_prefix("//?/") {
|
||||
// Some tools emit forward-slash forms
|
||||
rest.to_string()
|
||||
} else {
|
||||
raw
|
||||
}
|
||||
}
|
||||
|
||||
/// Unified diagnostic: `path:line:col: message` (path omitted if unknown).
|
||||
#[derive(Debug, Error, Clone)]
|
||||
#[error("{}", self.format_message())]
|
||||
@@ -47,7 +65,7 @@ impl Diagnostic {
|
||||
|
||||
pub fn format_message(&self) -> String {
|
||||
match &self.path {
|
||||
Some(p) => format!("{}:{}: {}", p.display(), self.span, self.message),
|
||||
Some(p) => format!("{}:{}: {}", display_path(p), self.span, self.message),
|
||||
None => format!("{}: {}", self.span, self.message),
|
||||
}
|
||||
}
|
||||
@@ -57,3 +75,35 @@ impl Diagnostic {
|
||||
pub fn bail_at(path: Option<&Path>, span: Span, message: impl Into<String>) -> anyhow::Error {
|
||||
anyhow::Error::new(Diagnostic::new(path, span, message))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn strips_windows_extended_prefix() {
|
||||
let p = PathBuf::from(r"\\?\E:\marqdo\examples\errors\bad-arity.mq.md");
|
||||
assert_eq!(
|
||||
display_path(&p),
|
||||
r"E:\marqdo\examples\errors\bad-arity.mq.md"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn strips_unc_extended_prefix() {
|
||||
let p = PathBuf::from(r"\\?\UNC\server\share\file.mq.md");
|
||||
assert_eq!(display_path(&p), r"\\server\share\file.mq.md");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn diagnostic_message_uses_clean_path() {
|
||||
let d = Diagnostic::at(
|
||||
Path::new(r"\\?\E:\marqdo\x.mq.md"),
|
||||
Span::new(7, 1),
|
||||
"missing argument for parameter `x`",
|
||||
);
|
||||
let msg = d.format_message();
|
||||
assert!(!msg.contains(r"\\?\"));
|
||||
assert!(msg.contains(r"E:\marqdo\x.mq.md:7:1:"));
|
||||
}
|
||||
}
|
||||
+71
-12
@@ -1,7 +1,8 @@
|
||||
//! Line classification (M1) — no Flex.
|
||||
//!
|
||||
//! Unmarked lines are comments; lines whose first non-whitespace character
|
||||
//! opens a Marqdo/Markdown marker are code.
|
||||
//! Narrative comments are paragraph-scoped: blank lines separate paragraphs.
|
||||
//! After a comment line, subsequent non-blank lines stay comments until a blank
|
||||
//! (so mid-paragraph lines starting with `` ` `` are not treated as code).
|
||||
|
||||
use std::fmt;
|
||||
|
||||
@@ -40,6 +41,9 @@ fn is_code_starter(c: char) -> bool {
|
||||
}
|
||||
|
||||
/// Classify a single logical line (no trailing newline required).
|
||||
///
|
||||
/// This is the **paragraph-start** rule only. Prefer [`classify_source`] for
|
||||
/// full-file classification (paragraph continuation).
|
||||
pub fn classify_line(text: &str) -> LineKind {
|
||||
let trimmed = text.trim_end_matches(['\r', '\n']);
|
||||
if trimmed.chars().all(|c| c.is_whitespace()) {
|
||||
@@ -53,7 +57,11 @@ pub fn classify_line(text: &str) -> LineKind {
|
||||
}
|
||||
}
|
||||
|
||||
/// Classify every line of a source file.
|
||||
/// Classify every line of a source file (blank-line paragraph comments).
|
||||
///
|
||||
/// Structural end markers (`---` / `***` / empty `****`) always stay Code and
|
||||
/// break a comment paragraph, so frontmatter closers and function ends work
|
||||
/// even when adjacent to narrative.
|
||||
pub fn classify_source(source: &str) -> Vec<ClassifiedLine> {
|
||||
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
|
||||
let lines: Vec<&str> = if source.is_empty() {
|
||||
@@ -62,15 +70,46 @@ pub fn classify_source(source: &str) -> Vec<ClassifiedLine> {
|
||||
source.lines().collect()
|
||||
};
|
||||
|
||||
lines
|
||||
.into_iter()
|
||||
.enumerate()
|
||||
.map(|(i, text)| ClassifiedLine {
|
||||
let mut out = Vec::with_capacity(lines.len());
|
||||
let mut in_comment_paragraph = false;
|
||||
|
||||
for (i, text) in lines.into_iter().enumerate() {
|
||||
let base = classify_line(text);
|
||||
let trimmed = text.trim();
|
||||
let structural = is_structural_code_line(trimmed);
|
||||
let kind = match base {
|
||||
LineKind::Blank => {
|
||||
in_comment_paragraph = false;
|
||||
LineKind::Blank
|
||||
}
|
||||
LineKind::Comment => {
|
||||
in_comment_paragraph = true;
|
||||
LineKind::Comment
|
||||
}
|
||||
LineKind::Code if structural => {
|
||||
in_comment_paragraph = false;
|
||||
LineKind::Code
|
||||
}
|
||||
LineKind::Code if in_comment_paragraph => LineKind::Comment,
|
||||
LineKind::Code => LineKind::Code,
|
||||
};
|
||||
out.push(ClassifiedLine {
|
||||
line_no: (i + 1) as u32,
|
||||
kind: classify_line(text),
|
||||
kind,
|
||||
text: text.to_string(),
|
||||
})
|
||||
.collect()
|
||||
});
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
/// Function-end / frontmatter HR or empty bold return — never swallowed by paragraphs.
|
||||
fn is_structural_code_line(trimmed: &str) -> bool {
|
||||
if trimmed.len() >= 3
|
||||
&& (trimmed.chars().all(|c| c == '-') || trimmed.chars().all(|c| c == '*'))
|
||||
{
|
||||
return true;
|
||||
}
|
||||
false
|
||||
}
|
||||
|
||||
/// Human-readable dump for `--dump-lines`.
|
||||
@@ -121,10 +160,30 @@ mod tests {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn paragraph_comment_keeps_backtick_continuation() {
|
||||
let src = "采用了\n`.mq.md`的双层后缀\n\n> print text=ok\n";
|
||||
let lines = classify_source(src);
|
||||
assert_eq!(lines[0].kind, LineKind::Comment);
|
||||
assert_eq!(lines[1].kind, LineKind::Comment);
|
||||
assert_eq!(lines[2].kind, LineKind::Blank);
|
||||
assert_eq!(lines[3].kind, LineKind::Code);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn frontmatter_closing_hr_stays_code() {
|
||||
let src = "---\ntitle: x\n---\n\n# main\n";
|
||||
let lines = classify_source(src);
|
||||
assert_eq!(lines[0].kind, LineKind::Code);
|
||||
assert_eq!(lines[1].kind, LineKind::Comment);
|
||||
assert_eq!(lines[2].kind, LineKind::Code);
|
||||
assert_eq!(lines[2].text.trim(), "---");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn classify_hello_fixture() {
|
||||
let src = include_str!("../../examples/structure/hello.mq.md");
|
||||
let src = include_str!("../../tests/structure/hello.mq.md");
|
||||
let lines = classify_source(src);
|
||||
assert!(lines.iter().any(|l| l.kind == LineKind::Code && l.text.contains("print")));
|
||||
assert!(lines.iter().any(|l| l.kind == LineKind::Comment));
|
||||
assert!(lines.iter().any(|l| l.kind == LineKind::Code));
|
||||
}
|
||||
}
|
||||
@@ -6,6 +6,7 @@
|
||||
pub mod ast;
|
||||
pub mod bytecode;
|
||||
pub mod capture;
|
||||
pub mod catalog;
|
||||
pub mod debug;
|
||||
pub mod diagnostics;
|
||||
pub mod interp;
|
||||
|
||||
+73
-13
@@ -4,11 +4,12 @@ use std::process::ExitCode;
|
||||
use anyhow::Result;
|
||||
use clap::{Parser, Subcommand, ValueEnum};
|
||||
|
||||
use marqdo::view::{serve, ViewOptions};
|
||||
use marqdo::catalog::{write_catalog, CatalogOptions};
|
||||
use marqdo::view::{serve, write_static, OutputOptions, ViewOptions};
|
||||
use marqdo::{Backend, RunOptions};
|
||||
|
||||
#[derive(Parser, Debug)]
|
||||
#[command(name = "marqdo", version, about = "Marqdo interpreter — run and view .mq.md programs")]
|
||||
#[command(name = "marqdo", version, about = "Marqdo interpreter — run, view, and catalog .mq.md")]
|
||||
struct Cli {
|
||||
#[command(subcommand)]
|
||||
command: Commands,
|
||||
@@ -54,19 +55,54 @@ enum Commands {
|
||||
#[arg(long)]
|
||||
dump_all: bool,
|
||||
},
|
||||
/// Browse `.mq.md` structure + execution in a local webpage
|
||||
/// Browse `.mq.md` structure + execution (live server or static output)
|
||||
View {
|
||||
#[command(subcommand)]
|
||||
action: Option<ViewAction>,
|
||||
|
||||
/// Path when running the live server (default: `.`)
|
||||
#[arg(value_name = "PATH", global = true)]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(long, default_value = "127.0.0.1", global = true)]
|
||||
host: String,
|
||||
|
||||
#[arg(long, default_value_t = 7429, global = true)]
|
||||
port: u16,
|
||||
|
||||
#[arg(long, global = true)]
|
||||
no_open: bool,
|
||||
},
|
||||
/// Generate OKF-compatible catalog YAML + module pages
|
||||
Catalog {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(long, default_value = "127.0.0.1")]
|
||||
host: String,
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
},
|
||||
/// Alias for `catalog`
|
||||
Sync {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(long, default_value_t = 7429)]
|
||||
port: u16,
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
},
|
||||
}
|
||||
|
||||
#[derive(Subcommand, Debug)]
|
||||
enum ViewAction {
|
||||
/// Write static HTML documentation site
|
||||
Output {
|
||||
#[arg(value_name = "PATH")]
|
||||
path: Option<PathBuf>,
|
||||
|
||||
#[arg(short = 'o', long = "out", required = true)]
|
||||
out: PathBuf,
|
||||
|
||||
#[arg(long)]
|
||||
no_open: bool,
|
||||
no_exec: bool,
|
||||
},
|
||||
}
|
||||
|
||||
@@ -115,16 +151,40 @@ fn try_main() -> Result<i32> {
|
||||
Ok(0)
|
||||
}
|
||||
Commands::View {
|
||||
action,
|
||||
path,
|
||||
host,
|
||||
port,
|
||||
no_open,
|
||||
} => {
|
||||
serve(ViewOptions {
|
||||
} => match action {
|
||||
Some(ViewAction::Output {
|
||||
path: out_path,
|
||||
out,
|
||||
no_exec,
|
||||
}) => {
|
||||
write_static(OutputOptions {
|
||||
path: out_path
|
||||
.or(path)
|
||||
.unwrap_or_else(|| PathBuf::from(".")),
|
||||
out_dir: out,
|
||||
no_exec,
|
||||
})?;
|
||||
Ok(0)
|
||||
}
|
||||
None => {
|
||||
serve(ViewOptions {
|
||||
path: path.unwrap_or_else(|| PathBuf::from(".")),
|
||||
host,
|
||||
port,
|
||||
open_browser: !no_open,
|
||||
})?;
|
||||
Ok(0)
|
||||
}
|
||||
},
|
||||
Commands::Catalog { path, out } | Commands::Sync { path, out } => {
|
||||
write_catalog(CatalogOptions {
|
||||
path: path.unwrap_or_else(|| PathBuf::from(".")),
|
||||
host,
|
||||
port,
|
||||
open_browser: !no_open,
|
||||
out_dir: out,
|
||||
})?;
|
||||
Ok(0)
|
||||
}
|
||||
|
||||
+38
-7
@@ -144,14 +144,29 @@ impl<'a> Cursor<'a> {
|
||||
break;
|
||||
}
|
||||
|
||||
// Body until next heading at level <= ours.
|
||||
// Body until next heading at level <= ours, or explicit end (--- / *** / empty **).
|
||||
while self.skip_noise() {
|
||||
let Some(l) = self.peek() else { break };
|
||||
let trimmed = l.text.trim();
|
||||
|
||||
// Empty bold return ends the function body.
|
||||
if is_empty_bold_return(trimmed) {
|
||||
let span = Span {
|
||||
line: l.line_no,
|
||||
col: 1,
|
||||
};
|
||||
self.bump();
|
||||
fun.body.push(Stmt::Return {
|
||||
value: Expr::Literal(Literal::None),
|
||||
span,
|
||||
});
|
||||
break;
|
||||
}
|
||||
|
||||
// --- / *** at function body top level ends the function (no return).
|
||||
if is_frame(trimmed) {
|
||||
self.bump();
|
||||
continue;
|
||||
break;
|
||||
}
|
||||
|
||||
if is_heading(trimmed) {
|
||||
@@ -191,10 +206,14 @@ impl<'a> Cursor<'a> {
|
||||
bail!("{span}: unexpected frame line as statement");
|
||||
}
|
||||
|
||||
// Bold return **…**
|
||||
// Bold return **…** (empty inner → None)
|
||||
if trimmed.starts_with("**") && trimmed.ends_with("**") && trimmed.len() >= 4 {
|
||||
let inner = &trimmed[2..trimmed.len() - 2];
|
||||
let value = parse_expr_str(inner)?;
|
||||
let value = if inner.trim().is_empty() {
|
||||
Expr::Literal(Literal::None)
|
||||
} else {
|
||||
parse_expr_str(inner)?
|
||||
};
|
||||
return Ok(Stmt::Return { value, span });
|
||||
}
|
||||
|
||||
@@ -481,9 +500,21 @@ fn is_frame(trimmed: &str) -> bool {
|
||||
if trimmed.len() < 3 {
|
||||
return false;
|
||||
}
|
||||
// Empty bold return `****` is handled separately; frames are --- or *** (etc.).
|
||||
if is_empty_bold_return(trimmed) {
|
||||
return false;
|
||||
}
|
||||
trimmed.chars().all(|c| c == '-') || trimmed.chars().all(|c| c == '*')
|
||||
}
|
||||
|
||||
/// `****` or `**` + whitespace only + `**`.
|
||||
fn is_empty_bold_return(trimmed: &str) -> bool {
|
||||
if !(trimmed.starts_with("**") && trimmed.ends_with("**") && trimmed.len() >= 4) {
|
||||
return false;
|
||||
}
|
||||
trimmed[2..trimmed.len() - 2].trim().is_empty()
|
||||
}
|
||||
|
||||
fn is_ordered_branch(trimmed: &str) -> bool {
|
||||
strip_ordered(trimmed).is_some()
|
||||
}
|
||||
@@ -525,7 +556,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn parse_hello() {
|
||||
let src = include_str!("../../examples/structure/hello.mq.md");
|
||||
let src = include_str!("../../tests/structure/hello.mq.md");
|
||||
let m = parse_source(src).unwrap();
|
||||
assert_eq!(m.functions.len(), 1);
|
||||
assert_eq!(m.functions[0].name, "Hello World");
|
||||
@@ -535,7 +566,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn parse_index() {
|
||||
let src = include_str!("../../examples/structure/nested-call.mq.md");
|
||||
let src = include_str!("../../tests/structure/nested-call.mq.md");
|
||||
let m = parse_source(src).unwrap();
|
||||
assert!(m.imports.is_empty());
|
||||
let main = m.functions.iter().find(|f| f.name == "main").unwrap();
|
||||
@@ -546,7 +577,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn parse_branch() {
|
||||
let src = include_str!("../../examples/structure/branch.mq.md");
|
||||
let src = include_str!("../../tests/structure/branch.mq.md");
|
||||
let m = parse_source(src).unwrap();
|
||||
let main = &m.functions[0];
|
||||
assert!(main.body.iter().any(|s| matches!(s, Stmt::Branch { .. })));
|
||||
|
||||
+462
-206
@@ -1,6 +1,6 @@
|
||||
//! HTML shell for `marqdo view`.
|
||||
//! HTML shell for `marqdo view` — Apple-inspired monochrome, system fonts only.
|
||||
|
||||
use std::path::Path;
|
||||
use std::path::{Component, Path, PathBuf};
|
||||
|
||||
use crate::view::render::FileViewModel;
|
||||
|
||||
@@ -17,6 +17,358 @@ pub fn escape(s: &str) -> String {
|
||||
.collect()
|
||||
}
|
||||
|
||||
/// How navigation hrefs are built.
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum LinkMode {
|
||||
/// Live server: `/file?path=…`
|
||||
Live,
|
||||
/// Static export: relative links under `pages/`.
|
||||
/// `from` is the source rel path of the current page (`None` = index.html).
|
||||
Static { from: Option<String> },
|
||||
}
|
||||
|
||||
fn stylesheet() -> &'static str {
|
||||
// Inspired by Apple HIG clarity + docs-site layouts (sticky sidebar, readable
|
||||
// center column, system grays). Monochrome only; no remote fonts.
|
||||
r#"
|
||||
:root {
|
||||
--bg: #f5f5f7;
|
||||
--surface: #ffffff;
|
||||
--ink: #1d1d1f;
|
||||
--muted: #6e6e73;
|
||||
--line: #d2d2d7;
|
||||
--line-strong: #1d1d1f;
|
||||
--fill: #f5f5f7;
|
||||
--hover: #e8e8ed;
|
||||
--focus: #0071e3;
|
||||
--fail-bg: #fff5f5;
|
||||
--ok-bg: #f5f5f7;
|
||||
--radius: 12px;
|
||||
--mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
|
||||
--sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
html { scroll-behavior: smooth; }
|
||||
body {
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
font-family: var(--sans);
|
||||
color: var(--ink);
|
||||
background: var(--bg);
|
||||
line-height: 1.47;
|
||||
font-size: 17px;
|
||||
-webkit-font-smoothing: antialiased;
|
||||
text-rendering: optimizeLegibility;
|
||||
}
|
||||
a { color: var(--ink); text-decoration: none; }
|
||||
a:hover { opacity: 0.72; }
|
||||
a:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }
|
||||
#nav-toggle { position: absolute; opacity: 0; pointer-events: none; }
|
||||
.topbar {
|
||||
display: none;
|
||||
align-items: center;
|
||||
gap: 0.75rem;
|
||||
padding: 0.7rem 1rem;
|
||||
border-bottom: 1px solid var(--line);
|
||||
background: rgba(255,255,255,0.86);
|
||||
backdrop-filter: saturate(180%) blur(16px);
|
||||
-webkit-backdrop-filter: saturate(180%) blur(16px);
|
||||
position: sticky;
|
||||
top: 0;
|
||||
z-index: 20;
|
||||
}
|
||||
.topbar .brand { margin: 0; font-size: 1.05rem; font-weight: 600; letter-spacing: -0.022em; }
|
||||
.brand-row {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.55rem;
|
||||
}
|
||||
.brand-row .brand { margin: 0; }
|
||||
.logo {
|
||||
width: 1.75rem;
|
||||
height: 1.75rem;
|
||||
object-fit: contain;
|
||||
flex-shrink: 0;
|
||||
border-radius: 6px;
|
||||
}
|
||||
.topbar .logo { width: 1.45rem; height: 1.45rem; }
|
||||
.nav-brand .logo { width: 2rem; height: 2rem; }
|
||||
.nav-btn {
|
||||
appearance: none;
|
||||
border: 1px solid var(--line);
|
||||
background: var(--surface);
|
||||
color: var(--ink);
|
||||
border-radius: 10px;
|
||||
width: 2.35rem;
|
||||
height: 2.35rem;
|
||||
font-size: 1.05rem;
|
||||
line-height: 1;
|
||||
cursor: pointer;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
transition: background 0.15s ease, border-color 0.15s ease;
|
||||
}
|
||||
.nav-btn:hover { background: var(--hover); }
|
||||
.shell {
|
||||
display: grid;
|
||||
grid-template-columns: 280px minmax(0, 1fr);
|
||||
min-height: 100vh;
|
||||
max-width: 1400px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
.nav {
|
||||
border-right: 1px solid var(--line);
|
||||
padding: 1.75rem 1rem 2.5rem 1.15rem;
|
||||
overflow: auto;
|
||||
background: var(--bg);
|
||||
position: sticky;
|
||||
top: 0;
|
||||
align-self: start;
|
||||
height: 100vh;
|
||||
}
|
||||
.nav-brand { display: block; padding: 0 0.35rem; margin-bottom: 1.15rem; }
|
||||
.nav-brand .tagline { margin: 0.1rem 0 0; }
|
||||
.brand {
|
||||
font-size: 1.35rem;
|
||||
font-weight: 700;
|
||||
letter-spacing: -0.03em;
|
||||
margin: 0 0 0.1rem;
|
||||
}
|
||||
.tagline {
|
||||
color: var(--muted);
|
||||
font-size: 0.78rem;
|
||||
margin: 0;
|
||||
font-weight: 500;
|
||||
}
|
||||
.nav > h2:first-of-type { margin-top: 0.35rem; }
|
||||
.nav h2 {
|
||||
font-size: 0.68rem;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.09em;
|
||||
color: var(--muted);
|
||||
font-weight: 600;
|
||||
margin: 1.15rem 0.35rem 0.45rem;
|
||||
}
|
||||
.nav ul { list-style: none; padding: 0; margin: 0; }
|
||||
.nav li { margin: 0.08rem 0; }
|
||||
.nav a.file {
|
||||
display: block;
|
||||
padding: 0.42rem 0.65rem;
|
||||
border-radius: 8px;
|
||||
border-bottom: none;
|
||||
color: var(--ink);
|
||||
font-family: var(--mono);
|
||||
font-size: 0.78rem;
|
||||
transition: background 0.12s ease, color 0.12s ease;
|
||||
}
|
||||
.nav a.file:hover { background: var(--hover); opacity: 1; }
|
||||
.nav a.file.active {
|
||||
background: var(--ink);
|
||||
color: #fff;
|
||||
opacity: 1;
|
||||
font-weight: 500;
|
||||
}
|
||||
.folder {
|
||||
color: var(--muted);
|
||||
font-size: 0.72rem;
|
||||
margin: 1rem 0.35rem 0.35rem;
|
||||
font-weight: 600;
|
||||
letter-spacing: 0.01em;
|
||||
}
|
||||
.panel-wrap {
|
||||
min-width: 0;
|
||||
overflow: auto;
|
||||
background: var(--bg);
|
||||
}
|
||||
main.panel {
|
||||
padding: 2.25rem 2.5rem 4rem;
|
||||
margin: 0 auto;
|
||||
width: 100%;
|
||||
max-width: 58rem;
|
||||
}
|
||||
h1.page {
|
||||
font-size: clamp(1.75rem, 2.4vw, 2.35rem);
|
||||
font-weight: 700;
|
||||
letter-spacing: -0.035em;
|
||||
margin: 0 0 0.3rem;
|
||||
line-height: 1.15;
|
||||
}
|
||||
.meta {
|
||||
color: var(--muted);
|
||||
font-size: 0.88rem;
|
||||
margin: 0 0 1.75rem;
|
||||
font-family: var(--mono);
|
||||
}
|
||||
.status-pill {
|
||||
display: inline-block;
|
||||
font-size: 0.68rem;
|
||||
font-weight: 600;
|
||||
letter-spacing: 0.04em;
|
||||
text-transform: uppercase;
|
||||
padding: 0.18rem 0.5rem;
|
||||
border-radius: 999px;
|
||||
border: 1px solid var(--line);
|
||||
margin-left: 0.5rem;
|
||||
vertical-align: middle;
|
||||
}
|
||||
.status-pill.ok { background: var(--surface); color: var(--muted); }
|
||||
.status-pill.fail { background: var(--ink); color: #fff; border-color: var(--ink); }
|
||||
section.block { margin: 2rem 0; }
|
||||
section.block > h2 {
|
||||
font-size: 0.72rem;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.08em;
|
||||
color: var(--muted);
|
||||
font-weight: 600;
|
||||
margin: 0 0 0.85rem;
|
||||
}
|
||||
.structure {
|
||||
background: var(--surface);
|
||||
border: 1px solid var(--line);
|
||||
border-radius: var(--radius);
|
||||
padding: 0.35rem 0.15rem;
|
||||
box-shadow: 0 1px 0 rgba(0,0,0,0.02);
|
||||
}
|
||||
.card {
|
||||
border: none;
|
||||
border-bottom: 1px solid var(--line);
|
||||
border-radius: 0;
|
||||
padding: 0.85rem 1.1rem;
|
||||
margin: 0;
|
||||
background: transparent;
|
||||
}
|
||||
.card:last-child { border-bottom: none; }
|
||||
.fun-card, .call-card, .branch-card, .loop-card, .ret-card {
|
||||
border-left: 2px solid var(--line-strong);
|
||||
padding-left: calc(1.1rem - 2px);
|
||||
}
|
||||
.comment-card {
|
||||
border-left: 2px solid var(--line);
|
||||
background: transparent;
|
||||
padding-left: calc(1.1rem - 2px);
|
||||
}
|
||||
.badge {
|
||||
display: inline-block;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.66rem;
|
||||
padding: 0.14rem 0.4rem;
|
||||
border-radius: 6px;
|
||||
border: 1px solid var(--line);
|
||||
background: var(--fill);
|
||||
color: var(--ink);
|
||||
margin-right: 0.4rem;
|
||||
font-weight: 600;
|
||||
letter-spacing: 0.02em;
|
||||
}
|
||||
.params { margin: 0.35rem 0 0; }
|
||||
.chip {
|
||||
display: inline-block;
|
||||
font-family: var(--mono);
|
||||
font-size: 0.72rem;
|
||||
padding: 0.14rem 0.45rem;
|
||||
margin: 0.15rem 0.15rem 0 0;
|
||||
border-radius: 6px;
|
||||
background: var(--fill);
|
||||
border: 1px solid transparent;
|
||||
color: var(--ink);
|
||||
}
|
||||
.nested {
|
||||
margin: 0.45rem 0 0.15rem 0.15rem;
|
||||
padding-left: 0.85rem;
|
||||
border-left: 1px solid var(--line);
|
||||
}
|
||||
.arm {
|
||||
margin: 0.4rem 0;
|
||||
padding: 0.55rem 0.7rem;
|
||||
background: var(--fill);
|
||||
border-radius: 10px;
|
||||
border: 1px solid transparent;
|
||||
}
|
||||
.out, .source {
|
||||
font-family: var(--mono);
|
||||
font-size: 0.82rem;
|
||||
white-space: pre-wrap;
|
||||
background: var(--surface);
|
||||
border-radius: var(--radius);
|
||||
padding: 1rem 1.15rem;
|
||||
border: 1px solid var(--line);
|
||||
line-height: 1.55;
|
||||
box-shadow: 0 1px 0 rgba(0,0,0,0.02);
|
||||
}
|
||||
.out.ok { background: var(--ok-bg); }
|
||||
.out.fail {
|
||||
background: var(--fail-bg);
|
||||
border-color: #e4c1c1;
|
||||
color: var(--ink);
|
||||
font-weight: 500;
|
||||
}
|
||||
.comment-text {
|
||||
color: var(--muted);
|
||||
font-size: 0.92rem;
|
||||
display: block;
|
||||
margin-top: 0.35rem;
|
||||
white-space: pre-line;
|
||||
line-height: 1.55;
|
||||
max-width: 42em;
|
||||
}
|
||||
code.expr {
|
||||
font-family: var(--mono);
|
||||
font-size: 0.84rem;
|
||||
color: var(--ink);
|
||||
}
|
||||
.err { color: var(--ink); font-weight: 600; padding: 0.75rem 1rem; }
|
||||
.welcome {
|
||||
max-width: 40rem;
|
||||
margin: 4rem auto;
|
||||
text-align: center;
|
||||
}
|
||||
.welcome p { color: var(--muted); font-size: 1.05rem; }
|
||||
.backdrop {
|
||||
display: none;
|
||||
position: fixed;
|
||||
inset: 0;
|
||||
background: rgba(0,0,0,0.28);
|
||||
z-index: 25;
|
||||
animation: fade-in 0.18s ease;
|
||||
}
|
||||
@keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
|
||||
@media (max-width: 900px) {
|
||||
.shell { grid-template-columns: 240px minmax(0, 1fr); }
|
||||
main.panel { max-width: 48rem; padding: 1.75rem 1.5rem 3rem; }
|
||||
}
|
||||
@media (max-width: 800px) {
|
||||
.topbar { display: flex; }
|
||||
.nav-brand { display: none; }
|
||||
.shell {
|
||||
grid-template-columns: 1fr;
|
||||
max-width: none;
|
||||
min-height: calc(100vh - 3.25rem);
|
||||
}
|
||||
.nav {
|
||||
position: fixed;
|
||||
top: 0;
|
||||
left: 0;
|
||||
bottom: 0;
|
||||
width: min(82vw, 300px);
|
||||
height: 100vh;
|
||||
z-index: 30;
|
||||
transform: translateX(-105%);
|
||||
transition: transform 0.22s cubic-bezier(0.2, 0.8, 0.2, 1);
|
||||
border-right: 1px solid var(--line);
|
||||
background: var(--surface);
|
||||
box-shadow: 8px 0 32px rgba(0,0,0,0.08);
|
||||
}
|
||||
#nav-toggle:checked ~ .shell .nav { transform: translateX(0); }
|
||||
#nav-toggle:checked ~ .backdrop { display: block; }
|
||||
main.panel {
|
||||
max-width: none;
|
||||
padding: 1.4rem 1.15rem 3rem;
|
||||
}
|
||||
}
|
||||
"#
|
||||
}
|
||||
|
||||
pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
format!(
|
||||
r##"<!DOCTYPE html>
|
||||
@@ -24,209 +376,52 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String {
|
||||
<head>
|
||||
<meta charset="utf-8"/>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||||
<title>{title} · marqdo view</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com"/>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,700&family=IBM+Plex+Mono:wght@400;500&family=Sora:wght@400;600&display=swap" rel="stylesheet"/>
|
||||
<style>
|
||||
:root {{
|
||||
--bg0: #0f1c1a;
|
||||
--bg1: #162824;
|
||||
--panel: #1c322d;
|
||||
--ink: #e7f2ee;
|
||||
--muted: #9bb5ac;
|
||||
--accent: #3ecf8e;
|
||||
--accent-dim: #2a9b6a;
|
||||
--call: #5ec8ff;
|
||||
--branch: #f0b429;
|
||||
--loop: #ff7a59;
|
||||
--ret: #c4a7ff;
|
||||
--err: #ff6b6b;
|
||||
--line: rgba(255,255,255,0.08);
|
||||
}}
|
||||
* {{ box-sizing: border-box; }}
|
||||
body {{
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
font-family: "Sora", system-ui, sans-serif;
|
||||
color: var(--ink);
|
||||
background:
|
||||
radial-gradient(1200px 600px at 10% -10%, #1a3d34 0%, transparent 55%),
|
||||
radial-gradient(900px 500px at 100% 0%, #243528 0%, transparent 50%),
|
||||
linear-gradient(165deg, var(--bg0), var(--bg1));
|
||||
}}
|
||||
a {{ color: var(--accent); text-decoration: none; }}
|
||||
a:hover {{ text-decoration: underline; }}
|
||||
.shell {{
|
||||
display: grid;
|
||||
grid-template-columns: minmax(220px, 280px) 1fr;
|
||||
min-height: 100vh;
|
||||
}}
|
||||
@media (max-width: 800px) {{
|
||||
.shell {{ grid-template-columns: 1fr; }}
|
||||
}}
|
||||
.nav {{
|
||||
border-right: 1px solid var(--line);
|
||||
background: rgba(0,0,0,0.22);
|
||||
padding: 1.25rem 1rem 2rem;
|
||||
overflow: auto;
|
||||
}}
|
||||
.brand {{
|
||||
font-family: "Fraunces", Georgia, serif;
|
||||
font-size: 1.45rem;
|
||||
font-weight: 700;
|
||||
letter-spacing: -0.02em;
|
||||
margin: 0 0 0.25rem;
|
||||
}}
|
||||
.brand span {{ color: var(--accent); }}
|
||||
.tagline {{
|
||||
color: var(--muted);
|
||||
font-size: 0.8rem;
|
||||
margin: 0 0 1.25rem;
|
||||
}}
|
||||
.nav h2 {{
|
||||
font-size: 0.7rem;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.12em;
|
||||
color: var(--muted);
|
||||
margin: 1rem 0 0.4rem;
|
||||
}}
|
||||
.nav ul {{ list-style: none; padding: 0; margin: 0; }}
|
||||
.nav li {{ margin: 0.15rem 0; }}
|
||||
.nav a.file {{
|
||||
display: block;
|
||||
padding: 0.35rem 0.5rem;
|
||||
border-radius: 6px;
|
||||
color: var(--ink);
|
||||
font-family: "IBM Plex Mono", monospace;
|
||||
font-size: 0.78rem;
|
||||
}}
|
||||
.nav a.file:hover, .nav a.file.active {{
|
||||
background: rgba(62, 207, 142, 0.12);
|
||||
text-decoration: none;
|
||||
}}
|
||||
.folder {{ color: var(--muted); font-size: 0.75rem; margin-top: 0.75rem; }}
|
||||
main.panel {{
|
||||
padding: 1.5rem 1.75rem 3rem;
|
||||
overflow: auto;
|
||||
}}
|
||||
h1.page {{
|
||||
font-family: "Fraunces", Georgia, serif;
|
||||
font-size: 1.75rem;
|
||||
margin: 0 0 0.5rem;
|
||||
}}
|
||||
.meta {{ color: var(--muted); font-size: 0.85rem; margin-bottom: 1.5rem; }}
|
||||
section.block {{
|
||||
margin: 1.25rem 0 1.75rem;
|
||||
}}
|
||||
section.block > h2 {{
|
||||
font-size: 0.75rem;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.1em;
|
||||
color: var(--muted);
|
||||
margin: 0 0 0.65rem;
|
||||
border-bottom: 1px solid var(--line);
|
||||
padding-bottom: 0.35rem;
|
||||
}}
|
||||
.card {{
|
||||
background: var(--panel);
|
||||
border: 1px solid var(--line);
|
||||
border-radius: 10px;
|
||||
padding: 0.85rem 1rem;
|
||||
margin: 0.55rem 0;
|
||||
}}
|
||||
.fun-card {{ border-left: 3px solid var(--accent); }}
|
||||
.call-card {{ border-left: 3px solid var(--call); }}
|
||||
.branch-card {{ border-left: 3px solid var(--branch); }}
|
||||
.loop-card {{ border-left: 3px solid var(--loop); }}
|
||||
.ret-card {{ border-left: 3px solid var(--ret); }}
|
||||
.badge {{
|
||||
display: inline-block;
|
||||
font-family: "IBM Plex Mono", monospace;
|
||||
font-size: 0.7rem;
|
||||
padding: 0.1rem 0.4rem;
|
||||
border-radius: 4px;
|
||||
background: rgba(255,255,255,0.06);
|
||||
margin-right: 0.35rem;
|
||||
}}
|
||||
.params {{ margin: 0.35rem 0; }}
|
||||
.chip {{
|
||||
display: inline-block;
|
||||
font-family: "IBM Plex Mono", monospace;
|
||||
font-size: 0.75rem;
|
||||
padding: 0.15rem 0.45rem;
|
||||
margin: 0.15rem;
|
||||
border-radius: 999px;
|
||||
background: rgba(62, 207, 142, 0.15);
|
||||
color: var(--accent);
|
||||
}}
|
||||
.nested {{ margin-left: 0.85rem; padding-left: 0.75rem; border-left: 1px dashed var(--line); }}
|
||||
.arm {{
|
||||
margin: 0.4rem 0;
|
||||
padding: 0.5rem 0.65rem;
|
||||
background: rgba(0,0,0,0.2);
|
||||
border-radius: 8px;
|
||||
}}
|
||||
.out {{
|
||||
font-family: "IBM Plex Mono", monospace;
|
||||
font-size: 0.85rem;
|
||||
white-space: pre-wrap;
|
||||
background: #0a1210;
|
||||
border-radius: 8px;
|
||||
padding: 0.85rem 1rem;
|
||||
border: 1px solid var(--line);
|
||||
}}
|
||||
.out.ok {{ box-shadow: inset 3px 0 0 var(--accent-dim); }}
|
||||
.out.fail {{ box-shadow: inset 3px 0 0 var(--err); color: #ffc9c9; }}
|
||||
.source {{
|
||||
font-family: "IBM Plex Mono", monospace;
|
||||
font-size: 0.78rem;
|
||||
white-space: pre-wrap;
|
||||
background: #0a1210;
|
||||
border-radius: 8px;
|
||||
padding: 0.85rem 1rem;
|
||||
border: 1px solid var(--line);
|
||||
line-height: 1.45;
|
||||
}}
|
||||
.err {{ color: var(--err); }}
|
||||
.comment-card {{
|
||||
border-left: 3px solid var(--muted);
|
||||
background: rgba(255,255,255,0.03);
|
||||
}}
|
||||
.comment-text {{
|
||||
color: var(--muted);
|
||||
font-size: 0.9rem;
|
||||
line-height: 1.45;
|
||||
}}
|
||||
code.expr {{
|
||||
font-family: "IBM Plex Mono", monospace;
|
||||
font-size: 0.82rem;
|
||||
color: var(--ink);
|
||||
}}
|
||||
.welcome {{ max-width: 36rem; }}
|
||||
.welcome p {{ color: var(--muted); line-height: 1.55; }}
|
||||
</style>
|
||||
<title>{title} · marqdo</title>
|
||||
<link rel="icon" href="https://s3.cflmy.cn/logo/Logo.ico" type="image/x-icon"/>
|
||||
<link rel="shortcut icon" href="https://s3.cflmy.cn/logo/Logo.ico" type="image/x-icon"/>
|
||||
<link rel="apple-touch-icon" href="https://s3.cflmy.cn/logo/Logo.png"/>
|
||||
<style>{css}</style>
|
||||
</head>
|
||||
<body>
|
||||
<input type="checkbox" id="nav-toggle"/>
|
||||
<label class="backdrop" for="nav-toggle" aria-hidden="true"></label>
|
||||
<header class="topbar">
|
||||
<label class="nav-btn" for="nav-toggle" aria-label="Menu">☰</label>
|
||||
<div class="brand-row">
|
||||
<img class="logo" src="https://s3.cflmy.cn/logo/Logo.png" width="28" height="28" alt="marqdo"/>
|
||||
<p class="brand">marqdo</p>
|
||||
</div>
|
||||
</header>
|
||||
<div class="shell">
|
||||
<aside class="nav">
|
||||
<p class="brand">marq<span>do</span> view</p>
|
||||
<p class="tagline">Markup structure · live output</p>
|
||||
<div class="nav-brand">
|
||||
<div class="brand-row">
|
||||
<img class="logo" src="https://s3.cflmy.cn/logo/Logo.png" width="32" height="32" alt="marqdo"/>
|
||||
<div>
|
||||
<p class="brand">marqdo</p>
|
||||
<p class="tagline">view</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{nav}
|
||||
</aside>
|
||||
<div class="panel-wrap">
|
||||
<main class="panel">
|
||||
{main}
|
||||
</main>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
"##,
|
||||
title = escape(title),
|
||||
css = stylesheet(),
|
||||
nav = nav,
|
||||
main = main
|
||||
)
|
||||
}
|
||||
|
||||
pub fn nav_html(files: &[std::path::PathBuf], active: Option<&str>) -> String {
|
||||
pub fn nav_html(files: &[PathBuf], active: Option<&str>, links: &LinkMode) -> String {
|
||||
let mut out = String::from("<h2>Files</h2><ul>");
|
||||
let mut last_folder = String::new();
|
||||
for f in files {
|
||||
@@ -253,16 +448,68 @@ pub fn nav_html(files: &[std::path::PathBuf], active: Option<&str>) -> String {
|
||||
} else {
|
||||
""
|
||||
};
|
||||
let href = format!("/file?path={}", urlencoding_encode(&rel));
|
||||
let href = href_file(links, &rel);
|
||||
out.push_str(&format!(
|
||||
"<li><a class=\"file{active_cls}\" href=\"{href}\">{}</a></li>",
|
||||
"<li><a class=\"file{active_cls}\" href=\"{}\">{}</a></li>",
|
||||
escape(&href),
|
||||
escape(name)
|
||||
));
|
||||
}
|
||||
out.push_str("</ul>");
|
||||
// index link for static pages
|
||||
if matches!(links, LinkMode::Static { from: Some(_) }) {
|
||||
let home = href_index(links);
|
||||
out.insert_str(
|
||||
0,
|
||||
&format!(
|
||||
"<p style=\"margin:0 0 0.75rem\"><a href=\"{}\">Index</a></p>",
|
||||
escape(&home)
|
||||
),
|
||||
);
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
fn href_file(links: &LinkMode, target_rel: &str) -> String {
|
||||
match links {
|
||||
LinkMode::Live => format!("/file?path={}", urlencoding_encode(target_rel)),
|
||||
LinkMode::Static { from: None } => format!("pages/{}.html", target_rel),
|
||||
LinkMode::Static {
|
||||
from: Some(from_rel),
|
||||
} => relative_page_href(from_rel, target_rel),
|
||||
}
|
||||
}
|
||||
|
||||
fn href_index(links: &LinkMode) -> String {
|
||||
match links {
|
||||
LinkMode::Live => "/".into(),
|
||||
LinkMode::Static { from: None } => "index.html".into(),
|
||||
LinkMode::Static {
|
||||
from: Some(from_rel),
|
||||
} => {
|
||||
let depth = Path::new(from_rel)
|
||||
.parent()
|
||||
.map(|p| p.components().filter(|c| matches!(c, Component::Normal(_))).count())
|
||||
.unwrap_or(0);
|
||||
// pages/<dirs...>/file.html → up (depth+1) to OUT_DIR
|
||||
format!("{}index.html", "../".repeat(depth + 1))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// From `pages/<from>.html` to `pages/<to>.html`.
|
||||
fn relative_page_href(from_rel: &str, to_rel: &str) -> String {
|
||||
let from_parent = Path::new(from_rel).parent().unwrap_or_else(|| Path::new(""));
|
||||
let to_path = PathBuf::from(format!("{to_rel}.html"));
|
||||
let mut ups = 0usize;
|
||||
for c in from_parent.components() {
|
||||
if matches!(c, Component::Normal(_)) {
|
||||
ups += 1;
|
||||
}
|
||||
}
|
||||
format!("{}{}", "../".repeat(ups), to_path.to_string_lossy().replace('\\', "/"))
|
||||
}
|
||||
|
||||
fn urlencoding_encode(s: &str) -> String {
|
||||
let mut out = String::new();
|
||||
for b in s.bytes() {
|
||||
@@ -276,43 +523,56 @@ fn urlencoding_encode(s: &str) -> String {
|
||||
out
|
||||
}
|
||||
|
||||
pub fn page_index(files: &[std::path::PathBuf], only: Option<&Path>) -> String {
|
||||
let nav = nav_html(files, None);
|
||||
pub fn page_index(files: &[PathBuf], only: Option<&Path>, links: &LinkMode) -> String {
|
||||
let nav = nav_html(files, None, links);
|
||||
let main = if let Some(p) = only {
|
||||
let rel = p.to_string_lossy().replace('\\', "/");
|
||||
format!(
|
||||
"<div class=\"welcome\"><h1 class=\"page\">Single file</h1><p class=\"meta\">Open <a href=\"/file?path={}\">{}</a></p></div>",
|
||||
urlencoding_encode(&rel),
|
||||
"<div class=\"welcome\"><h1 class=\"page\">marqdo</h1><p class=\"meta\">Open <a href=\"{}\">{}</a></p></div>",
|
||||
escape(&href_file(links, &rel)),
|
||||
escape(&rel)
|
||||
)
|
||||
} else if files.is_empty() {
|
||||
"<div class=\"welcome\"><h1 class=\"page\">marqdo</h1><p>No <code>.mq.md</code> files found in this path.</p></div>".into()
|
||||
} else {
|
||||
// Prefer callers to render the first file at `/` / index.html; this is a fallback.
|
||||
let first = files[0].to_string_lossy().replace('\\', "/");
|
||||
format!(
|
||||
"<div class=\"welcome\"><h1 class=\"page\">Browse</h1><p>Select a <code>.mq.md</code> file in the index. Structure is rendered from the AST; output comes from the same pipeline as <code>marqdo run</code>.</p><p class=\"meta\">{} file(s)</p></div>",
|
||||
files.len()
|
||||
"<div class=\"welcome\"><h1 class=\"page\">marqdo</h1><p>Opening <a href=\"{}\">{}</a>…</p></div>",
|
||||
escape(&href_file(links, &first)),
|
||||
escape(&first)
|
||||
)
|
||||
};
|
||||
layout("index", &nav, &main)
|
||||
}
|
||||
|
||||
pub fn page_file(files: &[std::path::PathBuf], rel: &str, vm: &FileViewModel) -> String {
|
||||
let nav = nav_html(files, Some(rel));
|
||||
pub fn page_file(files: &[PathBuf], rel: &str, vm: &FileViewModel, links: &LinkMode) -> String {
|
||||
let nav = nav_html(files, Some(rel), links);
|
||||
let status = if vm.ok { "ok" } else { "fail" };
|
||||
let status_label = if vm.ok { "ok" } else { "fail" };
|
||||
let out_text = if vm.ok {
|
||||
if vm.stdout.is_empty() {
|
||||
"(no stdout)".to_string()
|
||||
"(no stdout)".into()
|
||||
} else {
|
||||
escape(&vm.stdout)
|
||||
}
|
||||
} else if vm.stderr.is_empty() {
|
||||
"(skipped)".into()
|
||||
} else {
|
||||
escape(&vm.stderr)
|
||||
};
|
||||
let title = Path::new(rel)
|
||||
.file_name()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or(rel)
|
||||
.trim_end_matches(".mq.md");
|
||||
let main = format!(
|
||||
r#"
|
||||
<h1 class="page">{title}</h1>
|
||||
<h1 class="page">{title}<span class="status-pill {status}">{status_label}</span></h1>
|
||||
<p class="meta">{rel}</p>
|
||||
<section class="block">
|
||||
<h2>Structure</h2>
|
||||
{structure}
|
||||
<div class="structure">{structure}</div>
|
||||
</section>
|
||||
<section class="block">
|
||||
<h2>Execution</h2>
|
||||
@@ -323,15 +583,11 @@ pub fn page_file(files: &[std::path::PathBuf], rel: &str, vm: &FileViewModel) ->
|
||||
<pre class="source">{source}</pre>
|
||||
</section>
|
||||
"#,
|
||||
title = escape(
|
||||
Path::new(rel)
|
||||
.file_stem()
|
||||
.and_then(|s| s.to_str())
|
||||
.unwrap_or(rel)
|
||||
),
|
||||
title = escape(title),
|
||||
status = status,
|
||||
status_label = status_label,
|
||||
rel = escape(rel),
|
||||
structure = vm.structure_html,
|
||||
status = status,
|
||||
out = out_text,
|
||||
source = escape(&vm.source),
|
||||
);
|
||||
|
||||
+52
-14
@@ -1,8 +1,11 @@
|
||||
//! `marqdo view` — local HTML browser for `.mq.md` structure + output.
|
||||
|
||||
mod html;
|
||||
mod output;
|
||||
mod render;
|
||||
|
||||
pub use output::{write_static, OutputOptions};
|
||||
|
||||
use std::fs;
|
||||
use std::net::SocketAddr;
|
||||
use std::path::{Path, PathBuf};
|
||||
@@ -11,7 +14,7 @@ use std::process::Command;
|
||||
use anyhow::{bail, Context, Result};
|
||||
use tiny_http::{Header, Method, Request, Response, Server, StatusCode};
|
||||
|
||||
use crate::view::html::{escape, page_file, page_index};
|
||||
use crate::view::html::{escape, page_file, page_index, LinkMode};
|
||||
use crate::view::render::{render_module_structure, FileViewModel};
|
||||
use crate::{run_file_capture, RunOptions};
|
||||
|
||||
@@ -22,12 +25,10 @@ pub struct ViewOptions {
|
||||
pub open_browser: bool,
|
||||
}
|
||||
|
||||
struct ViewRoot {
|
||||
/// Directory that paths are resolved against.
|
||||
root: PathBuf,
|
||||
/// If Some, only this relative file is in scope (single-file mode).
|
||||
only_file: Option<PathBuf>,
|
||||
files: Vec<PathBuf>,
|
||||
pub(crate) struct ViewRoot {
|
||||
pub root: PathBuf,
|
||||
pub only_file: Option<PathBuf>,
|
||||
pub files: Vec<PathBuf>,
|
||||
}
|
||||
|
||||
/// Block serving until Ctrl+C (process kill).
|
||||
@@ -54,7 +55,7 @@ pub fn serve(opts: ViewOptions) -> Result<()> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn build_root(path: &Path) -> Result<ViewRoot> {
|
||||
pub(crate) fn build_root(path: &Path) -> Result<ViewRoot> {
|
||||
let path = if path.exists() {
|
||||
path.canonicalize().unwrap_or_else(|_| path.to_path_buf())
|
||||
} else {
|
||||
@@ -124,14 +125,23 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
|
||||
let (path_part, query) = split_url(&url);
|
||||
match path_part {
|
||||
"/" | "/index.html" => {
|
||||
let body = page_index(&root.files, root.only_file.as_deref());
|
||||
respond_html(request, body)
|
||||
// Default: open the first file in the folder (sorted), no welcome pick screen.
|
||||
if let Some(first) = root.files.first() {
|
||||
let rel = first.to_string_lossy().replace('\\', "/");
|
||||
let resolved = resolve_rel(root, &rel)?;
|
||||
let vm = build_file_view(&resolved, &rel)?;
|
||||
let body = page_file(&root.files, &rel, &vm, &LinkMode::Live);
|
||||
respond_html(request, body)
|
||||
} else {
|
||||
let body = page_index(&root.files, None, &LinkMode::Live);
|
||||
respond_html(request, body)
|
||||
}
|
||||
}
|
||||
"/file" => {
|
||||
let rel = query_param(query, "path").unwrap_or_default();
|
||||
let resolved = resolve_rel(root, &rel)?;
|
||||
let vm = build_file_view(&resolved, &rel)?;
|
||||
let body = page_file(&root.files, &rel, &vm);
|
||||
let body = page_file(&root.files, &rel, &vm, &LinkMode::Live);
|
||||
respond_html(request, body)
|
||||
}
|
||||
"/api/tree" => {
|
||||
@@ -146,18 +156,22 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
|
||||
}
|
||||
}
|
||||
|
||||
fn build_file_view(abs: &Path, rel: &str) -> Result<FileViewModel> {
|
||||
pub(crate) fn build_file_view(abs: &Path, rel: &str) -> Result<FileViewModel> {
|
||||
let source = fs::read_to_string(abs).with_context(|| format!("read {}", abs.display()))?;
|
||||
let structure = match crate::load::load_module(abs) {
|
||||
Ok(module) => render_module_structure(&module, &source),
|
||||
Err(e) => format!(
|
||||
"<div class=\"err\">parse/load error: {}</div>",
|
||||
escape(&format!("{e:#}"))
|
||||
escape(&tidy_user_error(&format!("{e:#}"), abs, rel))
|
||||
),
|
||||
};
|
||||
let (stdout, stderr, ok) = match run_file_capture(abs, &RunOptions::default()) {
|
||||
Ok(cap) => (cap.stdout, String::new(), true),
|
||||
Err(e) => (String::new(), format!("{e:#}"), false),
|
||||
Err(e) => (
|
||||
String::new(),
|
||||
tidy_user_error(&format!("{e:#}"), abs, rel),
|
||||
false,
|
||||
),
|
||||
};
|
||||
Ok(FileViewModel {
|
||||
rel_path: rel.to_string(),
|
||||
@@ -169,6 +183,30 @@ fn build_file_view(abs: &Path, rel: &str) -> Result<FileViewModel> {
|
||||
})
|
||||
}
|
||||
|
||||
/// Prefer view-relative paths and strip Windows `\\?\` noise in error text.
|
||||
fn tidy_user_error(msg: &str, abs: &Path, rel: &str) -> String {
|
||||
use crate::diagnostics::display_path;
|
||||
let mut s = msg.to_string();
|
||||
let abs_disp = abs.display().to_string();
|
||||
let abs_clean = display_path(abs);
|
||||
for candidate in [
|
||||
abs_disp.as_str(),
|
||||
abs_clean.as_str(),
|
||||
&abs_disp.replace('/', "\\"),
|
||||
&abs_clean.replace('/', "\\"),
|
||||
&abs_disp.replace('\\', "/"),
|
||||
&abs_clean.replace('\\', "/"),
|
||||
] {
|
||||
if !candidate.is_empty() {
|
||||
s = s.replace(candidate, rel);
|
||||
}
|
||||
}
|
||||
// Leftover extended prefixes anywhere in the message
|
||||
s = s.replace(r"\\?\", "");
|
||||
s = s.replace("//?/", "");
|
||||
s
|
||||
}
|
||||
|
||||
fn resolve_rel(root: &ViewRoot, rel: &str) -> Result<PathBuf> {
|
||||
if rel.is_empty() {
|
||||
bail!("missing path");
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
//! Static HTML export: `marqdo view output`.
|
||||
|
||||
use std::fs;
|
||||
use std::path::PathBuf;
|
||||
|
||||
use anyhow::{Context, Result};
|
||||
|
||||
use crate::view::html::{page_file, page_index, LinkMode};
|
||||
use crate::view::{build_file_view, build_root, ViewRoot};
|
||||
|
||||
pub struct OutputOptions {
|
||||
pub path: PathBuf,
|
||||
pub out_dir: PathBuf,
|
||||
pub no_exec: bool,
|
||||
}
|
||||
|
||||
pub fn write_static(opts: OutputOptions) -> Result<()> {
|
||||
let root = build_root(&opts.path)?;
|
||||
fs::create_dir_all(&opts.out_dir)
|
||||
.with_context(|| format!("create {}", opts.out_dir.display()))?;
|
||||
|
||||
let pages_root = opts.out_dir.join("pages");
|
||||
let mut first_page_html: Option<String> = None;
|
||||
|
||||
for rel_pb in &root.files {
|
||||
let rel = rel_pb.to_string_lossy().replace('\\', "/");
|
||||
let abs = resolve_abs(&root, &rel)?;
|
||||
let mut vm = build_file_view(&abs, &rel)?;
|
||||
if opts.no_exec {
|
||||
vm.stdout.clear();
|
||||
vm.stderr = "execution skipped (--no-exec)".into();
|
||||
vm.ok = true;
|
||||
}
|
||||
let links = LinkMode::Static {
|
||||
from: Some(rel.clone()),
|
||||
};
|
||||
let html = page_file(&root.files, &rel, &vm, &links);
|
||||
let out_file = pages_root.join(format!("{rel}.html"));
|
||||
if let Some(parent) = out_file.parent() {
|
||||
fs::create_dir_all(parent)?;
|
||||
}
|
||||
fs::write(&out_file, html).with_context(|| format!("write {}", out_file.display()))?;
|
||||
|
||||
if first_page_html.is_none() {
|
||||
// index.html = first file (same content, links rooted at OUT_DIR)
|
||||
first_page_html = Some(page_file(
|
||||
&root.files,
|
||||
&rel,
|
||||
&vm,
|
||||
&LinkMode::Static { from: None },
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
let index_html = first_page_html.unwrap_or_else(|| {
|
||||
page_index(&root.files, root.only_file.as_deref(), &LinkMode::Static { from: None })
|
||||
});
|
||||
let index_path = opts.out_dir.join("index.html");
|
||||
fs::write(&index_path, index_html)
|
||||
.with_context(|| format!("write {}", index_path.display()))?;
|
||||
|
||||
eprintln!(
|
||||
"marqdo view output: {} page(s) → {}",
|
||||
root.files.len(),
|
||||
opts.out_dir.display()
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn resolve_abs(root: &ViewRoot, rel: &str) -> Result<PathBuf> {
|
||||
let abs = root.root.join(rel);
|
||||
Ok(abs.canonicalize().unwrap_or(abs))
|
||||
}
|
||||
+35
-9
@@ -77,6 +77,20 @@ fn skip_frontmatter_end(lines: &[ClassifiedLine]) -> Option<u32> {
|
||||
|
||||
fn emit_comments(lines: &[ClassifiedLine], from_line: u32, before_line: u32) -> String {
|
||||
let mut s = String::new();
|
||||
let mut paragraph: Vec<String> = Vec::new();
|
||||
|
||||
let flush = |paragraph: &mut Vec<String>, s: &mut String| {
|
||||
if paragraph.is_empty() {
|
||||
return;
|
||||
}
|
||||
let text = paragraph.join("\n");
|
||||
paragraph.clear();
|
||||
s.push_str(&format!(
|
||||
"<div class=\"card comment-card\"><span class=\"badge\">comment</span><span class=\"comment-text\">{}</span></div>",
|
||||
escape(&text)
|
||||
));
|
||||
};
|
||||
|
||||
for l in lines {
|
||||
if l.line_no < from_line {
|
||||
continue;
|
||||
@@ -84,17 +98,18 @@ fn emit_comments(lines: &[ClassifiedLine], from_line: u32, before_line: u32) ->
|
||||
if l.line_no >= before_line {
|
||||
break;
|
||||
}
|
||||
if l.kind == LineKind::Comment {
|
||||
let text = l.text.trim();
|
||||
if text.is_empty() {
|
||||
continue;
|
||||
match l.kind {
|
||||
LineKind::Comment => {
|
||||
let text = l.text.trim();
|
||||
if !text.is_empty() {
|
||||
paragraph.push(text.to_string());
|
||||
}
|
||||
}
|
||||
s.push_str(&format!(
|
||||
"<div class=\"card comment-card\"><span class=\"badge\">comment</span><span class=\"comment-text\">{}</span></div>",
|
||||
escape(text)
|
||||
));
|
||||
LineKind::Blank => flush(&mut paragraph, &mut s),
|
||||
LineKind::Code => flush(&mut paragraph, &mut s),
|
||||
}
|
||||
}
|
||||
flush(&mut paragraph, &mut s);
|
||||
s
|
||||
}
|
||||
|
||||
@@ -413,7 +428,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn structure_keeps_comments_and_surface_expr() {
|
||||
let src = include_str!("../../examples/structure/nested-call.mq.md");
|
||||
let src = include_str!("../../tests/structure/nested-call.mq.md");
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&module, src);
|
||||
assert!(html.contains("comment-card"));
|
||||
@@ -421,4 +436,15 @@ mod tests {
|
||||
assert!(!html.contains("Binary {"));
|
||||
assert!(!html.contains("Literal(Int"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn comments_render_as_paragraphs() {
|
||||
let src = "段首说明\n续行仍属同段\n\n下一段\n\n# main\n\n> print text=x\n";
|
||||
let module = crate::parse::parse_source(src).unwrap();
|
||||
let html = render_module_structure(&module, src);
|
||||
let cards = html.matches("comment-card").count();
|
||||
assert_eq!(cards, 2, "blank line should split comment paragraphs: {html}");
|
||||
assert!(html.contains("段首说明\n续行仍属同段"));
|
||||
assert!(html.contains("下一段"));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
# 测试夹具(金样例)
|
||||
|
||||
金样例与集成测试同处 `tests/`,用子目录区分类别。设计见 [examples-and-tests.md](../doc/design/examples-and-tests.md)。
|
||||
|
||||
| 路径 | 内容 |
|
||||
|------|------|
|
||||
| [`structure/`](structure/) | 函数、调用、分支、循环、表、导入、位置实参 |
|
||||
| [`keywords/`](keywords/) | `print`、布尔与 `and`/`or`/`not` |
|
||||
| [`errors/`](errors/) | 期望失败(诊断文案) |
|
||||
| [`gold.rs`](gold.rs) | 集成测试:跑上述夹具并比对 stdout / stderr |
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
marqdo run tests/structure/hello.mq.md
|
||||
marqdo view tests
|
||||
marqdo catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
面向访客的可执行介绍在 [`public/`](../public/)(不含 `errors/`),见 [user-site.md](../doc/design/user-site.md)。
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
+138
-27
@@ -28,52 +28,75 @@ fn assert_err(path: &str, substr: &str) {
|
||||
|
||||
#[test]
|
||||
fn structure_hello() {
|
||||
assert_out("examples/structure/hello.mq.md", "Hello World!");
|
||||
assert_out("tests/structure/hello.mq.md", "Hello World!");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_nested_call() {
|
||||
assert_out("examples/structure/nested-call.mq.md", "Hello World!");
|
||||
assert_out("tests/structure/nested-call.mq.md", "Hello World!");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_positional_call() {
|
||||
assert_out(
|
||||
"examples/structure/positional-call.mq.md",
|
||||
"tests/structure/positional-call.mq.md",
|
||||
"Hello Marqdo!\nHello World!",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_branch() {
|
||||
assert_out("examples/structure/branch.mq.md", "零");
|
||||
assert_out("tests/structure/branch.mq.md", "零");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_loop() {
|
||||
assert_out(
|
||||
"examples/structure/loop.mq.md",
|
||||
"3\n2\n1\n今天吃苹果\n今天吃梨",
|
||||
"tests/structure/loop.mq.md",
|
||||
"3
|
||||
2
|
||||
1
|
||||
今天吃苹果
|
||||
今天吃梨",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_collection() {
|
||||
assert_out("examples/structure/collection.mq.md", "苹果\n梨\n桃");
|
||||
assert_out("tests/structure/collection.mq.md", "苹果
|
||||
梨
|
||||
桃");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_import() {
|
||||
assert_out(
|
||||
"examples/structure/import/main.mq.md",
|
||||
"42\n你好,Marqdo!",
|
||||
"tests/structure/import/main.mq.md",
|
||||
"42
|
||||
你好,Marqdo!",
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
#[test]
|
||||
fn structure_fn_end_hr() {
|
||||
assert_out("tests/structure/fn-end-hr.mq.md", "Hello World!");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_fn_end_empty_return() {
|
||||
assert_out("tests/structure/fn-end-empty-return.mq.md", "Hi Marqdo!");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn structure_paragraph_comment() {
|
||||
assert_out("tests/structure/paragraph-comment.mq.md", "ok");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn keywords_print() {
|
||||
assert_out(
|
||||
"examples/keywords/print.mq.md",
|
||||
"tests/keywords/print.mq.md",
|
||||
"named form\npositional",
|
||||
);
|
||||
}
|
||||
@@ -81,7 +104,7 @@ fn keywords_print() {
|
||||
#[test]
|
||||
fn keywords_bool_logic() {
|
||||
assert_out(
|
||||
"examples/keywords/bool-logic.mq.md",
|
||||
"tests/keywords/bool-logic.mq.md",
|
||||
"ok\nnone-falsy",
|
||||
);
|
||||
}
|
||||
@@ -89,7 +112,7 @@ fn keywords_bool_logic() {
|
||||
#[test]
|
||||
fn error_undefined_var() {
|
||||
assert_err(
|
||||
"examples/errors/undefined-var.mq.md",
|
||||
"tests/errors/undefined-var.mq.md",
|
||||
"undefined variable `missing`",
|
||||
);
|
||||
}
|
||||
@@ -97,7 +120,7 @@ fn error_undefined_var() {
|
||||
#[test]
|
||||
fn error_unknown_fn() {
|
||||
assert_err(
|
||||
"examples/errors/unknown-fn.mq.md",
|
||||
"tests/errors/unknown-fn.mq.md",
|
||||
"unknown function `no_such_fn`",
|
||||
);
|
||||
}
|
||||
@@ -105,7 +128,7 @@ fn error_unknown_fn() {
|
||||
#[test]
|
||||
fn error_bad_arity() {
|
||||
assert_err(
|
||||
"examples/errors/bad-arity.mq.md",
|
||||
"tests/errors/bad-arity.mq.md",
|
||||
"missing argument for parameter `x`",
|
||||
);
|
||||
}
|
||||
@@ -113,7 +136,7 @@ fn error_bad_arity() {
|
||||
#[test]
|
||||
fn error_syntax_bad_line() {
|
||||
assert_err(
|
||||
"examples/errors/syntax-bad-line.mq.md",
|
||||
"tests/errors/syntax-bad-line.mq.md",
|
||||
"unrecognized statement",
|
||||
);
|
||||
}
|
||||
@@ -131,7 +154,7 @@ fn assert_out_backend(path: &str, backend: &str, expect: &str) {
|
||||
#[test]
|
||||
fn bytecode_hello() {
|
||||
assert_out_backend(
|
||||
"examples/structure/hello.mq.md",
|
||||
"tests/structure/hello.mq.md",
|
||||
"bytecode",
|
||||
"Hello World!",
|
||||
);
|
||||
@@ -139,31 +162,37 @@ fn bytecode_hello() {
|
||||
|
||||
#[test]
|
||||
fn bytecode_branch() {
|
||||
assert_out_backend("examples/structure/branch.mq.md", "bytecode", "零");
|
||||
assert_out_backend("tests/structure/branch.mq.md", "bytecode", "零");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bytecode_loop() {
|
||||
assert_out_backend(
|
||||
"examples/structure/loop.mq.md",
|
||||
"tests/structure/loop.mq.md",
|
||||
"bytecode",
|
||||
"3\n2\n1\n今天吃苹果\n今天吃梨",
|
||||
"3
|
||||
2
|
||||
1
|
||||
今天吃苹果
|
||||
今天吃梨",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bytecode_collection() {
|
||||
assert_out_backend(
|
||||
"examples/structure/collection.mq.md",
|
||||
"tests/structure/collection.mq.md",
|
||||
"bytecode",
|
||||
"苹果\n梨\n桃",
|
||||
"苹果
|
||||
梨
|
||||
桃",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bytecode_print_keyword() {
|
||||
assert_out_backend(
|
||||
"examples/keywords/print.mq.md",
|
||||
"tests/keywords/print.mq.md",
|
||||
"bytecode",
|
||||
"named form\npositional",
|
||||
);
|
||||
@@ -172,7 +201,7 @@ fn bytecode_print_keyword() {
|
||||
#[test]
|
||||
fn bytecode_bool_logic() {
|
||||
assert_out_backend(
|
||||
"examples/keywords/bool-logic.mq.md",
|
||||
"tests/keywords/bool-logic.mq.md",
|
||||
"bytecode",
|
||||
"ok\nnone-falsy",
|
||||
);
|
||||
@@ -181,7 +210,7 @@ fn bytecode_bool_logic() {
|
||||
#[test]
|
||||
fn bytecode_nested_call() {
|
||||
assert_out_backend(
|
||||
"examples/structure/nested-call.mq.md",
|
||||
"tests/structure/nested-call.mq.md",
|
||||
"bytecode",
|
||||
"Hello World!",
|
||||
);
|
||||
@@ -190,7 +219,7 @@ fn bytecode_nested_call() {
|
||||
#[test]
|
||||
fn bytecode_positional_call() {
|
||||
assert_out_backend(
|
||||
"examples/structure/positional-call.mq.md",
|
||||
"tests/structure/positional-call.mq.md",
|
||||
"bytecode",
|
||||
"Hello Marqdo!\nHello World!",
|
||||
);
|
||||
@@ -199,8 +228,90 @@ fn bytecode_positional_call() {
|
||||
#[test]
|
||||
fn bytecode_import() {
|
||||
assert_out_backend(
|
||||
"examples/structure/import/main.mq.md",
|
||||
"tests/structure/import/main.mq.md",
|
||||
"bytecode",
|
||||
"42\n你好,Marqdo!",
|
||||
"42
|
||||
你好,Marqdo!",
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
#[test]
|
||||
fn bytecode_fn_end_hr() {
|
||||
assert_out_backend(
|
||||
"tests/structure/fn-end-hr.mq.md",
|
||||
"bytecode",
|
||||
"Hello World!",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bytecode_fn_end_empty_return() {
|
||||
assert_out_backend(
|
||||
"tests/structure/fn-end-empty-return.mq.md",
|
||||
"bytecode",
|
||||
"Hi Marqdo!",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn bytecode_paragraph_comment() {
|
||||
assert_out_backend(
|
||||
"tests/structure/paragraph-comment.mq.md",
|
||||
"bytecode",
|
||||
"ok",
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn catalog_writes_yaml() {
|
||||
let dir = tempfile_dir("mq-cat");
|
||||
let (code, _, stderr) = run(&[
|
||||
"catalog",
|
||||
"tests",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
let yaml = std::fs::read_to_string(dir.join("catalog.yaml")).unwrap();
|
||||
assert!(yaml.contains("type: Marqdo Catalog"));
|
||||
assert!(yaml.contains("structure/hello"));
|
||||
assert!(yaml.contains("utils.mq.md"), "{yaml}");
|
||||
assert!(
|
||||
yaml.contains("跨文件导入示例") || yaml.contains("imports:\n - utils.mq.md"),
|
||||
"{yaml}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn view_output_writes_html() {
|
||||
let dir = tempfile_dir("mq-site");
|
||||
let (code, _, stderr) = run(&[
|
||||
"view",
|
||||
"output",
|
||||
"tests/structure/hello.mq.md",
|
||||
"-o",
|
||||
dir.to_str().unwrap(),
|
||||
"--no-exec",
|
||||
]);
|
||||
assert_eq!(code, 0, "{stderr}");
|
||||
let index = std::fs::read_to_string(dir.join("index.html")).unwrap();
|
||||
assert!(index.contains("marqdo"));
|
||||
assert!(!index.contains("fonts.googleapis.com"));
|
||||
assert!(index.contains("#ffffff") || index.contains("--surface: #ffffff"));
|
||||
assert!(index.contains("nav-toggle"));
|
||||
assert!(dir.join("pages").join("hello.mq.md.html").exists());
|
||||
}
|
||||
|
||||
fn tempfile_dir(prefix: &str) -> std::path::PathBuf {
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"{prefix}-{}",
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.unwrap()
|
||||
.as_millis()
|
||||
));
|
||||
let _ = std::fs::remove_dir_all(&dir);
|
||||
std::fs::create_dir_all(&dir).unwrap();
|
||||
dir
|
||||
}
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: 函数结束 — 空返回
|
||||
description: **** 空返回并结束函数体
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> 问候 谁=Marqdo
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=Hi `谁`!
|
||||
|
||||
****
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: 函数结束 — 分割线
|
||||
description: --- 结束嵌套函数体,后续调用属于外层
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,11 @@
|
||||
---
|
||||
title: 成段注释
|
||||
description: 空行分段;段内以 ` 开头的续行仍是注释
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
说明采用了
|
||||
`.mq.md`双层后缀,段内不算代码。
|
||||
|
||||
> print text=ok
|
||||
File renamed without changes.
Reference in new issue
Block a user