From f99d552d87ba0c4c05c14fff3e4b9ae0dc8afb79 Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 15 Oct 2026 14:32:50 +0800 Subject: [PATCH] feat(view): show inferred param values; migrate welcome to v0.3 prose Param chips carry call-frame values (and refresh with the call picker). Welcome pages and the marqdo skill prefer body-inferred, conversational markup. Co-authored-by: Cursor --- .cursor/skills/marqdo/SKILL.md | 14 ++++----- public/00-welcome.mq.md | 27 +++++------------ public/00-欢迎.mq.md | 34 +++++++-------------- src/view/document.rs | 54 +++++++++++++++++++++++++++++++++- src/view/html.rs | 42 ++++++++++++++++++++++++++ src/view/render.rs | 6 ++-- 6 files changed, 124 insertions(+), 53 deletions(-) diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index cda2a51..c9530f1 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -138,20 +138,19 @@ Chinese builtins (same functions, no import): ## Functions, calls, end-body +Prefer **body-inferred params** and **prose-unified** wording (v0.3). `` + `name` `` still works, but teach the inferred form first: + ```markdown # main -> greet who=Marqdo +**greet who="Marqdo"** ## greet - + `who` -> print text=Hello, `who`! - -*None* +When we meet`who`, we **print text="Hello, `who`!"** and close with*None*. ``` -- Call: `> name key=value` or `> name value`. +- Call: `**fn key="text"**` (bold; quote text literals) or `> fn key=text` (standalone `>`; bare words are text). - Nested helpers use deeper `#` (`##`, `###`, …). - After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped). - In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`). @@ -163,9 +162,8 @@ Chinese builtins (same functions, no import): **y = x + 2** ## add_one - + `n` -*n + 1* +For input`n`, do **n = n + 1** and return*n*. ``` ```markdown diff --git a/public/00-welcome.mq.md b/public/00-welcome.mq.md index cd8cce7..1608ca8 100644 --- a/public/00-welcome.mq.md +++ b/public/00-welcome.mq.md @@ -7,7 +7,7 @@ import foreign:lib/foreign.mq.md # main -Hello — and welcome. I built Marqdo so that *code is documentation and documentation is code*: Markdown markers are the program structure, so what you read is what runs. +Hello — and welcome. I built Marqdo so that code is documentation and documentation is code: Markdown markers are the program structure, so what you read is what runs. AI systems already favor Markdown-shaped output. That raised a simple question: why keep docs and programs as two separate artifacts? Marqdo is the answer. The `.mq.md` suffix exists so a file stays renderable as Markdown while remaining executable. Richer OKF-style YAML catalogs and even slide decks are on the roadmap; for now this site itself is generated by Marqdo — and that often saves tokens when an AI is writing with you. @@ -15,44 +15,33 @@ The language is still early: structural markers, English/Chinese builtin aliases 中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。 -A small function to say hello (calls in entry `# main` actually run; `##` children are methods and do not auto-run): +Want a quick hello? Calls only run when they sit in the entry `# main` — `##` children are methods until something calls them. Try **greet who="marqdo"**. Names can include spaces: **greet who="marqdo user"**. -> greet who=marqdo +Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention. -Named args can include spaces: - -> greet who=marqdo user - -Beyond the basics above, Marqdo also ships standard libraries: table, time, text, files, system, math, foreign, and more. - -Math and foreign deserve a special mention. With the math library you can bind a formula like this: +Bind a formula to `f` like this: `f` = $$ x^2 - 2 $$ -Then plot it: +Then plot it: **_svg = math.plot formula=`f` var="x" min=-3 max=3** -**`_svg` = > math.plot formula=`f` var="x" min=-3 max=3** - -The foreign library lets you call external code, for example: +Foreign lets you embed another language. Bind `hi` to a small Python block: `hi` = ```python print("hello-from-python") ``` -Under Markdown this stays easy to read — which is the point: Marqdo’s design is code as documentation, documentation as code. +Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code. Welcome again — enjoy exploring Marqdo. ## greet - + `who` -> print text=Welcome, `who`! - -*None* +When we meet a visitor `who`, we **print text="Welcome, `who`!"** and close with*None*. ## install diff --git a/public/00-欢迎.mq.md b/public/00-欢迎.mq.md index 97bf98d..2d21746 100644 --- a/public/00-欢迎.mq.md +++ b/public/00-欢迎.mq.md @@ -7,53 +7,41 @@ description: 用户文档首页 — 代码即文档(中文版) # main -阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门*代码即文档,文档即代码*的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。 +阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门「代码即文档,文档即代码」的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。 -AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和代码拆成两套?我们来实现一个文档即代码的语言,所以marqdo应运而生,为了确保代码一定可以被渲染,marqdo的文件后缀定义为了`.mq.md`。在开发之处我们就尝试希望更丰富的支持,自动生成一个yaml文件使得 OKF 式知识库便捷的自动配置,乃至自动生成ppt,自然这都是以后的目标了。不过相当不错的是,至少这会成为一个不错的博客工具——对,这个站点就是 Marqdo 生成的,而且AI输出的时候会节约不少token,你知道的,token烧的太多,钱包会可怜的饿瘦的。 +AI 偏爱 Markdown 结构的输出。我当时的念头很简单——何必再把文档和代码拆成两套?于是有了 marqdo。为了让文件既能当文档渲染又能执行,后缀定为 `.mq.md`。更远的目标还有 OKF 式知识库的 YAML、甚至自动生成 PPT;眼下它至少已经是个不错的博客工具——对,这个站点就是 Marqdo 生成的。AI 写 `.mq.md` 时往往更省 token,钱包也会轻松一点。 语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。 -English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins). +English docs: [`00-welcome.mq.md`](00-welcome.mq.md)(English prose and English builtins). -用一个小函数打个招呼(入口 `# main` 里的调用会真正执行;`##` 子标题是方法,不会自动跑): +想先打个招呼?调用写在入口 `# main` 里才会真的跑——子标题里的方法要等你叫到它。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。 -> 问候 谁=marqdo +除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。 -具名实参可以带空格: - -> 问候 谁=marqdo user - -除了上面的一些基本内容之外,我还开发了这个语言的一些标准库,包括表、时间、文本、文件、系统、数学和外联等标准库。 - -其中数学库和外联库是我要着重提到的,例如数学库,你可以通过下面的方式调用: +比方说,先给公式起个名字`f`: `f` = $$ x^2 - 2 $$ -之后让我们画个图像吧! +接着画出来:**_svg = 数学.绘图 formula=`f` var="x" min=-3 max=3** -**`_svg` = > 数学.绘图 formula=`f` var="x" min=-3 max=3** - -外联库则允许你调用外部代码,例如: +外联则允许嵌一段别的语言。把`hi`绑成下面这样即可: `hi` = ```python print("hello-from-python") ``` -这些代码在markdown下面都非常的易读,就像我说的,marqdo的设计思想就是代码即文档, -文档即代码。 +这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。 -最后,再次欢迎你,尽情体验marqdo吧! +最后,再次欢迎你,尽情体验 marqdo 吧! ## 问候 - + `谁` -> 打印 内容=欢迎,`谁`! - -*None* +见到访客`谁`时,我们 **打印 内容="欢迎,`谁`!"**,然后收束为*None*。 ## 安装 diff --git a/src/view/document.rs b/src/view/document.rs index 1d649f9..557eb7f 100644 --- a/src/view/document.rs +++ b/src/view/document.rs @@ -633,6 +633,11 @@ fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String { } s.push_str(""); if !fun.params.is_empty() { + // Default SSR values = last call frame (matches picker default = last option). + let default_args = call_labels + .last() + .map(|a| parse_args_brief(&a.value)) + .unwrap_or_default(); s.push_str(r#"
"#); for p in &fun.params { let cls = if p.inferred { @@ -645,11 +650,19 @@ fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String { } else { "explicit + param" }; + let val = default_args + .get(p.name.as_str()) + .filter(|v| !v.is_empty()) + .map(|v| format!("={}", escape(v))) + .unwrap_or_default(); + // Always emit chip-val so call-picker JS can refresh per frame. s.push_str(&format!( - r#"{name}"#, + r#"{name}{val}"#, cls = cls, title = title, name = escape(&p.name), + fn = escape(&fun.name), + val = val, )); } s.push_str("
"); @@ -658,6 +671,22 @@ fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String { s } +/// Parse `args_brief` (`谁=marqdo, n=37`) into name → value. +fn parse_args_brief(brief: &str) -> HashMap { + let mut m = HashMap::new(); + if brief.trim().is_empty() { + return m; + } + for part in brief.split(", ") { + if let Some((k, v)) = part.split_once('=') { + if !k.is_empty() { + m.insert(k.to_string(), v.to_string()); + } + } + } + m +} + fn render_line_block( line_no: u32, text: &str, @@ -1163,6 +1192,29 @@ mod tests { ); } + #[test] + fn inferred_param_chip_shows_call_value() { + let src = include_str!("../../tests/markup-v03/inc-prose.mq.md"); + let module = crate::parse::parse_source(src).unwrap(); + let add = module + .functions + .iter() + .find(|f| f.name == "加一函数") + .expect("加一函数"); + assert!(add.params.iter().any(|p| p.name == "n" && p.inferred)); + let cap = crate::run_source(src, &crate::RunOptions::default()).unwrap(); + let annots = build_view_annots(&module, src, &cap); + let html = render_module_document(&module, src, &annots); + assert!( + html.contains(r#"data-param-name="n""#) && html.contains("chip inferred"), + "inferred param chip missing: {html}" + ); + assert!( + html.contains(r#"class="chip-val">=37"#) || html.contains("chip-val\">=37"), + "expected param chip value from call frame: {html}" + ); + } + #[test] fn document_frame_pickers_and_all_arms() { let src = include_str!("../../tests/view/document-annot-demo.mq.md"); diff --git a/src/view/html.rs b/src/view/html.rs index d60134e..1eb35be 100644 --- a/src/view/html.rs +++ b/src/view/html.rs @@ -593,6 +593,15 @@ ul.doc-loop, ol.doc-branch { font-size: 0.65em; opacity: 0.7; } +.chip .chip-val { + font-weight: 500; + opacity: 0.78; + font-family: var(--mono); + font-size: 0.92em; +} +.chip .chip-val:empty { + display: none; +} .nested { margin: 0.45rem 0 0.15rem 0.15rem; padding-left: 0.85rem; @@ -2185,11 +2194,43 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String { try {{ return JSON.parse(el.textContent || "{{}}"); }} catch (e) {{ return null; }} }} + function parseArgsBrief(brief) {{ + var out = {{}}; + if (!brief) return out; + String(brief).split(", ").forEach(function (part) {{ + var i = part.indexOf("="); + if (i <= 0) return; + out[part.slice(0, i)] = part.slice(i + 1); + }}); + return out; + }} + + function applyParamChipValues(fnName, callId, trace) {{ + if (!trace || !Array.isArray(trace.calls)) return; + var brief = ""; + for (var i = 0; i < trace.calls.length; i++) {{ + var c = trace.calls[i]; + if (String(c.call_id) === String(callId) && String(c.fn || "") === String(fnName)) {{ + brief = c.args_brief || ""; + break; + }} + }} + var args = parseArgsBrief(brief); + document.querySelectorAll('.chip[data-fn="' + fnName + '"][data-param-name]').forEach(function (chip) {{ + var name = chip.getAttribute("data-param-name") || ""; + var slot = chip.querySelector(".chip-val"); + if (!slot) return; + var v = args[name]; + slot.textContent = v ? ("=" + v) : ""; + }}); + }} + /** Source structure always stays visible; only chips + arm classes follow the frame. */ function initCallPickers() {{ document.querySelectorAll(".call-picker").forEach(function (sel) {{ function apply() {{ var callId = String(sel.value || ""); + var fnName = String(sel.getAttribute("data-fn") || ""); var allowed = {{}}; Array.prototype.forEach.call(sel.options, function (o) {{ allowed[String(o.value)] = true; @@ -2202,6 +2243,7 @@ pub fn layout(title: &str, nav: &str, main: &str) -> String { chip.hidden = cid !== callId; }}); var trace = readViewTrace(); + applyParamChipValues(fnName, callId, trace); if (trace && Array.isArray(trace.events)) {{ var takenByLine = {{}}; trace.events.forEach(function (ev) {{ diff --git a/src/view/render.rs b/src/view/render.rs index 67fc450..797d8e2 100644 --- a/src/view/render.rs +++ b/src/view/render.rs @@ -971,10 +971,11 @@ fn render_fun( ("chip", "explicit + param") }; s.push_str(&format!( - "{name}", + "{name}", cls = cls, title = title, name = escape(&p.name), + fn = escape(&fun.name), )); } s.push_str(""); @@ -1750,7 +1751,8 @@ mod tests { assert!(add.params.iter().any(|p| p.name == "n" && p.inferred)); let html = render_module_structure(&module, src); assert!( - html.contains("chip inferred") && html.contains(">n<"), + html.contains("chip inferred") + && (html.contains(">n<") || html.contains(r#"data-param-name="n""#)), "expected inferred chip for n: {html}" ); let outline = render_function_outline(&module);