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 <cursoragent@cursor.com>
This commit is contained in:
1 parent
7d49c358c1
commit
f99d552d87
6 files changed
+124
-53
No files matched your search
@@ -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
|
||||
|
||||
+8
-19
@@ -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
|
||||
|
||||
|
||||
+11
-23
@@ -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*。
|
||||
|
||||
## 安装
|
||||
|
||||
|
||||
+53
-1
@@ -633,6 +633,11 @@ fn render_fun_heading(fun: &Function, annots: &[ViewAnnot]) -> String {
|
||||
}
|
||||
s.push_str("</div>");
|
||||
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#"<div class="params">"#);
|
||||
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#"<span class="{cls}" title="{title}">{name}</span>"#,
|
||||
r#"<span class="{cls}" data-param-name="{name}" data-fn="{fn}" title="{title}">{name}<span class="chip-val">{val}</span></span>"#,
|
||||
cls = cls,
|
||||
title = title,
|
||||
name = escape(&p.name),
|
||||
fn = escape(&fun.name),
|
||||
val = val,
|
||||
));
|
||||
}
|
||||
s.push_str("</div>");
|
||||
@@ -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<String, String> {
|
||||
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");
|
||||
|
||||
@@ -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) {{
|
||||
|
||||
+4
-2
@@ -971,10 +971,11 @@ fn render_fun(
|
||||
("chip", "explicit + param")
|
||||
};
|
||||
s.push_str(&format!(
|
||||
"<span class=\"{cls}\" title=\"{title}\">{name}</span>",
|
||||
"<span class=\"{cls}\" data-param-name=\"{name}\" data-fn=\"{fn}\" title=\"{title}\">{name}<span class=\"chip-val\"></span></span>",
|
||||
cls = cls,
|
||||
title = title,
|
||||
name = escape(&p.name),
|
||||
fn = escape(&fun.name),
|
||||
));
|
||||
}
|
||||
s.push_str("</div>");
|
||||
@@ -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);
|
||||
|
||||
Reference in new issue
Block a user