Documentation
¶
Overview ¶
Package embedded — Embedded-mode structural parser.
Scan() (defined in scanner.go) provides single-pass segmentation of a markdown source into Passthrough and CalcMarkBlock segments. BuildDocument() projects those segments into a real *spec/document.Document with proper block kinds: each cm/calcmark fence becomes one *CalcBlock, each passthrough segment becomes one *TextBlock, all wrapped in BlockNodes with UUIDs and stitched together via spec/document.NewDocumentFromBlocks.
All CalcBlocks land in the SAME *Document, so the existing impldoc.Evaluator naturally resolves variables across fences (whole-doc scoping). This intentionally diverges from the rendering pipeline at convert.go:convertEmbedded, which evaluates each fence in isolation. Consumers that want cross-fence variable resolution and passthrough interpolation use BuildDocument (via the top-level calcmark.NewDocumentEmbedded facade); consumers that want per-fence-isolated rendering keep using Convert.
Per-segment projection rule (from the 2026-05-02-001 plan, U2): EXACTLY ONE block per segment. Do NOT call Detector.DetectBlocks on segment content — that would reintroduce the heuristic-bleed bug that motivated this whole architecture (see calcmark-web's prove-it run 2026-05-02-1315). The fence boundaries from Scan are the truth; per-segment content is one block of its kind.
Frontmatter handling lands in U4 — for now BuildDocument always passes nil for the frontmatter argument so a leading ---...--- segment becomes a TextBlock.
Package embedded scans standard markdown documents for cm/calcmark fenced code blocks and splits the input into passthrough and CalcMark segments.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildDocument ¶ added in v2.2.0
BuildDocument scans an Embedded-mode source (markdown with cm/calcmark fences) into a *spec/document.Document whose blocks reflect the fence boundaries:
- Each cm/calcmark fenced segment becomes one *specDoc.CalcBlock with the fence's inner content as its source.
- Each passthrough markdown segment becomes one *specDoc.TextBlock with the passthrough text as its source.
- A leading ---...--- segment is parsed as the document's *specDoc.Frontmatter via spec/document.ParseFrontmatter and does NOT also produce a TextBlock. Any text remaining after the closing --- (in the same passthrough segment) projects as a TextBlock.
Empty source returns an empty *Document with zero blocks. Sources with zero cm/calcmark fences return a single TextBlock containing the whole source (Embedded mode degrades gracefully to "all passthrough markdown" for fence-less input).
Frontmatter parse failures (e.g., unclosed `---`) silently fall back to projecting the offending segment as a TextBlock so the body still renders — matches NewDocument's tolerance for malformed frontmatter at the body level.
Types ¶
type Segment ¶
type Segment struct {
Kind SegmentKind
Text string // For Passthrough: the raw text (including newlines). For CalcMarkBlock: the block content (without fence lines).
OpenLine int // 1-based line number of the opening fence in the host document (0 for Passthrough).
}
Segment represents either passthrough markdown text or an extracted CalcMark block.
type SegmentKind ¶
type SegmentKind int
SegmentKind distinguishes passthrough text from CalcMark blocks.
const ( // Passthrough represents markdown text that is not a CalcMark block. Passthrough SegmentKind = iota // CalcMarkBlock represents an extracted CalcMark fenced code block. CalcMarkBlock )
Source Files