Module managed_block 

Generic managed-block writer: insert/update/remove a delimited region inside an existing text file, idempotently, while preserving sibling content.

Multiple klasp surfaces write a “managed block” — a region bracketed by a Markers::start / Markers::end line pair that other tools must leave alone. The AGENTS.md writer (crate’s klasp-agents-codex sibling, markdown), the git-hook writer (shell, with a shebang prelude), and future YAML config writers all share the same insert/update/remove algorithm; only their marker constants and an optional file-format prelude differ. This module is that shared algorithm; callers map BlockError onto their own crate-local error type and supply the file-format framing via Prelude.

Contract

• Idempotency. install(install(input)) == install(input). The block contents are anchored by the marker lines; re-running install replaces only what’s between them.
• Preservation. Bytes outside the managed block are returned unchanged, with one tolerated normalisation: trailing-newline state is canonicalised to a single \n when install appended (or uninstall stripped) the block.
• Round-trip. uninstall(install(input)) is input after normalising the trailing-newline state to a single \n (or the empty string when input was empty or whitespace-only, modulo a prelude that owned the whole file).

Structs

Markers

The marker line pair that brackets a managed block.

Prelude

Optional file-format prelude prepended ahead of the block when install has to fresh-create a file (or when appending to a file that lacks it).

Span

Byte span of the managed block within the host string, including both markers and the trailing \n after the end marker (when present). The span is a clean cut: text[..span.start] + new_block + text[span.end..] replaces the block while preserving everything around it.

Enums

BlockError

Errors the managed-block writer can raise.

Functions

contains_block

true when existing already contains a (well-formed) managed block.

find_block

Locate the managed block bracketed by markers within existing.

install_block

Insert (or update) the managed block in existing, returning the new file body.

render_block

Render the full managed block (markers + body) for embedding in a host file.

uninstall_block

Inverse of install_block: remove the managed block and the blank-line separator install inserted when it appended the block.