Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
a4c04666b4 |
No files matched your search
@@ -1 +0,0 @@
|
||||
/target
|
||||
Executable
+17
@@ -0,0 +1,17 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 360" width="520" height="360" role="img" aria-label="function plot">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
||||
<path d="M 0 0 L 10 5 L 0 10 z" fill="#4b5563"/>
|
||||
</marker>
|
||||
</defs>
|
||||
<style>
|
||||
.grid { stroke: #e5e7eb; stroke-width: 1; }
|
||||
.axis { stroke: #4b5563; stroke-width: 1.5; }
|
||||
.tick { stroke: #4b5563; stroke-width: 1; }
|
||||
.curve { fill: none; stroke: #1f6feb; stroke-width: 2; }
|
||||
.pt { fill: #1f6feb; }
|
||||
.axis-label { font: 12px ui-sans-serif, system-ui, sans-serif; fill: #374151; font-weight: 600; }
|
||||
.tick-label { font: 10px ui-sans-serif, system-ui, sans-serif; fill: #6b7280; }
|
||||
</style>
|
||||
<line x1="36.00" y1="36" x2="36.00" y2="324" class="grid"/><line x1="110.67" y1="36" x2="110.67" y2="324" class="grid"/><line x1="185.33" y1="36" x2="185.33" y2="324" class="grid"/><line x1="260.00" y1="36" x2="260.00" y2="324" class="grid"/><line x1="334.67" y1="36" x2="334.67" y2="324" class="grid"/><line x1="409.33" y1="36" x2="409.33" y2="324" class="grid"/><line x1="484.00" y1="36" x2="484.00" y2="324" class="grid"/><line x1="36" y1="310.91" x2="484" y2="310.91" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="grid"/><line x1="36" y1="194.55" x2="484" y2="194.55" class="grid"/><line x1="36" y1="136.36" x2="484" y2="136.36" class="grid"/><line x1="36" y1="78.18" x2="484" y2="78.18" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="axis" marker-end="url(#arrow)"/><line x1="260.00" y1="324" x2="260.00" y2="36" class="axis" marker-end="url(#arrow)"/><text x="488.00" y="256.73" class="axis-label">x</text><text x="266.00" y="40.00" class="axis-label">y</text><line x1="36.00" y1="248.73" x2="36.00" y2="256.73" class="tick"/><text x="36.00" y="266.73" text-anchor="middle" class="tick-label">-3</text><line x1="110.67" y1="248.73" x2="110.67" y2="256.73" class="tick"/><text x="110.67" y="266.73" text-anchor="middle" class="tick-label">-2</text><line x1="185.33" y1="248.73" x2="185.33" y2="256.73" class="tick"/><text x="185.33" y="266.73" text-anchor="middle" class="tick-label">-1</text><line x1="334.67" y1="248.73" x2="334.67" y2="256.73" class="tick"/><text x="334.67" y="266.73" text-anchor="middle" class="tick-label">1</text><line x1="409.33" y1="248.73" x2="409.33" y2="256.73" class="tick"/><text x="409.33" y="266.73" text-anchor="middle" class="tick-label">2</text><line x1="484.00" y1="248.73" x2="484.00" y2="256.73" class="tick"/><text x="484.00" y="266.73" text-anchor="middle" class="tick-label">3</text><line x1="256.00" y1="310.91" x2="264.00" y2="310.91" class="tick"/><text x="252.00" y="310.91" text-anchor="end" dominant-baseline="middle" class="tick-label">-2</text><line x1="256.00" y1="194.55" x2="264.00" y2="194.55" class="tick"/><text x="252.00" y="194.55" text-anchor="end" dominant-baseline="middle" class="tick-label">2</text><line x1="256.00" y1="136.36" x2="264.00" y2="136.36" class="tick"/><text x="252.00" y="136.36" text-anchor="end" dominant-baseline="middle" class="tick-label">4</text><line x1="256.00" y1="78.18" x2="264.00" y2="78.18" class="tick"/><text x="252.00" y="78.18" text-anchor="end" dominant-baseline="middle" class="tick-label">6</text><text x="252.00" y="266.73" class="tick-label">0</text><path d="M 36.00 49.09 L 38.24 54.30 L 40.48 59.46 L 42.72 64.56 L 44.96 69.62 L 47.20 74.62 L 49.44 79.57 L 51.68 84.46 L 53.92 89.31 L 56.16 94.10 L 58.40 98.84 L 60.64 103.52 L 62.88 108.16 L 65.12 112.74 L 67.36 117.27 L 69.60 121.75 L 71.84 126.17 L 74.08 130.54 L 76.32 134.86 L 78.56 139.13 L 80.80 143.35 L 83.04 147.51 L 85.28 151.62 L 87.52 155.68 L 89.76 159.68 L 92.00 163.64 L 94.24 167.54 L 96.48 171.39 L 98.72 175.18 L 100.96 178.93 L 103.20 182.62 L 105.44 186.26 L 107.68 189.84 L 109.92 193.38 L 112.16 196.86 L 114.40 200.29 L 116.64 203.67 L 118.88 206.99 L 121.12 210.27 L 123.36 213.49 L 125.60 216.65 L 127.84 219.77 L 130.08 222.83 L 132.32 225.84 L 134.56 228.80 L 136.80 231.71 L 139.04 234.56 L 141.28 237.36 L 143.52 240.11 L 145.76 242.81 L 148.00 245.45 L 150.24 248.05 L 152.48 250.59 L 154.72 253.07 L 156.96 255.51 L 159.20 257.89 L 161.44 260.22 L 163.68 262.50 L 165.92 264.72 L 168.16 266.90 L 170.40 269.02 L 172.64 271.09 L 174.88 273.10 L 177.12 275.07 L 179.36 276.98 L 181.60 278.84 L 183.84 280.64 L 186.08 282.40 L 188.32 284.10 L 190.56 285.75 L 192.80 287.35 L 195.04 288.89 L 197.28 290.38 L 199.52 291.82 L 201.76 293.21 L 204.00 294.55 L 206.24 295.83 L 208.48 297.06 L 210.72 298.24 L 212.96 299.36 L 215.20 300.44 L 217.44 301.46 L 219.68 302.43 L 221.92 303.34 L 224.16 304.21 L 226.40 305.02 L 228.64 305.78 L 230.88 306.48 L 233.12 307.14 L 235.36 307.74 L 237.60 308.29 L 239.84 308.79 L 242.08 309.23 L 244.32 309.63 L 246.56 309.97 L 248.80 310.25 L 251.04 310.49 L 253.28 310.67 L 255.52 310.80 L 257.76 310.88 L 260.00 310.91 L 262.24 310.88 L 264.48 310.80 L 266.72 310.67 L 268.96 310.49 L 271.20 310.25 L 273.44 309.97 L 275.68 309.63 L 277.92 309.23 L 280.16 308.79 L 282.40 308.29 L 284.64 307.74 L 286.88 307.14 L 289.12 306.48 L 291.36 305.78 L 293.60 305.02 L 295.84 304.21 L 298.08 303.34 L 300.32 302.43 L 302.56 301.46 L 304.80 300.44 L 307.04 299.36 L 309.28 298.24 L 311.52 297.06 L 313.76 295.83 L 316.00 294.55 L 318.24 293.21 L 320.48 291.82 L 322.72 290.38 L 324.96 288.89 L 327.20 287.35 L 329.44 285.75 L 331.68 284.10 L 333.92 282.40 L 336.16 280.64 L 338.40 278.84 L 340.64 276.98 L 342.88 275.07 L 345.12 273.10 L 347.36 271.09 L 349.60 269.02 L 351.84 266.90 L 354.08 264.72 L 356.32 262.50 L 358.56 260.22 L 360.80 257.89 L 363.04 255.51 L 365.28 253.07 L 367.52 250.59 L 369.76 248.05 L 372.00 245.45 L 374.24 242.81 Line truncated
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 6.4 KiB |
Executable
+135
@@ -0,0 +1,135 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Welcome to Marqdo
|
||||
description: User-docs home — code as documentation (English)
|
||||
import:
|
||||
math: lib/math.mq.md
|
||||
foreign: lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
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.
|
||||
|
||||
The language is still early: structural markers, English/Chinese builtin aliases (`print` / `打印` …), an importable standard library (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Join in at [GitHub](https://github.com/cflmy/marqdo).
|
||||
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
Want a quick hello? `marqdo run` executes the entry `# main`. Try **greet who="marqdo"**. Names can include spaces: **greet who="marqdo user"**.
|
||||
|
||||
This version also runs one function on its own. `marqdo call` takes the file, the function and named arguments. The page you read is the program that runs. What that is for, and why it matters, is in [features/22-call.mq.md](features/22-call.mq.md).
|
||||
|
||||
Beyond the basics, Marqdo ships table, time, text, files, system, math, foreign, and more. Math and foreign deserve a special mention.
|
||||
|
||||
Write a math block and bind it with a TeX comment:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it: **_svg = math.plot formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
Foreign lets you embed another language. Use Node Intl for locale-aware currency formatting, a genuine presentation boundary:
|
||||
|
||||
`hi` =
|
||||
```node
|
||||
console.log(new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"}).format(950));
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code.
|
||||
|
||||
One file, three surfaces.
|
||||
|
||||
| Surface | What it is |
|
||||
|---|---|
|
||||
| Document | ordinary Markdown: prose, tables, links and fenced code |
|
||||
| Program | the same markers are executable: assignments, calls, returns |
|
||||
| Knowledge | frontmatter, links and generated catalog entries an agent can query |
|
||||
|
||||
The static site you are reading is generated from these files, so the examples are not screenshots. Run the same source and you get the same page.
|
||||
|
||||
Foreign v2 is a good example. Probe Node, then run the bound fence:
|
||||
|
||||
We first **node = [Check the formatting runtime](foreign.probe(lang="node"))** for the next step.
|
||||
|
||||
1. [ok](access(`node`, "ok"))
|
||||
We first **hello = [Format the native amount](foreign.run(code=`hi`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`hello`)**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="(node not found — install Node to run this cell)")**.
|
||||
|
||||
The same module also supports JSON calls, parallel fan-out, persistent kernels and an explicit state bridge. See [stdlib/foreign.mq.md](stdlib/foreign.mq.md) and the native-first Intl walkthrough in [features/19-foreign-view-cells.mq.md](features/19-foreign-view-cells.mq.md).
|
||||
|
||||
A view document is still a document. Named kernels and a cell order are ordinary bound tables:
|
||||
|
||||
```text
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | node | shared state |
|
||||
| 复核 | node | isolated state |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | write |
|
||||
| 计算指标 | 分析 | read |
|
||||
| 独立复核 | 复核 | validate |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
`marqdo view` consumes the foreign-owned `会话` handle and turns it into Run All, Step, per-cell kernels, a journal and a state panel. Without `会话`, cells are stateless one-shot runs. There is no separate interactive mode or command; `marqdo run` still executes the file as one program.
|
||||
|
||||
Documentation becomes knowledge when it can be discovered, verified and reused. OKF supplies the portable Markdown + YAML shape; EKC projects the repository into catalog layers L0–L4, a graph and an engineering preflight. The source `.mq.md` remains the only authority; generated artifacts are marked and rebuildable.
|
||||
|
||||
| Loop | Question |
|
||||
|---|---|
|
||||
| OKF | How do people and agents share a readable knowledge page? |
|
||||
| EKC | What existing capability, decision, constraint or failure should be reused before creating more? |
|
||||
| Preflight | REUSE → ADAPT → CREATE |
|
||||
|
||||
Read [features/20-okf-ekc.mq.md](features/20-okf-ekc.mq.md) for the concepts and commands.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
|
||||
Installation choices.
|
||||
|
||||
Install the interpreter (CLI) in any of these ways:
|
||||
|
||||
| Way | Notes |
|
||||
|------|------|
|
||||
| Ubuntu PPA | sudo add-apt-repository ppa:cflmy/marqdo then sudo apt install marqdo |
|
||||
| GitHub Releases | Prebuilt Windows / Linux packages from [releases](https://github.com/cflmy/marqdo/releases) |
|
||||
| From source | cargo build --release (needs a local Rust toolchain) |
|
||||
|
||||
Official extensions update independently of the CLI:
|
||||
|
||||
```text
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` tries CDN https://ext.marqdo.com first, then GitHub, then the proxy mirror. See [`features/05-extensions.mq.md`](features/05-extensions.mq.md).
|
||||
|
||||
|
||||
## greet
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| who | any | required | Recipient name inserted into the greeting |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; this function performs the described effects instead of returning business data |
|
||||
|
||||
When we meet a visitor `who`, we **print text="Welcome, `who`!"** and close with*None*.
|
||||
Executable
+17
@@ -0,0 +1,17 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 360" width="520" height="360" role="img" aria-label="function plot">
|
||||
<defs>
|
||||
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
||||
<path d="M 0 0 L 10 5 L 0 10 z" fill="#4b5563"/>
|
||||
</marker>
|
||||
</defs>
|
||||
<style>
|
||||
.grid { stroke: #e5e7eb; stroke-width: 1; }
|
||||
.axis { stroke: #4b5563; stroke-width: 1.5; }
|
||||
.tick { stroke: #4b5563; stroke-width: 1; }
|
||||
.curve { fill: none; stroke: #1f6feb; stroke-width: 2; }
|
||||
.pt { fill: #1f6feb; }
|
||||
.axis-label { font: 12px ui-sans-serif, system-ui, sans-serif; fill: #374151; font-weight: 600; }
|
||||
.tick-label { font: 10px ui-sans-serif, system-ui, sans-serif; fill: #6b7280; }
|
||||
</style>
|
||||
<line x1="36.00" y1="36" x2="36.00" y2="324" class="grid"/><line x1="110.67" y1="36" x2="110.67" y2="324" class="grid"/><line x1="185.33" y1="36" x2="185.33" y2="324" class="grid"/><line x1="260.00" y1="36" x2="260.00" y2="324" class="grid"/><line x1="334.67" y1="36" x2="334.67" y2="324" class="grid"/><line x1="409.33" y1="36" x2="409.33" y2="324" class="grid"/><line x1="484.00" y1="36" x2="484.00" y2="324" class="grid"/><line x1="36" y1="310.91" x2="484" y2="310.91" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="grid"/><line x1="36" y1="194.55" x2="484" y2="194.55" class="grid"/><line x1="36" y1="136.36" x2="484" y2="136.36" class="grid"/><line x1="36" y1="78.18" x2="484" y2="78.18" class="grid"/><line x1="36" y1="252.73" x2="484" y2="252.73" class="axis" marker-end="url(#arrow)"/><line x1="260.00" y1="324" x2="260.00" y2="36" class="axis" marker-end="url(#arrow)"/><text x="488.00" y="256.73" class="axis-label">x</text><text x="266.00" y="40.00" class="axis-label">y</text><line x1="36.00" y1="248.73" x2="36.00" y2="256.73" class="tick"/><text x="36.00" y="266.73" text-anchor="middle" class="tick-label">-3</text><line x1="110.67" y1="248.73" x2="110.67" y2="256.73" class="tick"/><text x="110.67" y="266.73" text-anchor="middle" class="tick-label">-2</text><line x1="185.33" y1="248.73" x2="185.33" y2="256.73" class="tick"/><text x="185.33" y="266.73" text-anchor="middle" class="tick-label">-1</text><line x1="334.67" y1="248.73" x2="334.67" y2="256.73" class="tick"/><text x="334.67" y="266.73" text-anchor="middle" class="tick-label">1</text><line x1="409.33" y1="248.73" x2="409.33" y2="256.73" class="tick"/><text x="409.33" y="266.73" text-anchor="middle" class="tick-label">2</text><line x1="484.00" y1="248.73" x2="484.00" y2="256.73" class="tick"/><text x="484.00" y="266.73" text-anchor="middle" class="tick-label">3</text><line x1="256.00" y1="310.91" x2="264.00" y2="310.91" class="tick"/><text x="252.00" y="310.91" text-anchor="end" dominant-baseline="middle" class="tick-label">-2</text><line x1="256.00" y1="194.55" x2="264.00" y2="194.55" class="tick"/><text x="252.00" y="194.55" text-anchor="end" dominant-baseline="middle" class="tick-label">2</text><line x1="256.00" y1="136.36" x2="264.00" y2="136.36" class="tick"/><text x="252.00" y="136.36" text-anchor="end" dominant-baseline="middle" class="tick-label">4</text><line x1="256.00" y1="78.18" x2="264.00" y2="78.18" class="tick"/><text x="252.00" y="78.18" text-anchor="end" dominant-baseline="middle" class="tick-label">6</text><text x="252.00" y="266.73" class="tick-label">0</text><path d="M 36.00 49.09 L 38.24 54.30 L 40.48 59.46 L 42.72 64.56 L 44.96 69.62 L 47.20 74.62 L 49.44 79.57 L 51.68 84.46 L 53.92 89.31 L 56.16 94.10 L 58.40 98.84 L 60.64 103.52 L 62.88 108.16 L 65.12 112.74 L 67.36 117.27 L 69.60 121.75 L 71.84 126.17 L 74.08 130.54 L 76.32 134.86 L 78.56 139.13 L 80.80 143.35 L 83.04 147.51 L 85.28 151.62 L 87.52 155.68 L 89.76 159.68 L 92.00 163.64 L 94.24 167.54 L 96.48 171.39 L 98.72 175.18 L 100.96 178.93 L 103.20 182.62 L 105.44 186.26 L 107.68 189.84 L 109.92 193.38 L 112.16 196.86 L 114.40 200.29 L 116.64 203.67 L 118.88 206.99 L 121.12 210.27 L 123.36 213.49 L 125.60 216.65 L 127.84 219.77 L 130.08 222.83 L 132.32 225.84 L 134.56 228.80 L 136.80 231.71 L 139.04 234.56 L 141.28 237.36 L 143.52 240.11 L 145.76 242.81 L 148.00 245.45 L 150.24 248.05 L 152.48 250.59 L 154.72 253.07 L 156.96 255.51 L 159.20 257.89 L 161.44 260.22 L 163.68 262.50 L 165.92 264.72 L 168.16 266.90 L 170.40 269.02 L 172.64 271.09 L 174.88 273.10 L 177.12 275.07 L 179.36 276.98 L 181.60 278.84 L 183.84 280.64 L 186.08 282.40 L 188.32 284.10 L 190.56 285.75 L 192.80 287.35 L 195.04 288.89 L 197.28 290.38 L 199.52 291.82 L 201.76 293.21 L 204.00 294.55 L 206.24 295.83 L 208.48 297.06 L 210.72 298.24 L 212.96 299.36 L 215.20 300.44 L 217.44 301.46 L 219.68 302.43 L 221.92 303.34 L 224.16 304.21 L 226.40 305.02 L 228.64 305.78 L 230.88 306.48 L 233.12 307.14 L 235.36 307.74 L 237.60 308.29 L 239.84 308.79 L 242.08 309.23 L 244.32 309.63 L 246.56 309.97 L 248.80 310.25 L 251.04 310.49 L 253.28 310.67 L 255.52 310.80 L 257.76 310.88 L 260.00 310.91 L 262.24 310.88 L 264.48 310.80 L 266.72 310.67 L 268.96 310.49 L 271.20 310.25 L 273.44 309.97 L 275.68 309.63 L 277.92 309.23 L 280.16 308.79 L 282.40 308.29 L 284.64 307.74 L 286.88 307.14 L 289.12 306.48 L 291.36 305.78 L 293.60 305.02 L 295.84 304.21 L 298.08 303.34 L 300.32 302.43 L 302.56 301.46 L 304.80 300.44 L 307.04 299.36 L 309.28 298.24 L 311.52 297.06 L 313.76 295.83 L 316.00 294.55 L 318.24 293.21 L 320.48 291.82 L 322.72 290.38 L 324.96 288.89 L 327.20 287.35 L 329.44 285.75 L 331.68 284.10 L 333.92 282.40 L 336.16 280.64 L 338.40 278.84 L 340.64 276.98 L 342.88 275.07 L 345.12 273.10 L 347.36 271.09 L 349.60 269.02 L 351.84 266.90 L 354.08 264.72 L 356.32 262.50 L 358.56 260.22 L 360.80 257.89 L 363.04 255.51 L 365.28 253.07 L 367.52 250.59 L 369.76 248.05 L 372.00 245.45 L 374.24 242.81 Line truncated
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 6.4 KiB |
Executable
+135
@@ -0,0 +1,135 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 欢迎使用 Marqdo
|
||||
description: 用户文档首页 — 代码即文档(中文版)
|
||||
导入:
|
||||
数学: lib/数学.mq.md
|
||||
外联: lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门「代码即文档,文档即代码」的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
|
||||
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).
|
||||
|
||||
想先打个招呼?`marqdo run` 会运行入口 `# main`。比如:**问候 谁="marqdo"**。名字里可以带空格:**问候 谁="marqdo user"**。
|
||||
|
||||
从这一版起,不必为了试用一个函数再包一层入口。`marqdo call` 直接运行文件里的某个函数,参数写在命令上。同一页仍然是给人读的文档。作用和价值写在 [features/22-函数调用.mq.md](features/22-函数调用.mq.md)。
|
||||
|
||||
除了这些基本面,标准库里还有表、时间、文本、文件、系统、数学、外联等。我特别想提数学和外联。
|
||||
|
||||
比方说,直接写一块公式,并用 TeX 注释标上变量名:
|
||||
|
||||
$$
|
||||
% marqdo: var=f
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
接着画出来:**_svg = 数学.绘图 formula=`f` var="x" min=-3 max=3**
|
||||
|
||||
外联则允许嵌一段别的语言。把`hi`绑成下面这样即可:
|
||||
|
||||
`hi` =
|
||||
```node
|
||||
console.log(new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"}).format(950));
|
||||
```
|
||||
|
||||
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。
|
||||
|
||||
一份文件,三个面。
|
||||
|
||||
| 面 | 是什么 |
|
||||
|---|---|
|
||||
| 文档 | 普通 Markdown:叙述、表格、链接、围栏代码 |
|
||||
| 程序 | 同一批标记可执行:赋值、调用、返回 |
|
||||
| 知识 | frontmatter、链接与生成的 catalog 条目,Agent 可查询 |
|
||||
|
||||
你正在读的静态站就是由这些文件生成的,所以示例不是截图。运行同一份源,会得到同一页。
|
||||
|
||||
外联 v2 是个好例子。先探测 Node,再运行绑定围栏:
|
||||
|
||||
我们先**node = [检查本地化展示所需的解释器](外联.探测(语言="node"))**,供下一步使用。
|
||||
|
||||
1. [ok](access(`node`, "ok"))
|
||||
我们先**问候 = [通过 Intl 展示原生金额](外联.运行(代码=`hi`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`问候`)**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="(未找到 node — 安装 Node 后可运行此单元)")**。
|
||||
|
||||
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 [stdlib/外联.mq.md](stdlib/外联.mq.md) 与原生分析与 Intl 示例 [features/19-外联视图单元.mq.md](features/19-外联视图单元.mq.md)。
|
||||
|
||||
view 仍然是一篇文档。命名内核与单元顺序就是普通绑定表:
|
||||
|
||||
```text
|
||||
`分析内核` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | node | 共享状态 |
|
||||
| 复核 | node | 隔离状态 |
|
||||
|
||||
`分析单元` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 写入 |
|
||||
| 计算指标 | 分析 | 读取 |
|
||||
| 独立复核 | 复核 | 校验 |
|
||||
|
||||
`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`
|
||||
```
|
||||
|
||||
`marqdo view` 消费 foreign 拥有的 `会话` 句柄,变成 Run All、Step、每单元内核、journal 与状态面板。没有 `会话` 时,单元是无状态的一次性运行。没有单独的交互模式或命令;`marqdo run` 仍然把文件当单个程序运行。
|
||||
|
||||
文档能被发现、验证和复用时,才成为知识。OKF 提供可移植的 Markdown + YAML 形态;EKC 把仓库投影成 catalog L0–L4、图与工程 preflight。源 `.mq.md` 始终是唯一权威,生成物有标记、可重建。
|
||||
|
||||
| 循环 | 问题 |
|
||||
|---|---|
|
||||
| OKF | 人和 Agent 如何共享一页可读知识? |
|
||||
| EKC | 创建之前,应该复用哪些已有能力、决策、约束与失败? |
|
||||
| Preflight | REUSE → ADAPT → CREATE |
|
||||
|
||||
概念与命令见 [features/20-OKF与EKC.mq.md](features/20-OKF与EKC.mq.md)。
|
||||
|
||||
最后,再次欢迎你,尽情体验 marqdo 吧!
|
||||
|
||||
安装方式。
|
||||
|
||||
解释器(CLI)任选其一:
|
||||
|
||||
| 方式 | 说明 |
|
||||
|------|------|
|
||||
| Ubuntu PPA | sudo add-apt-repository ppa:cflmy/marqdo 后 sudo apt install marqdo |
|
||||
| GitHub Releases | [releases](https://github.com/cflmy/marqdo/releases) 下载 Windows / Linux 预编译包 |
|
||||
| 源码 | cargo build --release(需本机 Rust) |
|
||||
|
||||
官方扩展与 CLI 可分开更新。安装扩展:
|
||||
|
||||
```text
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
`ext add` 下载顺序:CDN https://ext.marqdo.com → GitHub → proxy 镜像。详见本站 [`features/05-扩展.mq.md`](features/05-扩展.mq.md)。
|
||||
|
||||
|
||||
## 问候
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| 谁 | any | 必填 | 要显示在问候中的称呼 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;本函数通过上述操作产生效果,不返回业务数据。 |
|
||||
|
||||
见到访客`谁`时,我们 **打印 内容="欢迎,`谁`!"**,然后收束为*None*。
|
||||
Generated
-7
@@ -1,7 +0,0 @@
|
||||
# This file is automatically @generated by Cargo.
|
||||
# It is not intended for manual editing.
|
||||
version = 4
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "0.1.0"
|
||||
-10
@@ -1,10 +0,0 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.1.0"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
[[bin]]
|
||||
name = "marqdo"
|
||||
path = "src/marqdo.rs"
|
||||
@@ -0,0 +1,34 @@
|
||||
# 用户文档(可执行 · 可下载 · 中英双语)
|
||||
|
||||
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
|
||||
|
||||
**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
|
||||
|
||||
| 路径 | 内容 |
|
||||
|------|------|
|
||||
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
|
||||
| [`structure/`](structure/) | 基本结构 |
|
||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
| [`features/19-foreign-view-cells.mq.md`](features/19-foreign-view-cells.mq.md) / [`19-外联视图单元.mq.md`](features/19-外联视图单元.mq.md) | 外联 v2 完整 Python 示例:probe / JSON call / 并行 / 持久内核 / 状态桥 / view 单元 |
|
||||
| [`features/20-okf-ekc.mq.md`](features/20-okf-ekc.mq.md) / [`20-OKF与EKC.mq.md`](features/20-OKF与EKC.mq.md) | 代码即文档、文档即知识:OKF 形态与 EKC 工程知识编译器 |
|
||||
| [`features/21-persistence.mq.md`](features/21-persistence.mq.md) / [`21-持久化.mq.md`](features/21-持久化.mq.md) | 外联结果持久化:静态快照与 writeback |
|
||||
| [`features/22-call.mq.md`](features/22-call.mq.md) / [`22-函数调用.mq.md`](features/22-函数调用.mq.md) | `marqdo call`:同一份文档按函数执行,知识可以直接当工具 |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent`、`ext/web`、`ext/quantum`、`ext/linalg` — 见 `features/05-*.mq.md`、`06-*.mq.md`、`07-linalg.mq.md` / `07-线性代数.mq.md` 与 `doc/design/ext-*.md`。
|
||||
|
||||
中层标准库(Mid):`08`–`12`(re/encoding · path/fs · hash/secrets · csv/text · list/cli;及对应中文页)。
|
||||
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`。
|
||||
|
||||
开发文档在 [`doc/`](../doc/)。
|
||||
|
||||
## 浏览与生成 HTML
|
||||
|
||||
```bash
|
||||
cargo run -- view public
|
||||
cargo run -- view output public -o public
|
||||
```
|
||||
|
||||
详见 [user-site.md](../doc/design/user-site.md)。
|
||||
@@ -1,91 +0,0 @@
|
||||
---
|
||||
title: Marqdo主分支开发记录
|
||||
date: 2026-08-11
|
||||
author: pingan
|
||||
---
|
||||
|
||||
## 前言
|
||||
在经过一周多的ai疯狂开发之后,尽管marqdo已经做出了并拥有了许多非常良好的特性,作者确逐渐感到非常的不安,
|
||||
这种不安来自于崩塌感,作者不知道什么时候,ai就会更改关键的定义,导致突然的崩塌,在开发智能体拓展库的时候作者还尚未有这种感觉,但是在网络拓展库,这种不安定感几乎席卷了作者的全部身心。
|
||||
|
||||
必须承认,ai在没有经过大量训练就撰写一门崭新的语法,定义一些它完全没有接触过的东西对于ai还是太困难了,ai并不能通过我的监督,真正的理解marqdo代码即文档的设计思路,所以,尽管非常的遗憾,作者还是决定回归古法编程,还是手搓代码吧,尽管这意味着marqdo很难赶上ai的浪潮了。
|
||||
|
||||
marqdo的设计初衷很是简单,这就不是一门设计给程序员的语言,哪个程序员会用markdown表格来表示集合呢?不会的,这太过繁复了,但是ai可以,这就使得过去编程语言的范式变得不是那么重要了。
|
||||
|
||||
自然如果只是为了易读性,marqdo并没有完全的开发必要,重点在于对md的支持,作者必须承认谷歌提出的OKF规范,把markdown这种文件格式放到了一个极高的位置,这意味着,可执行的知识体系,如果能做到,为什么不试试?
|
||||
|
||||
此外,jupyter notebook笔记本体积太大不利于管理的问题也是存在的,作者就在想,markdown支持代码块的插入,这个代码如果可以直接执行并放回,这不就是最好的jupyter替代品吗?事实上,在main分支的marqdo已经实现了这个功能,但是还不够好,作者要把marqdo真正做成一门科学计算的顶级语言。
|
||||
|
||||
最后是数学公式的支持,公式库需要能够自动的渲染,高可读,还要能够自动的画图,自动的完成诸多内容,让可执行=正确,让ai支持数学推理不再困难。
|
||||
|
||||
最后,2026年8月11日,我预祝未来的自己,开发成功。
|
||||
|
||||
## 开发
|
||||
|
||||
### Marqdo上下文无关文法
|
||||
|
||||
file -> "---" metadata "---" content ;
|
||||
|
||||
metadata -> file_information |
|
||||
import_lib_name ;
|
||||
|
||||
content -> comment |
|
||||
code_body ;
|
||||
|
||||
comment -> comment_content ;
|
||||
|
||||
code_body -> class |
|
||||
function|
|
||||
code|
|
||||
$formula$|$$formula$$|\[formula\]|
|
||||
```code_block_type
|
||||
code_block
|
||||
```;
|
||||
|
||||
class -> # class_name code_body |
|
||||
# class_name => parent_class_name code_body ;
|
||||
|
||||
function -> function_header param_list body return_stmt ;
|
||||
|
||||
function_header -> ## identifier |
|
||||
### identifier |
|
||||
#### identifier ;
|
||||
|
||||
param_list -> + identifier ;
|
||||
|
||||
body -> statement |
|
||||
branch |
|
||||
loop ;
|
||||
|
||||
return_stmt -> ** statement ** ;
|
||||
|
||||
<!--the number of # stand for the level of function -->
|
||||
|
||||
code -> 1. branch |
|
||||
- loop |
|
||||
statement ;
|
||||
|
||||
<!--Ordered lists represent branch, unordered lists represent loop-->
|
||||
|
||||
branch -> statement ;
|
||||
|
||||
loop -> statement ;
|
||||
|
||||
statement -> > call |
|
||||
literal|
|
||||
`var_value_name`|
|
||||
list and dict|
|
||||
"str"|
|
||||
*statement_without_any_marker*;
|
||||
|
||||
<!--here we use markdown table to stand for list and dict-->
|
||||
|
||||
call -> function_name args;
|
||||
|
||||
literal -> literal_code as other code;
|
||||
|
||||
formula -> latex math code;
|
||||
|
||||
code_block_type -> code_block's code type;
|
||||
|
||||
code_block -> code of a code_block;
|
||||
Executable
+19
@@ -0,0 +1,19 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Phase I — tree-walk interpreter
|
||||
description: Lex · parse · check · tree-walk end to end
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Milestone: Phase I (tree-walk).
|
||||
|
||||
Pipeline: load → line classify → recursive-descent parse → semantic check → tree-walk eval. No Flex/Bison.
|
||||
|
||||
This page runs as a program — documentation is executable:
|
||||
|
||||
We now **[Display this step's result](> print text="Phase I: tree-walk interpreter is live.")**.
|
||||
Executable
+19
@@ -0,0 +1,19 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 第一阶段 — 树遍历解释器
|
||||
description: 词法 · 语法 · 语义 · 树遍历已贯通
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
里程碑:第一阶段(树遍历)。
|
||||
|
||||
流水线:加载 → 行分类 → 递归下降语法 → 语义检查 → 树遍历执行。实现不用 Flex/Bison。
|
||||
|
||||
本页本身即可运行,证明「文档即程序」已落地:
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="第一阶段:树遍历解释器已就绪。")**。
|
||||
Executable
+23
@@ -0,0 +1,23 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Bytecode backend
|
||||
description: `--backend bytecode` shares semantics with tree-walk
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Milestone: bytecode prototype.
|
||||
|
||||
The same `.mq.md` runs on tree-walk or the bytecode VM:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
Output matches on both backends:
|
||||
|
||||
We now **[Display this step's result](> print text="Bytecode backend: same program, alternate engine.")**.
|
||||
Executable
+23
@@ -0,0 +1,23 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 字节码后端
|
||||
description: `--backend bytecode` 与树遍历共用语义
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
里程碑:字节码原型。
|
||||
|
||||
同一套 `.mq.md` 可用树遍历或字节码 VM:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
两种后端输出一致:
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="字节码后端:同一程序,另一引擎。")**。
|
||||
Executable
+40
@@ -0,0 +1,40 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: view and the user docs site
|
||||
description: Local browse and static export from the interpreter
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Version 2.6.0 keeps action descriptions in the sentence and moves their implementation to side notes. Empty parentheses explicitly mark missing logic. Multiple actions and returns keep their original prose, while ordinary links remain navigation. On compact screens, native disclosures keep the implementation readable even without JavaScript.
|
||||
|
||||
Executable knowledge now presents inputs, returns, effects, dependencies and separate verification facts. Technical identities and digests stay folded. Source explanations are distinct from captured results; a pure effect summary or linked source is not proof that a program ran or its content was verified.
|
||||
|
||||
The reader introduced in 2.5.1: `marqdo view` and `view output` share a warm paper reader with a new
|
||||
Marqdo logo, serif document text, botanical ornaments, navigation, search and a
|
||||
floating action toolbar. Wide screens place real execution notes in the margins;
|
||||
compact screens keep them below the corresponding paragraph. Click a note to
|
||||
inspect its full captured value. Call and loop frame selectors remain available.
|
||||
|
||||
Static exports embed decorations, KaTeX and math fonts for offline reading. The
|
||||
play button runs the document in live view; static pages retain their captured
|
||||
results and explain how to start a live view. Ordinary document reruns update
|
||||
prose, bindings and notes from the same execution capture.
|
||||
|
||||
Annotations follow the exact source span across calls and loop iterations. Flowing
|
||||
curves and staggered margin notes avoid source text and neighboring connections.
|
||||
The floating toolbar labels its actions: refresh, settings, run, clear and more.
|
||||
|
||||
Local: `marqdo view public`
|
||||
|
||||
Static export: `marqdo view output public -o public`
|
||||
|
||||
Browse Structure keeps narration, highlights executable markers, and attaches
|
||||
run results (values, taken branch arms, call/loop frames). The same render path
|
||||
builds this user docs site; CI publishes to `gh-pages`.
|
||||
|
||||
We now **[Display this step's result](> print text="Docs site: generated by the Marqdo interpreter, not hand-written HTML.")**.
|
||||
Executable
+35
@@ -0,0 +1,35 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: view 与用户文档站
|
||||
description: 本地浏览与静态导出由解释器生成
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
版本 2.6.0 将动作说明留在句子里,实际实现引到侧注;空圆括号明确提示待补逻辑。同一句话可以保留多个调用与返回,普通链接仍是导航。窄屏使用原生可展开详情,没有 JavaScript 也能查看实现。
|
||||
|
||||
可执行知识先展示输入、返回、调用边界、依赖和分别列出的验证依据,技术身份与摘要按需展开。源码说明与运行捕获有不同含义;pure、来源关联或构造配置都不能被当作已运行或内容已验证的证据。
|
||||
|
||||
沿用 2.5.1 的阅读底座:`marqdo view` 与 `view output` 共用暖白金色阅读界面,新 Marqdo 标志、
|
||||
衬线正文、花枝装饰、导航搜索与底部悬浮工具栏。宽屏将真实执行结果沿左右页边引出,
|
||||
窄屏将标注放回对应段落下方;点击标注可查看完整捕获值,调用帧和循环轮次仍可切换。
|
||||
|
||||
静态导出内嵌装饰素材、KaTeX 与数学字体,断网也能阅读公式。播放按钮在实时 view 中
|
||||
运行文档;静态页面保留导出结果,并提示如何启动实时 view。普通文档重跑后,正文、
|
||||
变量和执行标注使用同一次执行捕获同步刷新。
|
||||
|
||||
执行标注跨调用帧与循环轮次精确对应源码区间。连续曲线与错落标注会避让正文和相邻连线;
|
||||
底部工具栏显示“刷新、设置、运行、清理、更多”,深浅色配色保持一致。
|
||||
|
||||
本地浏览:`marqdo view public`
|
||||
|
||||
静态导出:`marqdo view output public -o public`
|
||||
|
||||
Browse Structure 保真叙述、高亮可执行标记,并挂载运行结果(变量值、分支命中臂、调用/循环帧)。
|
||||
用户站与 live view 同源渲染;CI 发布到 `gh-pages`。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="文档站:由 Marqdo 解释器生成,不是手写 HTML。")**。
|
||||
Executable
+17
@@ -0,0 +1,17 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Objects and methods
|
||||
description: Sharp heading is a type; deeper headings are functions or methods
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
In Marqdo, a single sharp (#) defines an object / type constructor. Double sharp and deeper (## …) define free functions or methods. Constructing an object yields a map handle tagged with _type. Call methods with backtick object, then dot, then method name.
|
||||
|
||||
See doc/design/objects.md. Example gold: tests/structure/object-handle.mq.md. Official ext/llm and ext/agent use this pattern.
|
||||
|
||||
We now **[Display this step's result](> print text="objects-ok")**.
|
||||
Executable
+17
@@ -0,0 +1,17 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 对象与方法
|
||||
description: 一级标题是类型;更深标题是函数或方法
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
Marqdo 中,单个井号(#)定义对象 / 类型构造体;二级及以上(## …)定义自由函数或方法。构造得到带 _type 标记的 map 句柄。方法调用形如:反引号对象、点、方法名。
|
||||
|
||||
详见 doc/design/objects.md。金样例:tests/structure/object-handle.mq.md。官方 ext/llm 与 ext/agent 使用同一模式。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="对象就绪")**。
|
||||
Executable
+54
@@ -0,0 +1,54 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Official extensions (ext/)
|
||||
description: Optional packages — not stdlib
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
ext/ holds official optional extensions. They are not part of lib/. Resolve via `~/.marqdo/ext`, MARQDO_EXT, ./ext, or ext/ next to the binary.
|
||||
|
||||
Install (v0.2+):
|
||||
|
||||
```text
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
marqdo ext add linalg
|
||||
```
|
||||
|
||||
`ext add` downloads L1 sources and prebuilt natives when available. Order: CDN https://ext.marqdo.com → GitHub Releases → proxy mirror. Pack SemVer is `ext/VERSION` and may differ from the CLI.
|
||||
|
||||
Rebuild natives locally only when developing plugins:
|
||||
|
||||
```text
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
cargo build --release -p marqdo_plugin_quantum
|
||||
cargo build --release -p marqdo_plugin_linalg
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
Packages (not Markdown list markers — those are loops in Marqdo):
|
||||
|
||||
ext/llm — OpenAI-compatible chat. Design: doc/design/ext-llm.md
|
||||
|
||||
ext/agent — agent framework + native plugin. Design: doc/design/ext-agent.md
|
||||
|
||||
ext/web provides Documents/Endpoints, recursive View, document-head and request resources. Decompose layout to Markdown or native-control leaves; data, authentication and transport belong to ext/data, ext/security and ext/net. Follow examples/web-site/index.mq.md and examples/web-net-site/index.mq.md for complete workflows. Browser interaction uses Marqdo clients and the official WASM bridge. Development, builds and real acceptance run through marqdo call in skills/marqdo-dev/index.mq.md; the current author contract starts at ext/web/index.mq.md.
|
||||
|
||||
ext/quantum — circuits, draw, noise, formula matrix custom gates, Q7 density/viz, Q8 themed SVG (`theme=dark|light|bw`). Design: doc/design/ext-quantum.md · doc/design/ext-quantum-viz-style.md
|
||||
|
||||
Installer: marqdo ext list / add / remove — doc/design/ext-cli.md
|
||||
|
||||
Native plugins: lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
|
||||
|
||||
We now **[Display this step's result](> print text="ext-ok")**.
|
||||
Executable
+54
@@ -0,0 +1,54 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 官方扩展(ext/)
|
||||
description: 可选包 — 不是标准库
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
ext/ 存放官方可选扩展,不属于 lib/。解析顺序:`~/.marqdo/ext`、MARQDO_EXT、./ext、或可执行文件旁的 ext/。
|
||||
|
||||
安装(v0.2+):
|
||||
|
||||
```text
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
marqdo ext add linalg
|
||||
```
|
||||
|
||||
`ext add` 会下载 L1 与预编译 native(若有)。下载顺序:CDN https://ext.marqdo.com → GitHub Releases → proxy 镜像。扩展包版本见 `ext/VERSION`,可与 CLI 分开发版。
|
||||
|
||||
带原生插件的包若需本地重编:
|
||||
|
||||
```text
|
||||
cargo build --release -p marqdo_plugin_agent
|
||||
cargo build --release -p marqdo_plugin_quantum
|
||||
cargo build --release -p marqdo_plugin_linalg
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
扩展包(勿用 Markdown `-` 列表:在 Marqdo 里 `-` 是循环):
|
||||
|
||||
ext/llm(大模型)— OpenAI 兼容聊天。设计:doc/design/ext-llm.md
|
||||
|
||||
ext/agent(智能体)— 智能体框架 + 原生插件。设计:doc/design/ext-agent.md
|
||||
|
||||
ext/web(网页)提供 Document/Endpoint、递归 View、页头和请求资源。布局拆到 Markdown 或原生控件叶子,数据、鉴权与运输分别归 ext/data、ext/security、ext/net。完整实践见 examples/web-site-zh/index.mq.md 与 examples/web-net-site-zh/index.mq.md;浏览器交互通过 Marqdo 客户端及官方 WASM 桥完成。开发、构建和真实验收入口为 skills/marqdo-dev/index.mq.md,操作使用 marqdo call;当前作者契约见 ext/web/网页/索引.mq.md。
|
||||
|
||||
ext/quantum(量子)— 电路、绘图、噪声、公式矩阵自定义门、Q7 密度/高级图、Q8 主题 SVG(`主题=dark|light|bw`)。设计:doc/design/ext-quantum.md · doc/design/ext-quantum-viz-style.md
|
||||
|
||||
安装器:marqdo ext list / add / remove — doc/design/ext-cli.md
|
||||
|
||||
通用原生插件:lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="扩展就绪")**。
|
||||
Executable
+14
@@ -0,0 +1,14 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="152" height="180" viewBox="0 0 152.0 180.0" data-theme="dark" role="img" aria-label="measurement probabilities"><defs>
|
||||
<linearGradient id="mq-bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#0a0e14"/>
|
||||
<stop offset="55%" stop-color="#141c28"/>
|
||||
<stop offset="100%" stop-color="#0a0e14"/>
|
||||
</linearGradient>
|
||||
<filter id="mq-glow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="2.2" result="b"/>
|
||||
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<filter id="mq-soft" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="1.5" stdDeviation="1.8" flood-color="#4c6fff" flood-opacity="0.35"/>
|
||||
</filter>
|
||||
</defs><rect width="152.0" height="180.0" rx="14" fill="url(#mq-bg)"/><line x1="36" y1="144" x2="136" y2="144" stroke="#7d8fa3" stroke-width="1.2"/><line x1="36" y1="24" x2="36" y2="144" stroke="#7d8fa3" stroke-width="1.2"/><text x="8" y="28" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#e8eef6">1</text><text x="8" y="148" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#e8eef6">0</text><rect x="40" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#5b7cfa" stroke="#f0f5ff" stroke-width="1" filter="url(#mq-soft)"/><text x="58" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#e8eef6">000</text><text x="58" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#93a4b8">0.50</text><rect x="88" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#5b7cfa" stroke="#f0f5ff" stroke-width="1" filter="url(#mq-soft)"/><text x="106" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#e8eef6">111</text><text x="106" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#93a4b8">0.50</text></svg>
|
||||
|
After Width: | Height: | Size: 2.0 KiB |
Executable
+1
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="196" height="192" viewBox="0 0 196.0 192.0" role="img" aria-label="gate matrix heatmap"><text x="8" y="18" font-family="ui-monospace,Menlo,monospace" font-size="12" fill="#1a1a1a">H matrix</text><text x="8" y="67.6" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">0</text><text x="72" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">0</text><rect x="36" y="28" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="72" y="67.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><rect x="108" y="28" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="144" y="67.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><text x="8" y="139.60000000000002" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">1</text><text x="144" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">1</text><rect x="36" y="100" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="72" y="139.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><rect x="108" y="100" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="144" y="139.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">-0.707</text></svg>
|
||||
|
After Width: | Height: | Size: 1.6 KiB |
Executable
+39
@@ -0,0 +1,39 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Quantum circuits (ext/quantum)
|
||||
description: Official quantum simulator — tables, gates, Q7 density, Q8 themed SVG
|
||||
import:
|
||||
quantum: ext/quantum/circuit/index.mq.md
|
||||
gate: ext/quantum/gate/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Optional package (not stdlib). Install: `marqdo ext add quantum` (or build `marqdo_plugin_quantum`).
|
||||
|
||||
GHZ (3 qubits): H on q0, then CX 0→1 and 0→2. Ideal |000⟩ / |111⟩ each ≈ 1/2.
|
||||
|
||||
Q7: Bell density, partial trace, Schmidt, `draw kind=hinton` / qsphere — `examples/quantum-entanglement/`.
|
||||
|
||||
Q8: `draw theme="dark"|"light"|"bw"` (default dark lab look) on circuit / probs / bloch. Rebuild plugin then `ext add` so view loads the new native lib.
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
| 3 | CX | 0,2 |
|
||||
|
||||
We first **qc = [Compute qc](quantum.circuit(qubits=3, steps=`steps`))** for the next step.
|
||||
We first **p = [Compute p](> `qc`.probabilities)** for the next step.
|
||||
We first **_ = [Compute _](> `qc`.draw kind="probs" theme="dark")** for the next step.
|
||||
We first **H = [Compute H](gate.gate(name="H"))** for the next step.
|
||||
We first **__ = [Compute __](> `H`.draw kind="matrix")** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text=`p`)**.
|
||||
We now **[Display this step's result](> print text="quantum-feature-ok")**.
|
||||
Executable
+14
@@ -0,0 +1,14 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="152" height="180" viewBox="0 0 152.0 180.0" data-theme="dark" role="img" aria-label="measurement probabilities"><defs>
|
||||
<linearGradient id="mq-bg" x1="0" y1="0" x2="1" y2="1">
|
||||
<stop offset="0%" stop-color="#0a0e14"/>
|
||||
<stop offset="55%" stop-color="#141c28"/>
|
||||
<stop offset="100%" stop-color="#0a0e14"/>
|
||||
</linearGradient>
|
||||
<filter id="mq-glow" x="-40%" y="-40%" width="180%" height="180%">
|
||||
<feGaussianBlur stdDeviation="2.2" result="b"/>
|
||||
<feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge>
|
||||
</filter>
|
||||
<filter id="mq-soft" x="-20%" y="-20%" width="140%" height="140%">
|
||||
<feDropShadow dx="0" dy="1.5" stdDeviation="1.8" flood-color="#4c6fff" flood-opacity="0.35"/>
|
||||
</filter>
|
||||
</defs><rect width="152.0" height="180.0" rx="14" fill="url(#mq-bg)"/><line x1="36" y1="144" x2="136" y2="144" stroke="#7d8fa3" stroke-width="1.2"/><line x1="36" y1="24" x2="36" y2="144" stroke="#7d8fa3" stroke-width="1.2"/><text x="8" y="28" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#e8eef6">1</text><text x="8" y="148" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#e8eef6">0</text><rect x="40" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#5b7cfa" stroke="#f0f5ff" stroke-width="1" filter="url(#mq-soft)"/><text x="58" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#e8eef6">000</text><text x="58" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#93a4b8">0.50</text><rect x="88" y="83.99999999999999" width="36" height="60.000000000000014" rx="4" fill="#5b7cfa" stroke="#f0f5ff" stroke-width="1" filter="url(#mq-soft)"/><text x="106" y="162" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="11" fill="#e8eef6">111</text><text x="106" y="78.99999999999999" text-anchor="middle" font-family="ui-monospace,Menlo,Consolas,monospace" font-size="10" fill="#93a4b8">0.50</text></svg>
|
||||
|
After Width: | Height: | Size: 2.0 KiB |
Executable
+1
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="196" height="192" viewBox="0 0 196.0 192.0" role="img" aria-label="gate matrix heatmap"><text x="8" y="18" font-family="ui-monospace,Menlo,monospace" font-size="12" fill="#1a1a1a">H matrix</text><text x="8" y="67.6" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">0</text><text x="72" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">0</text><rect x="36" y="28" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="72" y="67.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><rect x="108" y="28" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="144" y="67.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><text x="8" y="139.60000000000002" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">1</text><text x="144" y="22" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="10" fill="#666">1</text><rect x="36" y="100" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="72" y="139.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">0.707</text><rect x="108" y="100" width="72" height="72" fill="rgb(107,116,247)" stroke="#1a1a1a" stroke-width="0.8"/><text x="144" y="139.6" text-anchor="middle" font-family="ui-monospace,Menlo,monospace" font-size="9" fill="#fff">-0.707</text></svg>
|
||||
|
After Width: | Height: | Size: 1.6 KiB |
Executable
+41
@@ -0,0 +1,41 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 量子电路(ext/quantum)
|
||||
description: 官方量子模拟 — 表、门、Q7 密度与高级图、Q8 主题 SVG
|
||||
导入:
|
||||
量子: ext/quantum/量子/电路/索引.mq.md
|
||||
门: ext/quantum/量子/门/索引.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
可选扩展(非 stdlib)。安装:`marqdo ext add quantum`(或编译 `marqdo_plugin_quantum`)。
|
||||
|
||||
中文面在同包 `ext/quantum/量子/`(根 skill:`索引.mq.md`),与英文模块树并列、不混排 API。
|
||||
|
||||
GHZ(3 比特):q0 哈达玛,再控非 0→1、0→2。理想 |000⟩ / |111⟩ 各约 1/2。
|
||||
|
||||
Q7:密度 / 部分迹 / Schmidt / `绘图 种类=hinton` 等 — `examples/quantum-entanglement/`。
|
||||
|
||||
Q8:`绘图 主题="dark"|"light"|"bw"`(默认 dark 科技感)作用于电路 / 概率 / 布洛赫。改插件后须再 `ext add`,view 才会加载新 `.so`。
|
||||
|
||||
`步骤` =
|
||||
|
||||
| 步 | 门 | 比特 |
|
||||
|----|----|------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
| 3 | CX | 0,2 |
|
||||
|
||||
我们先**qc = [计算并保存 qc](量子.电路(比特数=3, 步骤=`步骤`))**,供下一步使用。
|
||||
我们先**p = [计算并保存 p](> `qc`.概率)**,供下一步使用。
|
||||
我们先**_ = [计算并保存 _](> `qc`.绘图 种类="probs" 主题="dark")**,供下一步使用。
|
||||
我们先**H = [计算并保存 H](门.门(名="H"))**,供下一步使用。
|
||||
我们先**__ = [计算并保存 __](> `H`.绘图 种类="matrix")**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`p`)**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="量子特性-ok")**。
|
||||
Executable
+42
@@ -0,0 +1,42 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: How to write a linear-algebra formula document
|
||||
description: ext/linalg formula-doc — declare, infix, run-implies-correct
|
||||
import:
|
||||
la: ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# Formula documents with ext/linalg
|
||||
|
||||
|
||||
Not stdlib. Install: `marqdo ext add linalg` (or build `marqdo_plugin_linalg`).
|
||||
|
||||
*Idea:* if the `.mq.md` runs and the asserted form matches, the identity holds under the library rules. Algebra reads like a lecture; `factorize` / `lstsq` / `draw` stay explicit calculation steps.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Declare symbols in a table, multiply, transpose — `T_ascii` is one-step display (auto-simplify).
|
||||
|
||||
`shapes` =
|
||||
|
||||
| @ | name | rows | cols |
|
||||
|---|------|------|------|
|
||||
| 1 | A | 2 | 3 |
|
||||
| 2 | B | 3 | 2 |
|
||||
|
||||
We first **env = [Compute env](la.declare(table=`shapes`))** for the next step.
|
||||
We first **A = [A](access(`env`, "A"))** for the next step.
|
||||
We first **B = [B](access(`env`, "B"))** for the next step.
|
||||
We first **P = (`A` * `B`)** for the next step.
|
||||
We first **t = [Compute t](> `P`.T_ascii)** for the next step.
|
||||
We now **[Display this step's result](> print text=`t`)**.
|
||||
1. `t` == "B^T*A^T"
|
||||
We now **[Display this step's result](> print text="formula-doc-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="formula-doc-fail")**.
|
||||
|
||||
We now **[Display this step's result](> print text="see-examples-linalg-transpose")**.
|
||||
Executable
+45
@@ -0,0 +1,45 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 如何写线性代数公式文档
|
||||
description: ext/linalg 公式文档面 — 声明、中缀、跑通即正确
|
||||
导入:
|
||||
la: ext/linalg/线性代数.mq.md
|
||||
---
|
||||
|
||||
# 用 ext/linalg 写公式文档
|
||||
|
||||
可选扩展(非 stdlib)。安装:`marqdo ext add linalg`(中文 id:`线性代数`)。
|
||||
|
||||
*思想:* `.mq.md` 能跑通且断言的规范形一致,则在库规则下该恒等式成立。代数叙述像讲义;`分解` / `最小二乘` / `绘图` 才是显式计算步骤。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
这里讨论符号表达式的形状,而不是对矩阵中的每个数值做计算。先声明 A 为两行三列、B 为三行两列,乘积才具有合法的二行二列形状;转置时两个因子的顺序交换,得到 B^T*A^T。输出相符只证明本例在库定义的规范化规则下成立,不意味着任意数值近似或未声明符号也会被接受。
|
||||
|
||||
阅读时先看形状表,再看乘法和转置的动作说明。公式库需要对应的原生插件,缺少依赖时应先安装 linalg;不要把插件加载错误当成恒等式不成立。此例不读取或写入业务文件,也不把输出字符串重新执行成代码。需要实际矩阵分解时,沿文件开头的导入路径阅读分解函数的独立契约。
|
||||
|
||||
用表声明符号,再乘与转置 — `转置文本` 一步展示(默认化简)。
|
||||
|
||||
`形状` =
|
||||
|
||||
| @ | 名 | 行 | 列 |
|
||||
|---|----|----|----|
|
||||
| 1 | A | 2 | 3 |
|
||||
| 2 | B | 3 | 2 |
|
||||
|
||||
我们先**环境 = [声明带有行列约束的符号环境](la.声明(表=`形状`))**,供下一步使用。
|
||||
我们先**A = [A](access(`环境`, "A"))**,供下一步使用。
|
||||
我们先**B = [B](access(`环境`, "B"))**,供下一步使用。
|
||||
我们先**P = (`A` * `B`)**,供下一步使用。
|
||||
我们先**t = [取得当前步骤的转置公式或随机令牌](> `P`.转置文本)**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`t`)**。
|
||||
1. `t` == "B^T*A^T"
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="formula-doc-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="formula-doc-fail")**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="see-examples-linalg-transpose")**。
|
||||
Executable
+30
@@ -0,0 +1,30 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — regex and encoding
|
||||
description: lib/re + lib/encoding without plugins (Mid M1)
|
||||
import:
|
||||
re: lib/re.mq.md
|
||||
enc: lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# Regex and encoding in lib/
|
||||
|
||||
|
||||
Mid-tier stdlib: everyday primitives stay in `lib/`, not ABI plugins.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **ok = [Compute ok](re.is_match(text="user@example.com", pattern="^[^@]+@[^@]+$"))** for the next step.
|
||||
We first **tok = [Compute tok](enc.base64_encode(text="marqdo"))** for the next step.
|
||||
We first **hex = [Compute hex](enc.hex_encode(text="ok"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`ok`)**.
|
||||
We now **[Display this step's result](> print text=`tok`)**.
|
||||
We now **[Display this step's result](> print text=`hex`)**.
|
||||
1. `ok`
|
||||
We now **[Display this step's result](> print text="mid-m1-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="mid-m1-fail")**.
|
||||
Executable
+33
@@ -0,0 +1,33 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 正则与编解码
|
||||
description: lib/正则 + lib/编码,无需插件(中层 M1)
|
||||
导入:
|
||||
正则: lib/正则.mq.md
|
||||
编码: lib/编码.mq.md
|
||||
---
|
||||
|
||||
# 标准库中的正则与编解码
|
||||
|
||||
中层标准库:日常原语进 `lib/`,不必 ABI 插件。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
本例从固定的邮箱样式文本开始:正则只检查是否符合给定模式,并不是邮件地址真实性验证。随后把普通 UTF-8 文本分别编码成 Base64 和十六进制,以展示三种返回值的区别:匹配结果是布尔值,两种编码结果是文本。编码后的文本可以继续传给解码函数,还原原始字节或文字。
|
||||
|
||||
编码不具有保密作用,也不会替调用方校验邮箱能否接收消息。这里没有网络请求、文件读写或插件安装;所有输入都来自正文中的字面值。实际接入用户输入时要保留模式与编码函数的错误诊断,不能用空字符串代替失败。最后的标记只检查本例的匹配分支,不能代替编码往返和非法输入的验收。
|
||||
|
||||
我们先**ok = [检查给定模式是否匹配邮箱样式](正则.匹配(内容="user@example.com", 模式="^[^@]+@[^@]+$"))**,供下一步使用。
|
||||
我们先**tok = [把文本编码为 Base64](编码.基64编码(内容="marqdo"))**,供下一步使用。
|
||||
我们先**hex = [把文本编码为十六进制](编码.十六进制编码(内容="ok"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`ok`)**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`tok`)**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`hex`)**。
|
||||
1. `ok`
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m1-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m1-fail")**。
|
||||
Executable
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Path algebra and isolated native file copying
|
||||
import:
|
||||
path: lib/path.mq.md
|
||||
fs: lib/fs.mq.md
|
||||
---
|
||||
|
||||
This page composes native path and filesystem libraries. Call main with fs.write and a disposable --fs-root; the return contains actual observations for a caller or View.
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | Joined/normalized path text and actual copied content |
|
||||
|
||||
Joining and normalizing transform path text without granting filesystem access. The illustrative out/demo.txt is not an actual write destination. All real IO uses a unique native temporary directory, so this page neither requires a pre-existing out directory nor overwrites a caller's same-named files.
|
||||
|
||||
Grant fs.write and choose a disposable root. Native encoding, path and root checks still apply. Read the copied content before cleaning this run's directory; the returned value should be path-m2. The result contains observations rather than live file paths. An intermediate failure retains its native diagnostic and can leave this run's directory for inspection and caller cleanup.
|
||||
|
||||
The complete flow demonstrates text-only path algebra, actual writing, copying, reading and scoped cleanup. A normalized string is not a filesystem permission, and a printed marker alone would not prove what bytes were copied.
|
||||
|
||||
We **requested = [Join the illustrative output path](path.join(a="out", b="demo.txt"))** and **normalized = [Remove redundant path segments without filesystem IO](path.normalize(path="out/./x/../demo.txt"))** before the file demonstration.
|
||||
For actual IO we **work = [Create a unique directory inside the granted root](fs.temp_dir(prefix="path-demo"))** and **original = [Name this run own source file](path.join(a=`work`, b="demo.txt"))** and **copied = [Name its isolated copy](path.join(a=`work`, b="demo-copy.txt"))**.
|
||||
We **[Write the actual text to copy](fs.write_text(path=`original`, text="path-m2"))** and **[Copy only this run own file](fs.copy_file(src=`original`, dest=`copied`))**.
|
||||
We **copied_text = [Observe the actual copied content](fs.read_text(path=`copied`))** and then **[Clean only this run unique directory](fs.remove_tree(path=`work`))**.
|
||||
|
||||
`observed` =
|
||||
|
||||
| requested | normalized | copied_text |
|
||||
|---|---|---|
|
||||
| `requested` | `normalized` | `copied_text` |
|
||||
|
||||
After the isolated file operation we return *observed*. The temporary files have been removed.
|
||||
Executable
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 路径代数与隔离的原生文件复制
|
||||
import:
|
||||
路径: lib/路径.mq.md
|
||||
文件: lib/文件.mq.md
|
||||
---
|
||||
|
||||
本页直接使用路径库和文件库。调用 main 时授权 fs.write,并将 --fs-root 指向可丢弃的工作目录。函数返回实际观察记录,View 可以显示这些值;无需生成外部脚本。
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | 路径拼接文本、规范化文本与实际复制正文 |
|
||||
|
||||
路径拼接和规范化先处理文本,不隐含文件访问授权。out/demo.txt 只是这个代数示例的输入,不会成为实际写入目的地。真正的文件操作全部放在通过固有库创建的唯一临时目录里,因此不要求已有 out 目录,也不覆盖用户的同名文件。
|
||||
|
||||
调用需要 fs.write,文件库仍会检查授权根目录、编码与路径边界。复制后的正文应为 path-m2。保存这个实际值后清理本轮目录,再返回观察记录;临时路径不会成为可继续使用的持久产物。失败保留原生诊断,中途错误可能留下本轮临时目录供检查,调用方负责识别并清理它。
|
||||
|
||||
本函数既展示无 IO 的路径代数,也展示真实写入、复制、读取和清理。业务中不要根据一个规范化后的字符串就认为已经获得文件权限,更不要把打印成功标记当成已读回复制内容的证明。
|
||||
|
||||
先**requested = [组合演示用的相对路径文本](路径.拼接(甲="out", 乙="demo.txt"))**和**normalized = [消除相对路径中的冗余片段](路径.规范化(路径="out/./x/../demo.txt"))**,核对路径代数本身。
|
||||
为实际读写创建**work = [只使用本轮独有的授权临时目录](文件.临时目录(前缀="路径演示"))**,再准备**original = [在临时目录中命名原文件](路径.拼接(甲=`work`, 乙="demo.txt"))**和**copied = [在同一目录中命名副本](路径.拼接(甲=`work`, 乙="demo-copy.txt"))**。
|
||||
随后**[写入本轮需要复制的正文](文件.写文本(路径=`original`, 内容="path-m2"))**,并**[复制本轮文件而不触及已有用户文件](文件.复制文件(源=`original`, 目标=`copied`))**。
|
||||
读取阶段保存**copied_text = [读取副本的真实正文](文件.读文本(路径=`copied`))**,完成观察后**[清理本轮独有的临时目录](文件.删目录树(路径=`work`))**。
|
||||
|
||||
`observed` =
|
||||
|
||||
| requested | normalized | copied_text |
|
||||
|---|---|---|
|
||||
| `requested` | `normalized` | `copied_text` |
|
||||
|
||||
完成路径处理与隔离读写后,我们返回*observed*,其中保留的是已观察到的值,临时文件已经清理。
|
||||
Executable
+29
@@ -0,0 +1,29 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — hash and secrets
|
||||
description: lib/hash + lib/secrets without plugins (Mid M3)
|
||||
import:
|
||||
hash: lib/hash.mq.md
|
||||
sec: lib/secrets.mq.md
|
||||
---
|
||||
|
||||
# Digests and secure tokens
|
||||
|
||||
|
||||
Integrity digests and cryptographic tokens stay in `lib/` — do not use `math.random` for secrets.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **d = [Compute d](hash.sha256(text="marqdo"))** for the next step.
|
||||
We first **t = [Compute t](sec.token_hex(n=8))** for the next step.
|
||||
We first **L = [Compute L](len(`t`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`d`)**.
|
||||
We now **[Display this step's result](> print text=`L`)**.
|
||||
1. `L` == 16
|
||||
We now **[Display this step's result](> print text="mid-m3-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="mid-m3-fail")**.
|
||||
Executable
+32
@@ -0,0 +1,32 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 哈希与机密
|
||||
description: lib/哈希 + lib/机密,无需插件(中层 M3)
|
||||
导入:
|
||||
哈希: lib/哈希.mq.md
|
||||
机密: lib/机密.mq.md
|
||||
---
|
||||
|
||||
# 摘要与安全令牌
|
||||
|
||||
完整性摘要与加密令牌进 `lib/` — 勿用 `math.random` 生成令牌。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
摘要和随机令牌解决不同的问题。固定文本的 SHA-256 摘要可用于比对内容是否变化;随机令牌从安全随机源获取字节,再编码为十六进制文本。八个随机字节会显示为十六个十六进制字符,因此这里检查输出长度,不把令牌与某个固定值比较。
|
||||
|
||||
本例不会把令牌写到磁盘或发送到网络。实际产品需要依据用途选择令牌字节数,并在使用后按应用规则保管或撤销;这里的短值只演示参数与编码长度的关系。哈希不提供加密,也不能单靠未认证的摘要证明内容来自谁。随机源失败时应保留诊断,不能改用普通伪随机数或固定文本充当安全令牌。
|
||||
|
||||
我们先**d = [计算固定文本的 SHA-256](哈希.哈希256(内容="marqdo"))**,供下一步使用。
|
||||
我们先**t = [取得当前步骤的转置公式或随机令牌](机密.十六进制令牌(字节数=8))**,供下一步使用。
|
||||
我们先**L = [读取十六进制令牌的字符数](长度(`t`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`d`)**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`L`)**。
|
||||
1. `L` == 16
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m3-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m3-fail")**。
|
||||
Executable
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — csv and text
|
||||
description: lib/csv + thickened lib/text (Mid M4)
|
||||
import:
|
||||
csv: lib/csv.mq.md
|
||||
text: lib/text.mq.md
|
||||
---
|
||||
|
||||
# CSV cleaning with text helpers
|
||||
|
||||
|
||||
Parse a tiny CSV, normalize a field, print — no plugins.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **raw = "name,city\nAda,london\nBob,PARIS\n"** for the next step.
|
||||
We first **rows = [Compute rows](csv.parse(text=`raw`))** for the next step.
|
||||
We first **r0 = [Compute r0](at(value=`rows`, index=0))** for the next step.
|
||||
We first **city = [Compute city](text.to_upper(text=[city](access(`r0`, "city"))))** for the next step.
|
||||
We now **[Display this step's result](> print text=[name](access(`r0`, "name")))**.
|
||||
We now **[Display this step's result](> print text=`city`)**.
|
||||
We first **n = [Compute n](len(`rows`))** for the next step.
|
||||
1. `n` == 2
|
||||
We now **[Display this step's result](> print text="mid-m4-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="mid-m4-fail")**.
|
||||
Executable
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 逗号表与文本
|
||||
description: lib/逗号表 + 加厚 lib/文本(中层 M4)
|
||||
导入:
|
||||
逗号表: lib/逗号表.mq.md
|
||||
文本: lib/文本.mq.md
|
||||
---
|
||||
|
||||
# 用文本助手清洗 CSV
|
||||
|
||||
解析小表、规范化字段、打印 — 无需插件。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
CSV 解析先保留每个单元格的文本语义;下面选择第一条记录,再把城市字段规范为大写,得到 LONDON。姓名字段仍是 Ada,另一条记录仍保留在原集合中。调用文本变换不会自动替换原记录,因此这里只展示规范化值,不宣称整个表已经被清洗。
|
||||
|
||||
这里的 at 使用从零开始的位置,access 则按字段名读取记录;不要把二者的索引规则混用。输入正文直接写在本页,没有文件或进程访问。接入真实文件时先用原生文件库读取文本,再交给同一个解析函数;需要金额等数值运算时必须另外做明确的类型转换,不能根据 CSV 中的数字外观推断类型。两行计数只验证这份固定样本的解析结果。
|
||||
|
||||
我们先**raw = "name,city\nAda,london\nBob,PARIS\n"**,供下一步使用。
|
||||
我们先**rows = [解析或排序当前行记录](逗号表.解析(内容=`raw`))**,供下一步使用。
|
||||
我们先**r0 = [选择列表中的第一条记录](at(value=`rows`, index=0))**,供下一步使用。
|
||||
我们先**city = [将第一条记录的城市改为大写文本](文本.大写(内容=[city](access(`r0`, "city"))))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=[name](access(`r0`, "name")))**。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`city`)**。
|
||||
我们先**n = [取得本步骤需要的路径或计数](长度(`rows`))**,供下一步使用。
|
||||
1. `n` == 2
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m4-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m4-fail")**。
|
||||
Executable
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — lists and cli
|
||||
description: table sort/unique/zip + cli.parse (Mid M5)
|
||||
import:
|
||||
table: lib/table.mq.md
|
||||
csv: lib/csv.mq.md
|
||||
cli: lib/cli.mq.md
|
||||
---
|
||||
|
||||
# Sort CSV rows and parse flags
|
||||
|
||||
|
||||
Zero plugins: parse CSV, sort by key, parse `--input`.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **raw = "name,score\nbob,2\nalice,10\n"** for the next step.
|
||||
We first **rows = [Compute rows](csv.parse(text=`raw`))** for the next step.
|
||||
We first **rows = [Compute rows](table.sort_by(list=`rows`, key="name"))** for the next step.
|
||||
We first **r0 = [Compute r0](at(value=`rows`, index=0))** for the next step.
|
||||
We now **[Display this step's result](> print text=[name](access(`r0`, "name")))**.
|
||||
|
||||
We first **args = [Compute args](split(value="--input,scores.csv,--pretty", sep=","))** for the next step.
|
||||
We first **flags = [Compute flags](cli.parse(args=`args`))** for the next step.
|
||||
We now **[Display this step's result](> print text=[input](access(`flags`, "input")))**.
|
||||
1. [pretty](access(`flags`, "pretty"))
|
||||
We now **[Display this step's result](> print text="mid-m5-ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="mid-m5-fail")**.
|
||||
Executable
+37
@@ -0,0 +1,37 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 列表与命令行
|
||||
description: 表排序/去重 + 命令行解析(中层 M5)
|
||||
导入:
|
||||
表: lib/表.mq.md
|
||||
逗号表: lib/逗号表.mq.md
|
||||
命令行: lib/命令行.mq.md
|
||||
---
|
||||
|
||||
# 排序 CSV 并解析参数
|
||||
|
||||
零插件:解析 CSV、按键排序、解析 `--input`。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
这里先按 name 字段对 CSV 记录排序,所以第一条姓名是 alice;score 在本例中仍是文本,尚未参与数值排序。排序函数返回新集合,重新保存 rows 才能让后续取值使用排序结果。随后构造三个命令参数并交给命令行库,读取 input 的文件名以及 pretty 的开关状态。
|
||||
|
||||
参数数组中的元素始终是数据:本例解析 scores.csv 这个名字,不会读取该文件,也不会启动命令解释器。用于真实进程调用时应继续保持逐个参数传递,选项文本要加引号,不要拼成 shell 源码。没有插件、网络和文件授权需求;缺少必须的业务参数时,应由上层根据解析结果决定是否继续,而不是仅看到 pretty 为真就认定所有输入有效。
|
||||
|
||||
我们先**raw = "name,score\nbob,2\nalice,10\n"**,供下一步使用。
|
||||
我们先**rows = [解析或排序当前行记录](逗号表.解析(内容=`raw`))**,供下一步使用。
|
||||
我们先**rows = [解析或排序当前行记录](表.按键排序(list=`rows`, key="name"))**,供下一步使用。
|
||||
我们先**r0 = [选择列表中的第一条记录](at(value=`rows`, index=0))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=[name](access(`r0`, "name")))**。
|
||||
|
||||
我们先**args = [构造逐项传递的命令参数](split(value="--input,scores.csv,--pretty", sep=","))**,供下一步使用。
|
||||
我们先**flags = [解析选项值与布尔开关](命令行.解析(参数=`args`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=[input](access(`flags`, "input")))**。
|
||||
1. [pretty](access(`flags`, "pretty"))
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m5-ok")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="mid-m5-fail")**。
|
||||
Executable
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — log and uuid
|
||||
description: Level-filtered logs + UUID v4 (Mid M6)
|
||||
import:
|
||||
log: lib/log.mq.md
|
||||
uuid: lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# Observable scripts without plugins
|
||||
|
||||
|
||||
Default log level is info; raise to debug when you need more. Mint ids with uuid.v4.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We now **[Call log.info](> log.info text="mid-m6-start")**.
|
||||
|
||||
We now **[Call log.debug](> log.debug text="skipped-by-default")**.
|
||||
|
||||
We now **[Call log.set level](> log.set_level level="debug")**.
|
||||
|
||||
We now **[Call log.debug](> log.debug text="now-visible")**.
|
||||
|
||||
We first **id = [Compute id](uuid.v4())** for the next step.
|
||||
We first **n = [Compute n](len(`id`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`n`)**.
|
||||
Executable
+34
@@ -0,0 +1,34 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 日志与标识
|
||||
description: 按级别过滤的日志 + UUID 版本4(中层 M6)
|
||||
导入:
|
||||
日志: lib/日志.mq.md
|
||||
标识: lib/标识.mq.md
|
||||
---
|
||||
|
||||
# 无插件的可观测脚本
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;本段完成下述操作,不额外返回业务数据。 |
|
||||
|
||||
默认日志级别为 info;需要细节时再调到 debug。用 标识.版本4 生成 id。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
随后我们**[执行 日志.信息](> 日志.信息 内容="中层-m6-开始")**。
|
||||
|
||||
随后我们**[执行 日志.调试](> 日志.调试 内容="默认会跳过")**。
|
||||
|
||||
随后我们**[执行 日志.设级别](> 日志.设级别 级别="debug")**。
|
||||
|
||||
随后我们**[执行 日志.调试](> 日志.调试 内容="现在可见")**。
|
||||
|
||||
我们先**id = [计算并保存 id](标识.版本4())**,供下一步使用。
|
||||
我们先**n = [计算并保存 n](长度(`id`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`n`)**。
|
||||
Executable
+26
@@ -0,0 +1,26 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — datetime and url
|
||||
description: Calendar moments + URL/query parse (Mid2 M7)
|
||||
import:
|
||||
dt: lib/datetime.mq.md
|
||||
url: lib/url.mq.md
|
||||
---
|
||||
|
||||
# Time and addresses without plugins
|
||||
|
||||
|
||||
Moments are maps `{unix, zone, iso}`. Parse HTTPS URLs and round-trip query strings in `lib/url` (segment encoding stays in `net.url_encode`).
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **epoch = [Compute epoch](dt.from_unix(unix=0, zone="Asia/Shanghai"))** for the next step.
|
||||
We now **[Display this step's result](> print text=[iso](access(`epoch`, "iso")))**.
|
||||
|
||||
We first **u = [Compute u](url.parse(text="https://example.com/path?q=1#top"))** for the next step.
|
||||
We now **[Display this step's result](> print text=[host](access(`u`, "host")))**.
|
||||
We now **[Display this step's result](> print text=[query](access(`u`, "query")))**.
|
||||
Executable
+29
@@ -0,0 +1,29 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 日期时间与地址
|
||||
description: 日历时刻 + URL/查询串(Mid2 M7)
|
||||
导入:
|
||||
日时: lib/日期时间.mq.md
|
||||
址: lib/地址.mq.md
|
||||
---
|
||||
|
||||
# 无需插件的时间与地址
|
||||
|
||||
时刻是 map `{unix, zone, iso}`。用 `地址` 拆 HTTPS URL 与查询串。
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
时间戳零表示同一个时间点;指定 Asia/Shanghai 后,ISO 展示采用该时区的当地时间。改变时区不应改变 unix 字段所代表的瞬间。固定时间戳使本例可以重复验证,不依赖机器当前时钟,也不要求读取时间服务。
|
||||
|
||||
地址解析只拆分给定的 HTTPS 文本,host 应为 example.com,query 保留 q=1。它不会访问服务器、验证网站可用性或把查询字符串当作本地文件名。后续需要查询参数时应使用地址库对应的查询解析能力,并保留转义和重复键的边界。时间与 URL 都返回有明确字段的记录;先按契约读取字段,再决定展示格式,避免把整份记录误当成最终用户需要的单段文本。
|
||||
|
||||
我们先**epoch = [构造固定时区的零时刻](日时.自戳(秒=0, 区="Asia/Shanghai"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=[iso](access(`epoch`, "iso")))**。
|
||||
|
||||
我们先**u = [解析当前日期或 URL 输入](址.解析(内容="https://example.com/path?q=1"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=[host](access(`u`, "host")))**。
|
||||
随后我们**[显示当前步骤的结果](> print text=[query](access(`u`, "query")))**。
|
||||
Executable
+31
@@ -0,0 +1,31 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — toml, html, base32
|
||||
description: Config TOML + HTML escape + base32 (Mid2 M8)
|
||||
import:
|
||||
toml: lib/toml.mq.md
|
||||
html: lib/html.mq.md
|
||||
enc: lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# Config and safe text without plugins
|
||||
|
||||
|
||||
Parse a TOML subset for tools, escape HTML before assembly, encode with base32.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
We first **cfg = [Compute cfg](toml.parse(text="app = \"demo\"\n[server]\nport = 8080\n"))** for the next step.
|
||||
We now **[Display this step's result](> print text=[app](access(`cfg`, "app")))**.
|
||||
We first **srv = [server](access(`cfg`, "server"))** for the next step.
|
||||
We now **[Display this step's result](> print text=[port](access(`srv`, "port")))**.
|
||||
|
||||
We first **safe = [Compute safe](html.escape(text="<tag>"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`safe`)**.
|
||||
|
||||
We first **b = [Compute b](enc.base32_encode(text="ok"))** for the next step.
|
||||
We now **[Display this step's result](> print text=`b`)**.
|
||||
Executable
+30
@@ -0,0 +1,30 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 配置表、超文本、基32
|
||||
description: TOML 配置 + HTML 转义 + base32(Mid2 M8)
|
||||
导入:
|
||||
配置: lib/配置表.mq.md
|
||||
超: lib/超文本.mq.md
|
||||
编: lib/编码.mq.md
|
||||
---
|
||||
|
||||
# 无需插件的配置与安全字面
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
三个步骤处理三种文本边界:TOML 解析得到 app 字段的记录,HTML 转义把尖括号变成普通可展示文本,Base32 把 UTF-8 输入编码为另一种文本表示。它们彼此独立,不能把配置解析、页面布局和编码混成一个隐藏的字符串处理流程。
|
||||
|
||||
TOML 文本直接来自本页,读取真实配置文件时应先使用原生文件库;本例不会隐式寻找系统配置。HTML 转义适用于普通文本展示,不能代替 URL、脚本或样式上下文各自需要的处理,更不应因此拼接大量业务 HTML。Base32 只改变表示方法,不加密数据。所有结果都可继续传递给其他 Marqdo 函数,当前步骤不创建文件、不发送网络请求,也不需要外联解释器。
|
||||
|
||||
我们先**cfg = [解析显式提供的 TOML 配置](配置.解析(内容="app = \"演示\"\n"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=[app](access(`cfg`, "app")))**。
|
||||
|
||||
我们先**safe = [将尖括号转义为普通展示文本](超.转义(内容="<tag>"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=`safe`)**。
|
||||
|
||||
我们先**b = [把输入文本编码为 Base32](编.基32编码(内容="ok"))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=`b`)**。
|
||||
Executable
+33
@@ -0,0 +1,33 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Native directory trees, enumeration and file metadata
|
||||
import:
|
||||
fs: lib/fs.mq.md
|
||||
---
|
||||
|
||||
This complete demonstration uses native filesystem tools. Call main with fs.write and a disposable --fs-root. It returns actual metadata and relative paths after cleaning its own temporary directory.
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | Actual byte size, directory entry count and relative paths |
|
||||
|
||||
Create a unique temporary directory, then one child directory and one text file. Every write remains under the granted root, avoiding collisions with a pre-existing demo folder. Paths are built explicitly; no generated reader/writer or foreign process participates.
|
||||
|
||||
The content ok occupies two UTF-8 bytes. File size measures stored bytes rather than text character count. Enumeration returns relative paths for the child directory and file; counting those paths is another distinct observation. The example does not depend on operating-system enumeration order. Sort explicitly if a later workflow requires stable ordering.
|
||||
|
||||
Collect the real metadata and paths before removing this run's unique tree. Returned paths describe an observation, not still-live artifacts. A failure can retain its native diagnostic and this run's directory for caller inspection. Cleanup must stay scoped to the directory created by this invocation.
|
||||
|
||||
We **work = [Create a unique directory inside the granted root](fs.temp_dir(prefix="fs-tree-demo"))** and **child = work + "/sub"** and **note = work + "/readme.txt"**.
|
||||
We **[Create this run own child directory](fs.make_dirs(path=`child`))** and **[Write the exact UTF-8 example content](fs.write_text(path=`note`, text="ok"))**.
|
||||
We **metadata = [Read the actual file metadata](fs.stat(path=`note`))** and **paths = [Enumerate this run directory entries](fs.walk(path=`work`))** and **size = [Retain storage byte size](access(metadata, "size"))** and **entries = [Count the actual enumerated paths](len(`paths`))**.
|
||||
We **[Remove only this run unique directory tree](fs.remove_tree(path=`work`))** after collecting the observations.
|
||||
|
||||
`observed` =
|
||||
|
||||
| size | entries | paths |
|
||||
|---|---|---|
|
||||
| `size` | `entries` | `paths` |
|
||||
|
||||
After observing and cleaning this run we return *observed*.
|
||||
Executable
+33
@@ -0,0 +1,33 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 原生目录树、遍历与文件状态
|
||||
import:
|
||||
文件: lib/文件.mq.md
|
||||
---
|
||||
|
||||
使用固有文件库完成整个演示。调用 main 时授予 fs.write,并指定独立的 --fs-root。函数返回实际元数据与相对路径列表,正常结束后清理自己的临时目录。
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | 真实文件字节数、目录条目数与相对路径列表 |
|
||||
|
||||
本轮先创建唯一临时目录,再在其中建立子目录和文本文件,避免固定的演示名称与已有目录冲突。创建和写入都受 --fs-root 约束,目录参数并不授予访问其他位置的权限。所有路径由当前流程明确构造,没有外部脚本代为读取或修改正文。
|
||||
|
||||
内容“好”占三个 UTF-8 字节,size 描述存储大小而不是字符数。遍历结果包含文件和子目录的相对路径,条目数与字符串长度也是不同的量。本例只观察枚举内容,不依赖操作系统给出的顺序;需要稳定排序时应继续组合表库。
|
||||
|
||||
实际观察值保存后删除本轮独有的临时树。返回的路径列表描述已经观察过的内容,不是仍然存在的文件句柄。中途失败保留原生诊断与可能留下的本轮目录,调用方可以检查后清理,不应递归删除与演示无关的用户目录。
|
||||
|
||||
先**work = [创建本轮独有的授权临时目录](文件.临时目录(前缀="文件树演示"))**和**child = work + "/子"**及**note = work + "/说明.txt"**。
|
||||
接着**[递归创建本轮子目录](文件.建目录树(路径=`child`))**,并**[写入一个明确的 UTF-8 字符](文件.写文本(路径=`note`, 内容="好"))**。
|
||||
观察时保存**metadata = [读取真实文件元数据](文件.状态(路径=`note`))**和**paths = [枚举本轮目录里的实际条目](文件.遍历(路径=`work`))**及**size = [保留存储字节数](access(metadata, "size"))**和**entries = [保留遍历条目数](长度(`paths`))**。
|
||||
最后**[只清理本轮独有的目录树](文件.删目录树(路径=`work`))**,再组织实际观察值。
|
||||
|
||||
`observed` =
|
||||
|
||||
| size | entries | paths |
|
||||
|---|---|---|
|
||||
| `size` | `entries` | `paths` |
|
||||
|
||||
完成观察与清理后,我们返回*observed*。
|
||||
Executable
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Mid stdlib — stats and log fields
|
||||
description: Thin mean/median/stdev + structured log fields (Mid2 M10)
|
||||
import:
|
||||
stats: lib/stats.mq.md
|
||||
log: lib/log.mq.md
|
||||
---
|
||||
|
||||
# Closing Mid2 sugar
|
||||
|
||||
|
||||
Light statistics and optional `fields=` on log lines — no remote sinks, no dataframes.
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
`xs` =
|
||||
|
||||
| |
|
||||
|---|
|
||||
| 10 |
|
||||
| 20 |
|
||||
| 30 |
|
||||
|
||||
We first **m = [Compute m](stats.mean(list=`xs`))** for the next step.
|
||||
We now **[Display this step's result](> print text=`m`)**.
|
||||
|
||||
`fld` =
|
||||
|
||||
| step | status |
|
||||
|------|--------|
|
||||
| done | ok |
|
||||
|
||||
We now **[Call log.info](> log.info text="mid2-m10" fields=`fld`)**.
|
||||
Executable
+39
@@ -0,0 +1,39 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中层标准库 — 统计与日志字段
|
||||
description: 薄均值/中位数/标准差 + 日志 fields(Mid2 M10)
|
||||
导入:
|
||||
统计: lib/统计.mq.md
|
||||
日志: lib/日志.mq.md
|
||||
---
|
||||
|
||||
# Mid2 收口糖
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
数值列表包含十、二十和三十,平均值应为二十。这里把数据写成一列表格,让读者能直接核对输入,而不是在外部解释器中再构造同一份列表。统计函数不修改原集合;需要中位数、标准差或空集合策略时,应继续阅读统计库对应函数的独立契约。
|
||||
|
||||
结构化日志同时携带消息与步骤、状态字段,用于后续过滤或诊断。日志输出不是函数的业务返回值,也不能作为已经完成某项发布或文件写入的证据。本例没有文件和网络操作;实际日志目的地与权限沿用日志库的运行环境规则。若后续任务依赖统计结果,就应直接传递 m 的数值,而不是重新解析打印文本或把最后一条日志当作成功标志。
|
||||
|
||||
`xs` =
|
||||
|
||||
| |
|
||||
|---|
|
||||
| 10 |
|
||||
| 20 |
|
||||
| 30 |
|
||||
|
||||
我们先**m = [计算列表的算术平均值](统计.均值(列表=`xs`))**,供下一步使用。
|
||||
随后我们**[显示当前步骤的结果](> print text=`m`)**。
|
||||
|
||||
`fld` =
|
||||
|
||||
| 步骤 | 状态 |
|
||||
|------|------|
|
||||
| 完成 | ok |
|
||||
|
||||
随后我们**[执行 日志.信息](> 日志.信息 内容="mid2-m10" 字段=`fld`)**。
|
||||
Executable
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: AI 原生闭环(契约 + MLSP)
|
||||
description: 渐进式契约、结构化诊断与面向 AI 的 Marqdo 语言服务
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
里程碑(v1.1.0):AI 原生闭环——让 AI 不仅能写 Marqdo,还能验证 Marqdo。
|
||||
|
||||
三件套。核心表面守卫(`doc/design/core-surface.md`)钉住 19 个核心构造,任一侧(清单 / 文档 / 金样)单边改动,CI 必红。渐进式契约是可选的 `参数` / `返回` / `字段` 表,直接嵌在叙述里,四边界校验:调用实参、返回值、表绑定、键访问。MLSP for AI(`marqdo mlsp`)是行分隔 JSON 的语言服务,AI 按需查询语法,而不是背诵整部语法。
|
||||
|
||||
静态契约检查:
|
||||
|
||||
```bash
|
||||
marqdo check tests/contracts/ok_contract.mq.md
|
||||
```
|
||||
|
||||
结构化诊断——错误即数据:
|
||||
|
||||
```bash
|
||||
marqdo run tests/structure/hello.mq.md --json
|
||||
```
|
||||
|
||||
按需查询语法(MLSP):
|
||||
|
||||
```bash
|
||||
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
|
||||
```
|
||||
|
||||
MLSP 方法:`locate`(查符号 / 构造卡片)、`syntax`(戒律原文 + 样例 + 文档锚点)、`validate`(结构化诊断)、`repair_targets`(有界靶点)、`repair_apply`(有界行编辑,越界必拒)、`schema`(单元契约)。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> print text="契约是可选的:不写契约表,文件保持全动态。")**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> print text="诊断自带 code / severity / suggestion / doc_anchor / doc_quote。")**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> print text="MLSP 语法卡片内嵌戒律原文与样例,AI 无需预学语法。")**。
|
||||
|
||||
验证结果见:`doc/roadmap/perf-validation-report-2026-09-23.md`。
|
||||
Executable
+43
@@ -0,0 +1,43 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: AI-native loop (contracts + MLSP)
|
||||
description: Progressive contracts, structured diagnostics, and the Marqdo Language Server for AI
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Milestone (v1.1.0): the AI-native loop — so an AI can verify Marqdo, not just write it.
|
||||
|
||||
Three pieces. A core surface guard (`doc/design/core-surface.md`) pins the 19 core constructs, so a single-sided change (list / doc / golden sample) turns CI red. Progressive contracts are optional `参数` / `返回` / `字段` tables embedded in the narrative, checked at four boundaries: call argument, return, table bind, key access. MLSP for AI (`marqdo mlsp`) is a line-delimited JSON language service; the AI queries syntax on demand instead of memorizing the whole grammar.
|
||||
|
||||
Static contract check:
|
||||
|
||||
```bash
|
||||
marqdo check tests/contracts/ok_contract.mq.md
|
||||
```
|
||||
|
||||
Structured diagnostics — errors as data:
|
||||
|
||||
```bash
|
||||
marqdo run tests/structure/hello.mq.md --json
|
||||
```
|
||||
|
||||
Query syntax on demand (MLSP):
|
||||
|
||||
```bash
|
||||
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
|
||||
```
|
||||
|
||||
MLSP methods: `locate` (find a symbol / construct card), `syntax` (rule text + sample + doc anchor), `validate` (structured diagnostics), `repair_targets` (bounded span), `repair_apply` (bounded line edits, out-of-scope refused), `schema` (contract of one unit).
|
||||
|
||||
We now **[Display this step's result](> print text="Contracts are optional: with no contract table, a file stays fully dynamic.")**.
|
||||
|
||||
We now **[Display this step's result](> print text="Diagnostics carry code, severity, suggestion, doc_anchor and doc_quote.")**.
|
||||
|
||||
We now **[Display this step's result](> print text="MLSP syntax cards embed the rule text and a sample, so AI need not pre-learn the grammar.")**.
|
||||
|
||||
See validation results: `doc/roadmap/perf-validation-report-2026-09-23.md`.
|
||||
Executable
+116
@@ -0,0 +1,116 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Native analysis and an explicit Intl formatting boundary
|
||||
import:
|
||||
foreign: lib/foreign.mq.md
|
||||
table: lib/table.mq.md
|
||||
result: lib/result.mq.md
|
||||
native: ../../examples/foreign-native-report/index.mq.md
|
||||
---
|
||||
|
||||
This page keeps order analysis in Marqdo and uses Node Intl only for locale-aware
|
||||
currency formatting. Read [the actual native report tools](../../examples/foreign-native-report/index.mq.md)
|
||||
for their independently callable input and return contracts. That single module
|
||||
contains grouping, population statistics and the bounded persistent formatter.
|
||||
|
||||
Call this page's main with process.exec for a full workflow, or call analyze_orders
|
||||
in that module with no effects for native analysis alone. View evaluates the same
|
||||
cells with shared state and isolated kernels. No Python interpreter is needed.
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | View-session plan plus the native report and checked localized formatting |
|
||||
|
||||
This complete page uses six ordinary orders: their native total is 950, count
|
||||
is six, and the four regional rows retain count, total, mean and normalized span.
|
||||
The pure analysis is independently callable in the linked module. Formatting is a separate
|
||||
capability with an explicit process.exec grant and an installed Node runtime.
|
||||
The successful return contains report and formatting alongside the view-session
|
||||
plan; it contains no live kernel handle and can be returned by marqdo call.
|
||||
|
||||
The view gets the same native report copied into two named kernels. Its cells
|
||||
perform presentation rather than reimplementing native grouping or arithmetic.
|
||||
Run All first initializes the formatter in the analysis kernel, then a second
|
||||
cell reuses it. The review kernel receives its own report copy and formatter.
|
||||
This demonstrates both shared state and kernel isolation. Running the dependent
|
||||
formatting cell before its initializer should show the real missing-state error.
|
||||
|
||||
Static View export evaluates those same cells and embeds actual stdout.
|
||||
Interactive View retains their kernels for later runs. The low-level formatter
|
||||
used to check the public return is opened and closed separately, so it cannot
|
||||
secretly supply state to the view kernels. No stdin, notebook command, generated
|
||||
file-reader program or package installation is hidden in this example.
|
||||
If Node or formatting fails, the page returns that failure before declaring a
|
||||
ready view. Native-only consumers can still call analyze_orders with no effects.
|
||||
The table cells below are data, while the three bound node fences are explicit
|
||||
foreign code. The distinction is visible without translating a Python workflow
|
||||
into another ad hoc command sequence.
|
||||
|
||||
`orders` =
|
||||
|
||||
| @ | region | amount |
|
||||
|---|---|---|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
We **report = [Perform all analysis in Marqdo](native.analyze_orders(orders=`orders`))** and **formatted = [Use the genuine external formatting boundary](native.format_summary(report=`report`))**.
|
||||
1. not access(`formatted`, "ok")
|
||||
Return *formatted* before declaring an executable view ready.
|
||||
|
||||
`kernels` =
|
||||
|
||||
| @ | 名称 | 语言 |
|
||||
|---|---|---|
|
||||
| 1 | 分析 | node |
|
||||
| 2 | 复核 | node |
|
||||
|
||||
`cells` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|---|---|
|
||||
| 1 | 计算 | 分析 |
|
||||
| 2 | 格式化 | 分析 |
|
||||
| 3 | 复核 | 复核 |
|
||||
|
||||
`initial` =
|
||||
|
||||
| @ | 内核 | 名称 | 值 |
|
||||
|---|---|---|---|
|
||||
| 1 | 分析 | report | `report` |
|
||||
| 2 | 复核 | report | `report` |
|
||||
|
||||
We **会话 = [Declare the view with native values and explicit kernels](foreign.session(kernels=`kernels`, cells=`cells`, values=`initial`))**.
|
||||
|
||||
`计算` =
|
||||
```node
|
||||
var money = new Intl.NumberFormat("en-US", {style:"currency", currency:"CNY"});
|
||||
console.log(JSON.stringify(report));
|
||||
```
|
||||
|
||||
`格式化` =
|
||||
```node
|
||||
console.log(money.format(report.total));
|
||||
console.log(money.format(report.average));
|
||||
```
|
||||
|
||||
`复核` =
|
||||
```node
|
||||
var reviewMoney = new Intl.NumberFormat("en-US", {style:"currency", currency:"CNY"});
|
||||
console.log(JSON.stringify({count:report.count, total:reviewMoney.format(report.total)}));
|
||||
```
|
||||
|
||||
We **formatting = [Retain the checked persistent-kernel result](access(formatted, "value"))**.
|
||||
|
||||
`evidence` =
|
||||
|
||||
| report | formatting |
|
||||
|---|---|
|
||||
| `report` | `formatting` |
|
||||
|
||||
Return *[The executable view plan with native analysis evidence](table.merge(a=`会话`, b=`evidence`))*.
|
||||
Executable
+97
@@ -0,0 +1,97 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 原生分析与明确的 Intl 格式化边界
|
||||
import:
|
||||
外联: lib/外联.mq.md
|
||||
表: lib/table.mq.md
|
||||
例程: ../../examples/foreign-native-report/index.mq.md
|
||||
---
|
||||
|
||||
先用固有能力,外联只补真实的能力缺口。本页复用 [原生报告例程](../../examples/foreign-native-report/index.mq.md),让统计在 Marqdo 中完成,再通过已支持的 Node 持久内核使用 Intl。阅读例程的源码即可找到可以独立调用的参数、返回值与失败约束。
|
||||
|
||||
在仓库根目录调用 marqdo call public/features/19-外联视图单元.mq.md main --effects process.exec --fs-root . --json 可以获得真实报告与视图计划。使用 view 导出同一份源码即可运行下面声明的单元。这里采用函数标题 main,便于作为工具直接调用;不需要 Python 解释器或另一套笔记本入口。
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | 包含 report、formatting 及内核/单元/初始值的视图计划;失败时返回实际 Result |
|
||||
|
||||
格式化结果中的数字会显示为 950.00 与 158.33,货币标志由区域设置决定;原生 report 保留未格式化的数值。
|
||||
|
||||
本页的六笔订单全部由 Marqdo 固有能力处理,得到合计 950、数量六、四个区域的订单数、合计、均值和总体标准化跨度。分组、排序、统计与数值运算都不需要外部脚本;真正交给 Node 的只有 Intl 本地化货币格式。直接调用本页 main 需要 process.exec,Node 应预先安装。成功返回的计划包含 report 原始报告和 formatting 展示结果,调用者可以继续验证具体数值。
|
||||
|
||||
共享例程有独立的参数及返回表,区域键和金额键都由调用者明确指定,因此中文字段不需要重命名成另一套 JSON 拼接语言。本页和英文页共同调用一份原生算法,避免两个版本逐渐出现不同的统计规则。纯数据分析可以直接调用例程的 analyze_orders,不需要任何进程授权;空输入、单元素区域与相同金额的区域也有清楚的定义。金额只是示例数值,展示的两位小数由 Intl 决定,不宣称是金融十进制定点模型。
|
||||
|
||||
视图的分析内核先输出已经算好的报告,并创建本地化格式器;同一内核中的第二个单元继续使用这个格式器。因此 Run All 的顺序是明确的执行依赖,直接先运行格式化单元应展示真实的未初始化状态。复核单元使用另一份内核和自己的格式器,体现状态隔离。两个内核收到的是报告的数据拷贝,谁都不会重新实现一份分组算法,也不会修改 Marqdo 的源订单。
|
||||
|
||||
用于验证工具返回值的低层格式化例程单独创建并关闭了一个持久内核:第一次求值创建格式器,第二次复用状态。它检查每次求值的 ok,遇到可恢复错误时关闭仍存活的内核,再返回真实诊断。用于视图的会话随后才被声明;工具验证的内核不能暗中给视图提供状态。视图的静态导出与交互模式运行同一批单元,输出来自实际执行,不用预写的通过文字冒充结果。
|
||||
|
||||
正文先交代数据来源和边界,再把调用放入相应的句子。下面的订单、内核、单元和初始值都是普通表格;三段绑定的 node 围栏才是明确外联的代码。整个操作不要求向终端输入 JSON,也不生成文件读取器。若解释器不可用或格式化失败,会在创建可用视图之前把失败交给调用者。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 区域 | 金额 |
|
||||
|---|---|---|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
我们先**报告 = [使用固有库完成分组和总体统计](例程.analyze_orders(orders=`订单`, region_key="区域", amount_key="金额"))**,再**格式结果 = [把真正缺失的本地化展示交给 Intl](例程.format_summary(report=`报告`, locale="zh-CN"))**。
|
||||
1. not access(`格式结果`, "ok")
|
||||
返回*格式结果*,保留外联解释器或格式化的真实失败。
|
||||
|
||||
`内核` =
|
||||
|
||||
| @ | 名称 | 语言 |
|
||||
|---|---|---|
|
||||
| 1 | 分析 | node |
|
||||
| 2 | 复核 | node |
|
||||
|
||||
`单元` =
|
||||
|
||||
| @ | 单元 | 内核 |
|
||||
|---|---|---|
|
||||
| 1 | 计算 | 分析 |
|
||||
| 2 | 格式化 | 分析 |
|
||||
| 3 | 复核 | 复核 |
|
||||
|
||||
`初始值` =
|
||||
|
||||
| @ | 内核 | 名称 | 值 |
|
||||
|---|---|---|---|
|
||||
| 1 | 分析 | report | `报告` |
|
||||
| 2 | 复核 | report | `报告` |
|
||||
|
||||
接着**会话 = [用普通表格声明显式的视图会话](外联.会话(内核表=`内核`, 单元表=`单元`, 值表=`初始值`))**,让两份内核获得同一个原生报告的独立 JSON 拷贝。
|
||||
|
||||
`计算` =
|
||||
```node
|
||||
var money = new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"});
|
||||
console.log(JSON.stringify(report));
|
||||
```
|
||||
|
||||
`格式化` =
|
||||
```node
|
||||
console.log(money.format(report.total));
|
||||
console.log(money.format(report.average));
|
||||
```
|
||||
|
||||
`复核` =
|
||||
```node
|
||||
var reviewMoney = new Intl.NumberFormat("zh-CN", {style:"currency", currency:"CNY"});
|
||||
console.log(JSON.stringify({count:report.count, total:reviewMoney.format(report.total)}));
|
||||
```
|
||||
|
||||
我们**展示 = [保留已经检查过的持久格式化结果](access(格式结果, "value"))**,把数据与展示来源一并交给调用者。
|
||||
|
||||
`依据` =
|
||||
|
||||
| report | formatting |
|
||||
|---|---|
|
||||
| `报告` | `展示` |
|
||||
|
||||
所有值准备好后返回*[带原生分析依据的可执行视图计划](表.merge(a=`会话`, b=`依据`))*。
|
||||
Executable
+140
@@ -0,0 +1,140 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 代码即文档,文档即知识 — OKF 与 EKC
|
||||
description: Marqdo 如何以一份可执行源为唯一权威,把它投影成 OKF 风格知识与 Engineering Knowledge Compiler 制品
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
Marqdo 的宪法是「代码即文档,文档即知识库」。`.mq.md` 不是程序截图:它同时是可读源码、可执行单元和知识页。
|
||||
|
||||
这个承诺只有在知识始终从源派生时才成立。OKF 提供可移植知识包的形态;EKC 提供工程化投影。二者都不成为第二份权威。
|
||||
|
||||
---
|
||||
|
||||
OKF 的形,Marqdo 的义。
|
||||
|
||||
OKF(Open Knowledge Format)用 Markdown + YAML frontmatter 表示知识:一页一概念、路径即身份、链接成图、强制面刻意保持很小。Marqdo 借用这个形态,但正文是可执行语法。
|
||||
|
||||
因此概念页可以直接指向证明它的文件:
|
||||
|
||||
```yaml
|
||||
type: Capability
|
||||
title: 持久外联内核
|
||||
description: 向显式声明的本地内核传递原生数据并保留状态
|
||||
resource: public/features/19-外联视图单元.mq.md
|
||||
status: stable
|
||||
verified:
|
||||
by: marqdo-knowledge/verify
|
||||
tags:
|
||||
- foreign
|
||||
- view-cells
|
||||
```
|
||||
|
||||
同一页可以在编辑器里读、从 catalog 链接、被 Agent 查询,也可以直接运行。未知字段保留;未知类型降级为可读正文。概念页不是源文件的复制品。
|
||||
|
||||
---
|
||||
|
||||
哪些是生成的,哪些不是。
|
||||
|
||||
| 层 | 作者 | 职责 |
|
||||
|---|---|---|
|
||||
| 源 | 人或编码 Agent | .mq.md;唯一语义权威 |
|
||||
| 目录包 | marqdo catalog | 模块、符号、能力与图投影 |
|
||||
| 任务知识 | plan 晋升 | 任务、技能与可执行资源包 |
|
||||
| 静态站 | marqdo view output | 人读 HTML,永远不是权威 |
|
||||
|
||||
生成物带 GENERATED 标记,可以删除重建;没有它们源树仍能运行。Catalog 是索引,不是语言特性。
|
||||
|
||||
---
|
||||
|
||||
EKC:Engineering Knowledge Compiler。
|
||||
|
||||
EKC 把仓库投影成工程知识系统,并在 Agent 写新代码前提供 preflight:
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► catalog L0–L4
|
||||
├─ graph
|
||||
├─ context pack
|
||||
└─ Agent preflight
|
||||
```
|
||||
|
||||
| 层 | 知识 | 例子 |
|
||||
|---|---|---|
|
||||
| L0 Repository | 语言、规模、根目录 | 仓库总览 |
|
||||
| L1 Module | imports、exports、职责 | 外联内核模块 |
|
||||
| L2 Symbol | 签名、调用、指纹 | 外部源码中的函数 |
|
||||
| L3 Capability | 工程能做什么 | 运行持久外联内核 |
|
||||
| L4 Knowledge | 决策、约束、失败 | 为什么状态桥必须显式 |
|
||||
|
||||
图记录 implements、uses、depends_on、tested_by、documented_by、constrained_by、decided_by、supersedes、conflicts_with、deprecated_by 等关系。Agent 先沿图发现已有能力,而不是重新造轮子。
|
||||
|
||||
---
|
||||
|
||||
Engineering First Information:先发现,再创建。
|
||||
|
||||
复用协议是硬顺序:
|
||||
|
||||
```text
|
||||
REUSE → ADAPT → CREATE
|
||||
```
|
||||
|
||||
preflight 可以在实现开始前返回已有能力、API、约束、决策与失败经验。知识图缺失时返回明确的 missing_knowledge,而不是静默编造。
|
||||
|
||||
五条原则:
|
||||
|
||||
| # | 原则 |
|
||||
|---|---|
|
||||
| 1 | Discover before Create |
|
||||
| 2 | Reuse before Adapt |
|
||||
| 3 | Adapt before Duplicate |
|
||||
| 4 | Verify before Promote |
|
||||
| 5 | Code changes update knowledge |
|
||||
|
||||
---
|
||||
|
||||
命令。
|
||||
|
||||
```bash
|
||||
# 把仓库投影成 catalog + EKC 制品
|
||||
marqdo catalog .
|
||||
|
||||
# 写代码前先问:已经有了什么?
|
||||
marqdo knowledge preflight "增加一个持久外联内核"
|
||||
marqdo find "外联 会话"
|
||||
marqdo reuse "实现 JSON 并行扇出"
|
||||
|
||||
# 看一次修改会影响什么
|
||||
marqdo impact public/features/19-外联视图单元.mq.md
|
||||
|
||||
# 校验知识投影
|
||||
marqdo knowledge verify
|
||||
```
|
||||
|
||||
`marqdo catalog` 保留人读的 `index.md` 与模块页;EKC 在 `.marqdo/` 下增加 L0–L4。两者都从同一棵源树生成。
|
||||
|
||||
---
|
||||
|
||||
每个声称的能力都必须有可执行资源。
|
||||
|
||||
一个知识页说“这个工程能分析订单”,就必须指向一个真正能跑的 `.mq.md` 资源。这是 OKF 形态的笔记与可执行知识系统的区别。
|
||||
|
||||
外联示例先用 Marqdo 固有能力分析订单,再把本地化展示交给 Node Intl。显式导入指向共享的可调用报表手册,页面本身声明实际的视图内核、原生值与单元。验收仍要检查逐单元的真实结果,不能把一份可序列化计划当作单元已经运行成功的证明。
|
||||
|
||||
---
|
||||
|
||||
继续阅读。
|
||||
|
||||
OKF 设计:[OKF 设计](../../doc/design/okf.md)
|
||||
|
||||
Engineering Knowledge Compiler:[Engineering Knowledge Compiler](../../doc/design/engineering-knowledge.md)
|
||||
|
||||
Catalog CLI:[Catalog CLI](../../doc/design/catalog-cli.md)
|
||||
|
||||
OKF 与 Marqdo 调研:[OKF 与 Marqdo 调研](../../doc/research/okf-and-marqdo.md)
|
||||
|
||||
外联 view 单元示例:[外联 view 单元示例](19-外联视图单元.mq.md)
|
||||
Executable
+140
@@ -0,0 +1,140 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Code as documentation, documentation as knowledge — OKF and EKC
|
||||
description: How Marqdo keeps one executable source of truth while projecting it into OKF-style knowledge and Engineering Knowledge Compiler artifacts
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Marqdo's constitution is code as documentation and documentation as knowledge. A `.mq.md` file is not a screenshot of a program: it is the readable source, the executable unit and the knowledge page at the same time.
|
||||
|
||||
That claim matters only if the knowledge stays derived from the source. OKF gives us the shape of a portable knowledge bundle; EKC gives us the engineering projection. Neither becomes a second source of truth.
|
||||
|
||||
---
|
||||
|
||||
OKF shape, Marqdo meaning.
|
||||
|
||||
OKF (Open Knowledge Format) describes knowledge as Markdown pages with YAML frontmatter: one concept per page, path as identity, links as graph, a deliberately small required surface. Marqdo borrows that shape, but its body is executable.
|
||||
|
||||
A concept page can therefore point at the exact file that proves it:
|
||||
|
||||
```yaml
|
||||
type: Capability
|
||||
title: Persistent foreign kernels
|
||||
description: Run an explicitly declared local kernel with native data
|
||||
resource: public/features/19-foreign-view-cells.mq.md
|
||||
status: stable
|
||||
verified:
|
||||
by: marqdo-knowledge/verify
|
||||
tags:
|
||||
- foreign
|
||||
- view-cells
|
||||
```
|
||||
|
||||
The same page can be opened in an editor, linked from a catalog, queried by an agent, and executed. Unknown fields are preserved; unknown types degrade to readable prose. The page is a concept, not a copy of one.
|
||||
|
||||
---
|
||||
|
||||
What is generated, and what is not.
|
||||
|
||||
| Layer | Author | Role |
|
||||
|---|---|---|
|
||||
| Source | person or coding agent | .mq.md; the only semantic authority |
|
||||
| Catalog | marqdo catalog | module, symbol, capability and graph projection |
|
||||
| Task knowledge | plan promotion | task, skill and executable resource bundle |
|
||||
| Static site | marqdo view output | human-readable HTML, never an authority |
|
||||
|
||||
Generated artifacts are marked GENERATED and can be deleted and rebuilt. The source tree still runs without them. A catalog is an index, not a language feature.
|
||||
|
||||
---
|
||||
|
||||
EKC: the Engineering Knowledge Compiler.
|
||||
|
||||
EKC projects the repository into an engineering knowledge system, then exposes it through a preflight before an agent writes new code:
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► catalog L0–L4
|
||||
├─ graph
|
||||
├─ context pack
|
||||
└─ Agent preflight
|
||||
```
|
||||
|
||||
| Layer | Knowledge | Example |
|
||||
|---|---|---|
|
||||
| L0 Repository | language, size, roots | repository summary |
|
||||
| L1 Module | imports, exports, responsibility | a foreign kernel module |
|
||||
| L2 Symbol | signature, calls, fingerprint | a function in external source code |
|
||||
| L3 Capability | what the project can do | run a persistent foreign kernel |
|
||||
| L4 Knowledge | decisions, constraints, failures | why the bridge is explicit |
|
||||
|
||||
The graph records relations such as implements, uses, depends_on, tested_by, documented_by, constrained_by, decided_by, supersedes, conflicts_with and deprecated_by. That graph is how an agent discovers existing capability before inventing a duplicate.
|
||||
|
||||
---
|
||||
|
||||
Engineering First Information: discover before create.
|
||||
|
||||
The reuse protocol is a hard order:
|
||||
|
||||
```text
|
||||
REUSE → ADAPT → CREATE
|
||||
```
|
||||
|
||||
A preflight can return existing capabilities, APIs, constraints, decisions and failure notes before a new implementation starts. If the knowledge graph is missing, the result is an explicit missing_knowledge state, not a silent fabrication.
|
||||
|
||||
The five principles are:
|
||||
|
||||
| # | Principle |
|
||||
|---|---|
|
||||
| 1 | Discover before Create |
|
||||
| 2 | Reuse before Adapt |
|
||||
| 3 | Adapt before Duplicate |
|
||||
| 4 | Verify before Promote |
|
||||
| 5 | Code changes update knowledge |
|
||||
|
||||
---
|
||||
|
||||
The commands.
|
||||
|
||||
```bash
|
||||
# Project the repository into catalog + EKC artifacts
|
||||
marqdo catalog .
|
||||
|
||||
# Ask what already exists before writing code
|
||||
marqdo knowledge preflight "add a persistent foreign kernel"
|
||||
marqdo find "foreign session"
|
||||
marqdo reuse "implement JSON fan-out"
|
||||
|
||||
# See what a change would touch
|
||||
marqdo impact public/features/19-foreign-view-cells.mq.md
|
||||
|
||||
# Validate the knowledge projection
|
||||
marqdo knowledge verify
|
||||
```
|
||||
|
||||
`marqdo catalog` keeps the human-readable `index.md` and module pages; EKC adds L0–L4 files under `.marqdo/`. Both are generated from the same source tree.
|
||||
|
||||
---
|
||||
|
||||
Every claimed capability has an executable resource.
|
||||
|
||||
A knowledge page that says “this project can analyze orders” must point to a `.mq.md` resource that actually runs. That is the difference between an OKF-shaped note and an executable knowledge system.
|
||||
|
||||
The foreign example computes its order report in native Marqdo and uses Node Intl for locale-aware presentation. Explicit imports point to the shared callable report handbook, while the page declares the actual view kernels, values and cells. Inspect the real per-cell results; a serialized plan alone does not establish that its cells ran successfully.
|
||||
|
||||
---
|
||||
|
||||
Read more.
|
||||
|
||||
OKF design: [OKF design](../../doc/design/okf.md)
|
||||
|
||||
Engineering Knowledge Compiler: [Engineering Knowledge Compiler](../../doc/design/engineering-knowledge.md)
|
||||
|
||||
Catalog CLI: [Catalog CLI](../../doc/design/catalog-cli.md)
|
||||
|
||||
OKF and Marqdo research: [OKF and Marqdo research](../../doc/research/okf-and-marqdo.md)
|
||||
|
||||
Foreign view-cells example: [Foreign view-cells example](19-foreign-view-cells.mq.md)
|
||||
Executable
+58
@@ -0,0 +1,58 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Persist an actual formatting result through native writeback
|
||||
import:
|
||||
guide: ../../doc/library-development.mq.md
|
||||
formatter: ../../examples/foreign-native-report/index.mq.md
|
||||
writeback: lib/writeback.mq.md
|
||||
result: lib/result.mq.md
|
||||
---
|
||||
|
||||
The source remains the manual for this file operation. Its callable main computes
|
||||
native data, crosses a genuine formatting boundary, checks the result and records
|
||||
only the successful value. Invoke with process.exec,fs.write and --fs-root .;
|
||||
static View uses the same source and embeds its actual observed output.
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | Result with the actual string recorded in this source's total slot |
|
||||
|
||||
A static View snapshot embeds executed output in HTML. Explicit writeback
|
||||
instead keeps a selected value in this source file's named slot. A caller should
|
||||
choose that file effect deliberately: this main needs process.exec and fs.write,
|
||||
with --fs-root pointing at the repository. Reading the page alone does not write.
|
||||
|
||||
The amount is computed by the native programming guide, then the shared example
|
||||
uses Node Intl only for locale-aware currency formatting. Its persistent kernel
|
||||
is closed before this page receives the result. No Python process, foreign file
|
||||
writer or duplicated arithmetic participates. The exact returned string is then
|
||||
passed to lib/writeback, so the file operation remains a Marqdo capability.
|
||||
|
||||
The total slot below is actual recorded output. Repeated execution replaces that
|
||||
same key rather than appending another slot. An unavailable interpreter or failed
|
||||
formatting returns before the write; native write-policy or IO faults retain
|
||||
their diagnostics. Writeback persists this selected ordinary value, not a live
|
||||
kernel or arbitrary process memory. Review source changes with the repository's
|
||||
normal diff workflow. For published docs use a static snapshot unless a living
|
||||
auditable source result is intended, as it explicitly is in this demonstration.
|
||||
|
||||
We **amount = [Compute the native amount](guide.计算金额(单价=190, 数量=5))**.
|
||||
|
||||
`report` =
|
||||
|
||||
| total | average |
|
||||
|---|---|
|
||||
| `amount` | `amount` |
|
||||
|
||||
We **formatted = [Use only the actual Intl presentation gap](formatter.format_summary(report=`report`))**.
|
||||
1. not access(`formatted`, "ok")
|
||||
Return *formatted* before writing a result slot.
|
||||
We **text = [Select the actual formatter output](access(access(formatted, "value"), "total"))**.
|
||||
We **written = [Persist this actual output through Marqdo's native writeback](writeback.record(value=`text`, key="total"))**.
|
||||
<!-- marqdo-out total
|
||||
CN¥950.00
|
||||
-->
|
||||
|
||||
After the explicit native file operation, return *[The persisted formatted value](result.ok(value=`text`))*.
|
||||
Executable
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 用固有写回保存真实的格式化结果
|
||||
import:
|
||||
指南: ../../doc/library-development.mq.md
|
||||
例程: ../../examples/foreign-native-report/index.mq.md
|
||||
写回: lib/writeback.mq.md
|
||||
结果: lib/result.mq.md
|
||||
---
|
||||
|
||||
调用 main 需要 process.exec,fs.write,并将 --fs-root 指向仓库根目录。这是本页明确声明的文件修改,普通阅读不会写文件。静态 View 与可调用函数使用同一份源码,输出来自实际执行。
|
||||
|
||||
## main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | map | Result:保存到本页 total 槽位的实际文本 |
|
||||
|
||||
静态快照把执行输出嵌入 HTML;显式写回则把选定结果保存在源码的命名槽位里。本页正是需要后者的活文档示例,调用者应先知道会修改本页,再授予 fs.write。写回后的值可以在普通 Markdown 源码和差异中审阅,不依赖仍存活的外部进程。
|
||||
|
||||
金额由原生开发指南计算,随后共享例程只调用 Node Intl 完成固有库尚未提供的本地化货币展示。例程检查每次求值并关闭其持久内核,调用者得到的已经是普通文本。没有 Python 编排,也没有外部文件写入器;保存动作继续使用 Marqdo 的 writeback。示例的金额为 950,当前区域设置下的文本为 ¥950.00,真实输出会成为下面的 total 槽位内容。
|
||||
|
||||
再次执行替换同一个键,不重复添加槽位。若解释器不可用或格式化失败,在写文件之前就返回真实失败;固有文件策略或 IO 错误也保留诊断。这里持久化的是已经选定的文本,不保存任意内核内存,也不能根据它重建活资源句柄。完成后可用正常的仓库差异审阅流程检查变更,再决定是否随文档提交。
|
||||
|
||||
面向读者的发布页面通常选择静态快照;明确需要在源码中保存最新运行结果的审计文档才使用写回。两者可以共存,但静态导出如果执行了本页,仍会尊重这个显式写回操作。权限不会因为文档外观而被隐式扩张,依赖步骤也不能在失败后继续伪造结果。
|
||||
|
||||
先**金额 = [计算需要展示的原生金额](指南.计算金额(单价=190, 数量=5))**.
|
||||
|
||||
`report` =
|
||||
|
||||
| total | average |
|
||||
|---|---|
|
||||
| `金额` | `金额` |
|
||||
|
||||
再**格式结果 = [只把本地化展示交给 Intl](例程.format_summary(report=`report`, locale="zh-CN"))**。
|
||||
1. not access(`格式结果`, "ok")
|
||||
返回*格式结果*,失败时不进入文件写回。
|
||||
我们**正文 = [读取实际格式化文本](access(access(格式结果, "value"), "total"))**。
|
||||
随后**写入 = [使用固有写回能力保存真实文本](写回.record(value=`正文`, key="total"))**。
|
||||
<!-- marqdo-out total
|
||||
¥950.00
|
||||
-->
|
||||
|
||||
写回完成后返回*[已经保存的格式化文本](结果.ok(value=`正文`))*。
|
||||
Executable
+85
@@ -0,0 +1,85 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Call one function: the same document is the tool
|
||||
description: v2.2.0 marqdo call runs a function inside any .mq.md. The explanation, the implementation and the call are one page.
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
v2.2.0 adds one command: `marqdo call`. It adds no Markdown marker and no skill system. An ordinary .mq.md file is already a document, a piece of knowledge and a program. What was missing is a way to call one of its functions from outside.
|
||||
|
||||
The usual command runs the whole file. Functions inside it run only when the entry calls them. Trying one calculation meant writing an entry, a print and a check. The smallest unit you can execute is now a function.
|
||||
|
||||
```text
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
Standard output is 5. `--json` is for programs and agents: success carries the result, failure carries a diagnostic code, and the process exits non-zero. `--backend tree` and `--backend bytecode` both run that function. Another entry in the file is not used as a fallback.
|
||||
|
||||
The second half of this page is itself a calculator. This command calls this page:
|
||||
|
||||
```text
|
||||
marqdo call public/features/22-call.mq.md calculator.add a=2 b=3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
The change is how the file is used.
|
||||
|
||||
A person reads the sentences next to the function and sees what add computes. The compiler reads the same markers and checks parameters and the return. A developer composes the function into another program. A test passes inputs to this function and looks at the output, without a wrapper whose only job is to print. An agent reads what the function is for and runs the implementation that is already there, instead of reading the page and rewriting it.
|
||||
|
||||
Those four uses are one call. Knowledge becomes a tool because knowledge can already run, now at function scope. The file does not need a special name, and it does not need to declare itself a skill.
|
||||
|
||||
---
|
||||
|
||||
The command keeps a boundary.
|
||||
|
||||
An external call defaults to a pure function. Writing files, starting a process, using the network or loading a plugin is refused before the function runs. Pass `--effects plugin` when the tool needs an ABI plugin (for example `ext/quantum`). Session bindings use `--session` and `--toget name` (or trailing `toget name`); later calls may pass `$name`. Nested sub-tools use a dotted path such as `outer.helper`. An instance method needs its receiver; this command does not invent one.
|
||||
|
||||
The function must resolve to exactly one declaration. No match, or one short name that hits two functions, is a structured error. The command does not pick the first hit. Arguments bind through the signature and contract that the function already has. Missing, unknown and ill-typed arguments are diagnostics.
|
||||
|
||||
After editing a function, call it again with the inputs that failed. A passing check is a reason to keep the edit. A test does not prove every input. It gives the edit a check that can be repeated.
|
||||
|
||||
# calculator
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | Object/type namespace for the child functions below; call the intended child directly |
|
||||
|
||||
This is an ordinary Marqdo document.
|
||||
|
||||
It holds a little reusable arithmetic.
|
||||
|
||||
## add
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| a | any | required | Left operand supplied to this calculation |
|
||||
| b | any | required | Right operand supplied to this calculation |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | The value explicitly returned below; conditional returns follow the selected branch |
|
||||
|
||||
Add the numbers `a` and `b`.
|
||||
|
||||
After these steps, return *[result]((`a` + `b`))*.
|
||||
|
||||
## multiply
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| a | any | required | Left operand supplied to this calculation |
|
||||
| b | any | required | Right operand supplied to this calculation |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | The value explicitly returned below; conditional returns follow the selected branch |
|
||||
|
||||
Multiply the numbers `a` and `b`.
|
||||
|
||||
After these steps, return *[result]((`a` * `b`))*.
|
||||
Executable
+85
@@ -0,0 +1,85 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 函数级调用:同一份文档成为工具
|
||||
description: v2.2.0 的 marqdo call 让任意 .mq.md 里的函数可以带参数执行。说明、实现和调用是同一页。
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
v2.2.0 增加一条命令:`marqdo call`。它不新增 Markdown 标记,也不另建一套技能系统。一个普通的 .mq.md 本来就是文档、知识和程序。缺的是从外部直接调用其中某个函数。
|
||||
|
||||
以前日常用法是运行整份文件。入口对象跑完,里面的函数要等文件自己去调用。要试验一个计算,往往得再写入口、打印和检查。现在最小可执行单位是函数。
|
||||
|
||||
```text
|
||||
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
标准输出是 5。`--json` 给程序和 Agent 读:成功时是带结果的对象,失败时是带诊断码的对象,退出码非 0。`--backend tree` 与 `--backend bytecode` 执行同一个函数。文件里即使还有别的入口,也不会改去跑那个入口。
|
||||
|
||||
本页后半本身就是一份计算器。下面这条命令调用的就是这一页:
|
||||
|
||||
```text
|
||||
marqdo call public/features/22-函数调用.mq.md 计算器.加法 a=2 b=3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
它解决的是使用方式,不是再写一份说明书。
|
||||
|
||||
人打开这一页,读函数旁边的句子,知道加法在算什么。编译器解析同一批标记,检查参数和返回。开发者把函数嵌进别的程序。测试对这个函数传入输入,看输出是不是期望值,不必为它包一层只用来打印的程序。Agent 读到的是函数的用途,执行的是已经写好的实现,而不是读完说明再临时重写一遍。
|
||||
|
||||
这四件事共用一次调用。知识成为工具,是「知识即可执行」在函数这一层上的结果。文件不需要改名,也不需要声明自己是技能。运行时和工具清单都不会把一页普通文档挡在门外。
|
||||
|
||||
---
|
||||
|
||||
边界也写在命令里。
|
||||
|
||||
外部调用默认只执行纯函数。写文件、起进程、访问网络、加载插件,会在运行前被拒绝,副作用不会发生。要放宽权限,仍走项目里已有的验证,而不是在这条命令上新开一个开关。实例方法需要接收者,不能靠这条命令凭空调用。
|
||||
|
||||
函数名必须能唯一对上。没有这个函数,或同一个短名指向两个函数,都会返回结构化错误,不会擅自挑第一个。参数按函数已有的签名和契约绑定:缺了、多了、类型不对,都是诊断,不是静默猜一个值。
|
||||
|
||||
改一个函数之后,用原来的输入再调用一次。结果对了,这个实现就留下来;不对,就还是原来的实现。测试不能证明所有输入都正确。它让修改有一个可以重复的检查点。
|
||||
|
||||
# 计算器
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 供下述方法复用的对象或类型命名空间;直接调用所需的子函数。 |
|
||||
|
||||
这是一个普通的 Marqdo 文档。
|
||||
|
||||
其中包含一些可以复用的数学计算知识。
|
||||
|
||||
## 加法
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| a | any | 必填 | Left operand supplied to this calculation |
|
||||
| b | any | 必填 | Right operand supplied to this calculation |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 下文显式返回的计算值或结构化结果;分支存在时遵循实际命中的分支。 |
|
||||
|
||||
计算两个数字`a`和`b`的和。
|
||||
|
||||
完成上述步骤后,返回*[计算结果]((`a` + `b`))*。
|
||||
|
||||
## 乘法
|
||||
|
||||
| 参数 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| a | any | 必填 | Left operand supplied to this calculation |
|
||||
| b | any | 必填 | Right operand supplied to this calculation |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 下文显式返回的计算值或结构化结果;分支存在时遵循实际命中的分支。 |
|
||||
|
||||
计算两个数字`a`和`b`的积。
|
||||
|
||||
完成上述步骤后,返回*[计算结果]((`a` * `b`))*。
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
markup: occlusion
|
||||
import:
|
||||
result: ../../lib/result.mq.md
|
||||
title: Prove what a page claims: theorem tables judged by Lean 4
|
||||
description: v2.8.0 marqdo prove compiles theorem tables to Lean 4 and judges them. Offline symbolic execution works without a toolchain and never outruns Lean.
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
v2.8.0 adds one command: `marqdo prove`. A theorem table in a knowledge file is compiled to Lean 4 and judged automatically. The claim stops being prose that a reader agrees with and becomes a statement a proof assistant checks.
|
||||
|
||||
```text
|
||||
marqdo prove examples/approval.mq.md --json
|
||||
```
|
||||
|
||||
The pipeline has six stages: load, lower to an intermediate representation, type the claim, generate a Lean module, judge it, and issue a certificate. Judging has two layers. Offline symbolic execution runs first — path enumeration over the pure fragment, milliseconds, no toolchain required. When a Lean toolchain is available it re-checks the emitted module and upgrades the verdict.
|
||||
|
||||
The status ladder is honest by construction: `proved > checked > unverified > rejected > unproved > error`. Offline `checked` is a decided trace for the explored paths, never a proof; `proved` exists only when Lean says so. Without a toolchain the verdict stays at `checked` or `unverified` and the process exits zero — advisory, not silent. `--require-lean` flips unjudged states into failures for CI.
|
||||
|
||||
A false theorem does not get a shrug. The judge produces a counterexample witness — concrete input values that walk the function down a path where the conclusion fails — and points back at the theorem-table row.
|
||||
|
||||
The boundary that makes this trustworthy is monotonicity: whatever the offline layer claims, Lean must be able to confirm. If the offline verdict says checked and Lean cannot prove it, or a counterexample is proven away, the command fails with `proof.divergence` and exits non-zero. A judger defect fails loudly; a green light is never defended.
|
||||
|
||||
The fragment is deliberately small: pure functions, branch comparisons, call-trace shapes, constructor structure, interval restatements. Loops report `proof.foreach_pending` instead of pretending. Cross-module calls stay opaque until assumption tables arrive. Every simplification is recorded in the design docs, because a proof system that hides its boundaries is marketing, not verification.
|
||||
|
||||
This page runs — the theorems below live in the same file that explains them. `轨迹` is the implicit call trace of the function: the big-amount path must pass through 复核, opaque calls append to it, and inlined `result.ok` constructors do not.
|
||||
|
||||
# 台账
|
||||
|
||||
## 记一笔
|
||||
+ `金额`
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| 金额 | int | 记账金额(元) |
|
||||
|
||||
| 定理 | 结论 | 前提 | 策略 |
|
||||
|---|---|---|---|
|
||||
| 大额必经复核 | 包含(轨迹, "复核") | 金额 > 10000 | auto |
|
||||
| 大额单次外呼 | 长度(轨迹) = 1 | 金额 > 10000 | auto |
|
||||
| 必有回执 | 结果.ok = True | | auto |
|
||||
|
||||
1. 当`金额`小于等于10000时
|
||||
**回执 = [直接记账](result.ok(value="记"))**
|
||||
2. *
|
||||
**复核结论 = [转复核](复核(金额=`金额`))**
|
||||
**回执 = [采纳](result.ok(value=`复核结论`))**
|
||||
|
||||
*回执*
|
||||
|
||||
## 复核
|
||||
+ `金额`
|
||||
|
||||
**复核回执 = [复核通过](result.ok(value="复核"))**
|
||||
|
||||
*复核回执*
|
||||
+5071
File diff suppressed because it is too large.
Load diff
Executable
+28
@@ -0,0 +1,28 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Booleans and logic
|
||||
description: True / False / None and and / or / not
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Keywords: `True`, `False`, `None`, and `and` / `or` / `not`.
|
||||
|
||||
We first **a = True** for the next step.
|
||||
We first **b = False** for the next step.
|
||||
|
||||
1. `a` and not `b`
|
||||
We now **[Display this step's result](> print text="ok")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="fail")**.
|
||||
|
||||
We first **probe = 1** for the next step.
|
||||
|
||||
1. None
|
||||
We now **[Display this step's result](> print text="none-truthy")**.
|
||||
2. *
|
||||
We now **[Display this step's result](> print text="none-falsy")**.
|
||||
Executable
+18
@@ -0,0 +1,18 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Built-in input
|
||||
description: Read one line from stdin; optional prompt. Demo via frontmatter stdin.
|
||||
stdin: Ada
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
The input builtin reads one line. For demos and marqdo view / static export, put sample lines in frontmatter (stdin:). CLI can also use a pipe or --stdin-file. Live view can override with the Preset input box.
|
||||
|
||||
We first **name = [Compute name](input(prompt="Name: "))** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text="Hello `name`!")**.
|
||||
Executable
+19
@@ -0,0 +1,19 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Built-in print
|
||||
description: Named and positional forms
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
The `print` builtin accepts named or positional arguments:
|
||||
|
||||
We now **[Display this step's result](> print text="named form")**.
|
||||
|
||||
We now **[Display this step's result](> print "positional")**.
|
||||
|
||||
Named args may contain spaces; positional args may not.
|
||||
Executable
+39
@@ -0,0 +1,39 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: Built-ins len / str / int / type / trim / split / join / at
|
||||
description: Host builtins for strings and tables
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | None; execute this page's documented steps in order and observe their output or stated effects |
|
||||
|
||||
Length and type:
|
||||
|
||||
We first **s = "hello"** for the next step.
|
||||
|
||||
We first **n = [Compute n](len(`s`))** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text=`n`)**.
|
||||
|
||||
We first **ty = [Compute ty](type(`s`))** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text=`ty`)**.
|
||||
|
||||
Trim, split, join, and index:
|
||||
|
||||
We first **t = [Compute t](trim(value=" hi "))** for the next step.
|
||||
|
||||
We first **parts = [Compute parts](split(value="a,b", sep=","))** for the next step.
|
||||
|
||||
We first **mid = [Compute mid](at(value=`parts`, index=0))** for the next step.
|
||||
|
||||
We first **j = [Compute j](join(value=`parts`, sep="-"))** for the next step.
|
||||
|
||||
We now **[Display this step's result](> print text=`t`)**.
|
||||
|
||||
We now **[Display this step's result](> print text=`mid`)**.
|
||||
|
||||
We now **[Display this step's result](> print text=`j`)**.
|
||||
Executable
+21
@@ -0,0 +1,21 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 中英内核双名
|
||||
description: 无需导入:打印、长度、文本、整数 与 print / len / …
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
内核中英别名等价,可混用:
|
||||
|
||||
我们先**s = "你好"**,供下一步使用。
|
||||
|
||||
我们先**n = [计算并保存 n](长度(值=`s`))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`n`)**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> print text="also-english")**。
|
||||
Executable
+28
@@ -0,0 +1,28 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 布尔与逻辑
|
||||
description: 真 / 假 / 空 与 且 / 或 / 非
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
关键字:`真`、`假`、`空`,以及 `且` / `或` / `非`。
|
||||
|
||||
我们先**a = True**,供下一步使用。
|
||||
我们先**b = False**,供下一步使用。
|
||||
|
||||
1. `a` 且 非 `b`
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="通过")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="失败")**。
|
||||
|
||||
我们先**probe = 1**,供下一步使用。
|
||||
|
||||
1. 空
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="空为真")**。
|
||||
2. *
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="空为假")**。
|
||||
Executable
+19
@@ -0,0 +1,19 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 内置 打印
|
||||
description: 具名与位置两种写法
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
内置 `打印` 接受具名或位置实参:
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="具名写法")**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 "位置写法")**。
|
||||
|
||||
具名实参可以带空格;位置实参不可以。
|
||||
Executable
+39
@@ -0,0 +1,39 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 内置 长度 / 文本 / 整数 与 trim 等
|
||||
description: 主机内置;中文别名覆盖常用几个
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
长度与英文 `type`(类型无中文内核别名,见标准库文档):
|
||||
|
||||
我们先**s = "你好"**,供下一步使用。
|
||||
|
||||
我们先**n = [计算并保存 n](长度(值=`s`))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`n`)**。
|
||||
|
||||
我们先**ty = [计算并保存 ty](type(`s`))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`ty`)**。
|
||||
|
||||
去空白、拆分、拼接、按下标(主机名仍为英文):
|
||||
|
||||
我们先**t = [计算并保存 t](trim(value=" 嗨 "))**,供下一步使用。
|
||||
|
||||
我们先**parts = [计算并保存 parts](split(value="甲,乙", sep=","))**,供下一步使用。
|
||||
|
||||
我们先**mid = [计算并保存 mid](at(value=`parts`, index=0))**,供下一步使用。
|
||||
|
||||
我们先**j = [计算并保存 j](join(value=`parts`, sep="-"))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`t`)**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`mid`)**。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容=`j`)**。
|
||||
Executable
+18
@@ -0,0 +1,18 @@
|
||||
---
|
||||
markup: occlusion
|
||||
title: 内置 输入
|
||||
description: 从 stdin 读一行;可选提示。演示数据写在 frontmatter 输入。
|
||||
输入: 小明
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| result | any | 空值;按顺序执行本页的演示步骤,观察输出或已说明的副作用。 |
|
||||
|
||||
内置「输入」读一行。演示与 marqdo view / 静态导出可在 frontmatter 写「输入:」(或 stdin:)。CLI 也可用管道或 --stdin-file。Live view 可用 Preset input 覆盖。
|
||||
|
||||
我们先**名字 = [计算并保存 名字](输入(提示="名字:"))**,供下一步使用。
|
||||
|
||||
随后我们**[显示当前步骤的结果](> 打印 内容="你好 `名字`!")**。
|
||||
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
Loaded 100 of 226 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user