#selfdoc.directives

#selfdoc.directives

Directive parser for selfdoc's structured marker syntax.

Directive syntax: One-liner: :-: name key="value" ... Block open: :<: name [key="value" ...] Attr line: :@: key="value" Body sep: :=: Body line: ::: content Block close: :>:

Directives inside fenced code blocks ( or ~~~) are ignored. Unclosed block directives at EOF raise DirectiveError.

#DirectiveError

Raised when a directive is malformed (e.g. unclosed at EOF).

#Directive

A parsed directive block.

#_parse_attrs

def _parse_attrs(text: str) -> dict[str, str]

Extract all key="value" pairs from a string.

#_walk_blocks

def _walk_blocks(content: str, valid_names: set[str] | None=None)

Shared state machine for fence-tracking and directive detection.

Yields one of three event types per logical unit: ("line", line) -- non-directive line ("directive", name, attrs, body, line_num) -- a complete directive ("unclosed", name, line_num) -- unclosed block at EOF

#parse_directives

def parse_directives(content: str, valid_names: set[str] | None=None) -> list[Directive]

Extract all directive blocks from markdown content.

Returns a list of Directive dataclass instances in document order. Directives inside fenced code blocks are ignored. Raises DirectiveError if a directive is opened but never closed, or if a directive name is not in valid_names (when provided).

#resolve_directives

def resolve_directives(content: str, resolver: callable, valid_names: set[str] | None=None) -> str

Replace each directive with the output of resolver(name, attrs, body).

Non-directive content passes through unchanged. Directives inside fenced code blocks are left as-is (they are not directives).