Files
marqdo/lib/document.mq.md
T

6.5 KiB

markup
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

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:

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).

参数 类型 默认 说明
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).