156 lines
6.5 KiB
Markdown
156 lines
6.5 KiB
Markdown
---
|
|
markup: occlusion
|
|
---
|
|
|
|
Inert document operations share the renderer Markdown parser. Every function is pure.
|
|
|
|
Inspect and transform Markdown without executing its contents.
|
|
|
|
Behavior and limits: Shares the Markdown parser with rendering and recognizes YAML frontmatter. Spans are original UTF-8 byte offsets. Duplicate section names fail. Replacement preserves surrounding source; persist via fs.write_checked.
|
|
|
|
This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.
|
|
|
|
Implementation: [src/host/document.rs](../src/host/document.rs)
|
|
|
|
For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.
|
|
|
|
## sections
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| text | text | required | Text to read, transform or emit as described by this operation |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | list | List headings with original UTF-8 byte spans and body text; nested sections end at the next same-or-higher heading |
|
|
|
|
Use `text` as the inputs for this operation.
|
|
|
|
Effects: pure.
|
|
|
|
Call this function directly:
|
|
|
|
```sh
|
|
marqdo call lib/document.mq.md sections 'text="# Notes"' --effects none --json
|
|
```
|
|
|
|
List headings with original UTF-8 byte spans and body text; nested sections end at the next same-or-higher heading. No execution.
|
|
|
|
Return *[List headings with original UTF-8 byte spans and body text; nested sections end at the next same-or-higher heading](> host_document_sections text=`text`)*.
|
|
|
|
## section
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| text | text | required | Text to read, transform or emit as described by this operation |
|
|
| title | text | required | Exact, unique Markdown heading title |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | text | Read the body under one exact heading; missing or duplicate headings fail |
|
|
|
|
Use `text`, `title` as the inputs for this operation.
|
|
|
|
Effects: pure.
|
|
|
|
Read the body under one exact heading; missing or duplicate headings fail.
|
|
|
|
Return *[Read the body under one exact heading; missing or duplicate headings fail](> host_document_section text=`text` title=`title`)*.
|
|
|
|
## replace_section
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| text | text | required | Text to read, transform or emit as described by this operation |
|
|
| title | text | required | Exact, unique Markdown heading title |
|
|
| body | text | required | Request body, or replacement text for document operations |
|
|
| expected_sha256 | any | None | Digest of the exact prior text; None disables the check where allowed |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | map | Return Result with replaced section body, preserving its heading and surrounding source |
|
|
|
|
Use `text`, `title`, `body`, `expected_sha256`=None as the inputs for this operation.
|
|
|
|
Effects: pure.
|
|
|
|
Return Result with replaced section body, preserving its heading and surrounding source. Optional digest checks the whole source. Pure transform; persist via fs.write_checked.
|
|
|
|
Return *[Return Result with replaced section body, preserving its heading and surrounding source](> host_document_replace_section text=`text` title=`title` body=`body` expected_sha256=`expected_sha256`)*.
|
|
|
|
## tables
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| text | text | required | Text to read, transform or emit as described by this operation |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | list | Extract inert GFM headers and cell text, plus original byte ranges; cells are never evaluated |
|
|
|
|
Use `text` as the inputs for this operation.
|
|
|
|
Effects: pure.
|
|
|
|
Extract inert GFM headers and cell text, plus original byte ranges; cells are never evaluated.
|
|
|
|
Return *[Extract inert GFM headers and cell text, plus original byte ranges; cells are never evaluated](> host_document_tables text=`text`)*.
|
|
|
|
## replace_table
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| text | text | required | Text to read, transform or emit as described by this operation |
|
|
| index | number | required | Zero-based table index in source order |
|
|
| headers | list | required | Ordered list of table header text |
|
|
| rows | list | required | List of cell-text lists; each row must match the header width |
|
|
| expected_sha256 | any | None | Digest of the exact prior text; None disables the check where allowed |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | map | Replace the zero-based table from text headers and rows, preserving all surrounding source; return Result |
|
|
|
|
Use `text`, `index`, `headers`, `rows`, `expected_sha256`=None as the inputs for this operation.
|
|
|
|
Effects: pure.
|
|
|
|
Replace the zero-based table from text headers and rows, preserving all surrounding source; return Result.
|
|
|
|
Return *[Replace the zero-based table from text headers and rows, preserving all surrounding source; return Result](> host_document_replace_table text=`text` index=`index` headers=`headers` rows=`rows` expected_sha256=`expected_sha256`)*.
|
|
|
|
## links
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| text | text | required | Text to read, transform or emit as described by this operation |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | list | List Markdown link labels and targets with byte spans; never follow or execute them |
|
|
|
|
Use `text` as the inputs for this operation.
|
|
|
|
Effects: pure.
|
|
|
|
List Markdown link labels and targets with byte spans; never follow or execute them.
|
|
|
|
Return *[List Markdown link labels and targets with byte spans; never follow or execute them](> host_document_links text=`text`)*.
|
|
|
|
## code_blocks
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| text | text | required | Text to read, transform or emit as described by this operation |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| result | list | List code fence language and literal source with byte spans; never run foreign or Marqdo code |
|
|
|
|
Use `text` as the inputs for this operation.
|
|
|
|
Effects: pure.
|
|
|
|
List code fence language and literal source with byte spans; never run foreign or Marqdo code.
|
|
|
|
Return *[List code fence language and literal source with byte spans; never run foreign or Marqdo code](> host_document_code_blocks text=`text`)*.
|