docs(public): finish stdlib bracket-call demos and fix import returns
Prefer [lib.fn] in remaining public/stdlib samples, correct italic returns in structure import modules, and keep lib/系统 narration from starting with backticks. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
34915e3b16
commit
d5a9301c7f
20 files changed
+45
-39
No files matched your search
@@ -63,22 +63,22 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
|
||||
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
|
||||
|
||||
```markdown
|
||||
*`set_text` = > table.put in=None at="#log" value=msg*
|
||||
**> table.put in=None at="set_text" value=set_text**
|
||||
**`set_text` = table.put in=None at="#log" value=msg**
|
||||
**table.put in=None at="set_text" value=set_text**
|
||||
```
|
||||
|
||||
Better still — call a named helper:
|
||||
|
||||
```markdown
|
||||
**> browser.set_text sel="#log" text=msg**
|
||||
**browser.set_text sel="#log" text=msg**
|
||||
```
|
||||
|
||||
### 3. Bad pattern (do not write)
|
||||
|
||||
```markdown
|
||||
*`ret` = > json.set map=None key="set_text" value=…*
|
||||
*`ret` = > json.set map=ret key="canvas" value=…*
|
||||
*`cmds` = > json.append list=cmds item=c0*
|
||||
**`ret` = json.set map=None key="set_text" value=…**
|
||||
**`ret` = json.set map=ret key="canvas" value=…**
|
||||
**`cmds` = json.append list=cmds item=c0**
|
||||
```
|
||||
|
||||
## Writing application `.mq.md`
|
||||
|
||||
@@ -31,6 +31,7 @@
|
||||
| **M7** | structure collection 金样改链接形;public/stdlib 括号调用例 | **done** |
|
||||
| **M8** | 教程第 9 章 + Skill examples → 链接取元 / v0.3 标记 | **done** |
|
||||
| **M9** | 教程其余章节(1–8、10–12、14)全面对齐 v0.3 + 链接取元 | **done** |
|
||||
| **M10** | public/stdlib 剩余演示统一括号调用;public import 返回面修到 v0.3 | **done** |
|
||||
|
||||
## 2. 验收(出门)
|
||||
|
||||
@@ -53,3 +54,4 @@
|
||||
| 2026-09-14 | M7 structure collection 金样 + stdlib 括号调用例 |
|
||||
| 2026-09-14 | M8 教程 + Skill examples 同步 |
|
||||
| 2026-09-14 | M9 教程全书对齐 v0.3 标记与链接取元 |
|
||||
| 2026-09-14 | M10 public/stdlib 括号调用扫尾 + import 返回面 |
|
||||
+1
-1
@@ -53,7 +53,7 @@ description: 中文系统包装(加载环境 可选 路径=)
|
||||
|
||||
运行子进程。默认返回退出码(整数)。
|
||||
|
||||
`捕获=True` 时返回映射 `{code, stdout, stderr}`(过大输出可能截断)。
|
||||
当捕获为真(`捕获=True`)时返回映射 `{code, stdout, stderr}`(过大输出可能截断)。
|
||||
|
||||
在 `**…**` 内优先写裸变量 `参数=参数`;`` 参数=`参数` `` 亦可。
|
||||
|
||||
|
||||
@@ -15,6 +15,6 @@ print("hello-from-python")
|
||||
|
||||
Default command is python (Windows) or python3 (Unix). Override with set_cmd, env MARQDO_FOREIGN_PYTHON, or the command box in live view. Failures ask you to check that configuration.
|
||||
|
||||
**`out` = > foreign.run code=`hi` **
|
||||
**`out` = [foreign.run] code=`hi`**
|
||||
|
||||
> print text=`out`
|
||||
@@ -10,8 +10,8 @@ Shared JSON helpers for EN and ZH docs. Prefer parse, stringify, and quote.
|
||||
Build maps with tables or table.put — not json.set chains.
|
||||
|
||||
**`obj` = [json.parse] text="{}"**
|
||||
**`ty` = > type `obj`**
|
||||
**`ty` = [type] `obj`**
|
||||
**打印 内容=`ty`**
|
||||
|
||||
**`out` = > json.stringify value=`obj`**
|
||||
**`out` = [json.stringify] value=`obj`**
|
||||
**打印 内容=`out`**
|
||||
@@ -21,18 +21,18 @@ Plotting (already in the library): plot / plot_points / plot_conic return SVG te
|
||||
|
||||
diff / simplify / expand / partial subs return formula values so you can chain (e.g. differentiate twice, then plot or eval).
|
||||
|
||||
**`ty` = > type `f`**
|
||||
**`ty` = [type] `f`**
|
||||
|
||||
> print text=`ty`
|
||||
|
||||
**`df` = > math.diff formula=`f` var="x"**
|
||||
**`df` = [math.diff] formula=`f` var="x"**
|
||||
|
||||
> print text=`df`
|
||||
|
||||
**`roots` = > math.solve formula=`f` var="x"**
|
||||
**`roots` = [math.solve] formula=`f` var="x"**
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
**`_svg` = > math.plot formula=`f` var="x" min=-3 max=3**
|
||||
**`_svg` = [math.plot] formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
> print text=plot-ok
|
||||
@@ -8,6 +8,6 @@ import net:lib/net.mq.md
|
||||
|
||||
Import lib/net.mq.md. Functions: http_get, http_post, http_post_sse, openai_sse_parse, http_request, url_encode. HTTPS and optional headers= map are supported. Default post content-type is JSON. `http_post_sse` / `openai_sse_parse` return OpenAI chat stream event lists (`delta` / `done`).
|
||||
|
||||
**`e` = > net.url_encode text="hello world"**
|
||||
**`e` = [net.url_encode] text="hello world"**
|
||||
|
||||
> print text=`e`
|
||||
@@ -8,9 +8,9 @@ import plugin:lib/plugin.mq.md
|
||||
|
||||
Import lib/plugin.mq.md. Functions: load(path), unload(), list(). After load, registered plugin names are callable like other functions. C ABI: include/marqdo_abi.h — see doc/design/ext-abi.md. Path must stay under the program sandbox (cwd / fs root).
|
||||
|
||||
**`names` = > plugin.list **
|
||||
**`names` = [plugin.list]**
|
||||
|
||||
**`n` = > len `names` **
|
||||
**`n` = [len] `names`**
|
||||
|
||||
1. `n` >= 0
|
||||
> print text=plugin-ok
|
||||
|
||||
@@ -8,9 +8,9 @@ import sys:lib/sys.mq.md
|
||||
|
||||
Import lib/sys.mq.md. Functions: env_get, env_set, load_dotenv(optional path), args, cwd, exit(code), exec(cmd), stream_publish(event). load_dotenv does not override existing variables. Under view, exit soft-fails instead of killing the process. `stream_publish` feeds the view SSE EventBus.
|
||||
|
||||
**`d` = > sys.cwd **
|
||||
**`d` = [sys.cwd]**
|
||||
|
||||
**`n` = > len `d` **
|
||||
**`n` = [len] `d`**
|
||||
|
||||
1. `n` > 0
|
||||
> print text=cwd-ok
|
||||
|
||||
@@ -11,6 +11,6 @@ Import lib/text. Bracket path or classic dotted calls both work.
|
||||
**`t` = [text.str_trim] s=" marqdo "**
|
||||
**打印 内容=`t`**
|
||||
|
||||
**`parts` = > text.str_split s="a,b,c" sep=","**
|
||||
**`j` = > text.str_join xs=`parts` sep="-"**
|
||||
**`parts` = [text.str_split] s="a,b,c" sep=","**
|
||||
**`j` = [text.str_join] xs=`parts` sep="-"**
|
||||
**打印 内容=`j`**
|
||||
@@ -15,6 +15,6 @@ print("hello-from-python")
|
||||
|
||||
默认命令可用 设置命令 或 MARQDO_FOREIGN_PYTHON 覆盖;live view 里可改命令框再点 Run。
|
||||
|
||||
**`out` = > 外联.运行 代码=`hi` **
|
||||
**`out` = [外联.运行] 代码=`hi`**
|
||||
|
||||
> print text=`out`
|
||||
@@ -8,9 +8,9 @@ description: 加载可选共享库(.dll / .so / .dylib)
|
||||
|
||||
导入 lib/插件.mq.md。函数:加载(路径)、卸载()、列出()。加载后,插件注册的名称可像普通函数一样调用。C 契约见 include/marqdo_abi.h 与 doc/design/ext-abi.md。路径须落在程序沙箱内。
|
||||
|
||||
**`names` = > 插件.列出 **
|
||||
**`names` = [插件.列出]**
|
||||
|
||||
**`n` = > 长度 值=`names` **
|
||||
**`n` = [长度] 值=`names`**
|
||||
|
||||
1. `n` >= 0
|
||||
> 打印 内容=插件就绪
|
||||
|
||||
@@ -21,18 +21,18 @@ $$
|
||||
|
||||
求导 / 化简 / 展开 / 未完全数值化的代入仍返回 formula,可继续链式调用(例如求二阶导后再绘图或求值)。
|
||||
|
||||
**`ty` = > type `f`**
|
||||
**`ty` = [type] `f`**
|
||||
|
||||
> print text=`ty`
|
||||
|
||||
**`df` = > 数学.求导 formula=`f` var="x"**
|
||||
**`df` = [数学.求导] formula=`f` var="x"**
|
||||
|
||||
> print text=`df`
|
||||
|
||||
**`roots` = > 数学.求解 formula=`f` var="x"**
|
||||
**`roots` = [数学.求解] formula=`f` var="x"**
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
**`_svg` = > 数学.绘图 formula=`f` var="x" min=-3 max=3**
|
||||
**`_svg` = [数学.绘图] formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
> print text=plot-ok
|
||||
@@ -11,6 +11,6 @@ description: 去空白、拆分、拼接(代码即文档试点)
|
||||
**`t` = [文本.去空白] s=" marqdo "**
|
||||
**打印 内容=`t`**
|
||||
|
||||
**`parts` = > 文本.拆分 s="甲,乙,丙" sep=","**
|
||||
**`j` = > 文本.拼接 xs=`parts` sep="-"**
|
||||
**`parts` = [文本.拆分] s="甲,乙,丙" sep=","**
|
||||
**`j` = [文本.拼接] xs=`parts` sep="-"**
|
||||
**打印 内容=`j`**
|
||||
@@ -8,9 +8,9 @@ description: 环境变量、dotenv、工作目录、参数、退出、执行
|
||||
|
||||
导入 lib/系统.mq.md。函数:取环境、设环境、加载环境(可选路径)、参数表、工作目录、退出(码)、执行(命令)。加载环境不覆盖已有变量。view 下退出会软失败,不结束进程。
|
||||
|
||||
**`d` = > 系统.工作目录 **
|
||||
**`d` = [系统.工作目录]**
|
||||
|
||||
**`n` = > 长度 值=`d` **
|
||||
**`n` = [长度] 值=`d`**
|
||||
|
||||
1. `n` > 0
|
||||
> 打印 内容=工作目录就绪
|
||||
|
||||
@@ -8,6 +8,6 @@ description: HTTP(S) 与地址编码
|
||||
|
||||
导入 lib/网络.mq.md。函数:获取(地址)、提交(地址, 内容;可选 content_type / headers)、编码地址(内容)。支持 HTTP 与 HTTPS(ureq)。
|
||||
|
||||
**`e` = > 网络.编码地址 内容="你好"**
|
||||
**`e` = [网络.编码地址] 内容="你好"**
|
||||
|
||||
> 打印 内容=`e`
|
||||
@@ -10,7 +10,7 @@ In the YAML header, `import utils:utils.mq.md` imports a sibling module and bind
|
||||
|
||||
Bind a return value, print it, then call greet:
|
||||
|
||||
**`y` = > utils.add_one n=41**
|
||||
**`y` = [utils.add_one] n=41**
|
||||
|
||||
> print text=`y`
|
||||
|
||||
|
||||
@@ -1,14 +1,16 @@
|
||||
---
|
||||
title: Utility module
|
||||
description: Imported by main; bold is a return value
|
||||
description: Imported by main; italic is return; print for side effects
|
||||
---
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
*n + 1*
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
*None*
|
||||
@@ -10,7 +10,7 @@ description: frontmatter 导入 bind:路径.mq.md
|
||||
|
||||
绑定返回值、打印,再调用问候:
|
||||
|
||||
**`y` = > 工具.加一 n=41**
|
||||
**`y` = [工具.加一] n=41**
|
||||
|
||||
> 打印 内容=`y`
|
||||
|
||||
|
||||
@@ -1,14 +1,16 @@
|
||||
---
|
||||
title: 工具模块
|
||||
description: 被 main 导入;粗体为返回值
|
||||
description: 被 main 导入;斜体为返回;副作用用打印
|
||||
---
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
*n + 1*
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> 打印 内容=你好,`谁`!
|
||||
|
||||
*无*
|
||||
Reference in new issue
Block a user