Blocks
rn_forge.commons.fs.blocks
Managed blocks: one owner's fenced region inside a file another owner writes.
A :class:ManagedBlock owns the bytes between two markers and preserves the
rest of the file.
Example::
block = ManagedBlock("my-tool")
text = block.render(gitignore_text, ".my-tool/backups/\n")
block.extract(text) # -> '.my-tool/backups/\n'
block.remove(text) # -> the original text
HASH_COMMENT = '#'
module-attribute
Comment style for #-commented files (.gitignore, YAML, TOML, Python).
HTML_COMMENT = '<!--'
module-attribute
Comment style for Markdown and HTML.
ManagedBlock(name, comment=HASH_COMMENT, indent='', end_indent=None)
dataclass
A named, fenced region of a file owned by one generator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The block's name, appearing in both markers. Two blocks in one file must not share a name. |
required |
comment
|
str
|
|
HASH_COMMENT
|
indent
|
str
|
Leading whitespace the markers carry, for formats where the
block sits inside an indented structure ( |
''
|
end_indent
|
str | None
|
Leading whitespace of the end marker alone. |
None
|
begin
property
The opening marker line, without its trailing newline.
end
property
The closing marker line, without its trailing newline.
extract(text)
Return the block's body, or None when the block is absent.
The body is everything strictly between the markers (``""`` for an
empty block), with the file's newline sequence normalised to ``"
"`` so that it compares equal to freshly rendered content regardless of how the file on disk is terminated.
Raises:
AppException: The markers are malformed (see :meth:`render`).
remove(text)
Return text with the block and its markers removed.
A single blank line left immediately before the removed block is
dropped with it — that is the separator :meth:render inserts, so
repeated render/remove cycles do not accumulate whitespace. Any
further blank lines were the file's own and are kept. Returns text
unchanged when the block is absent.
Raises:
| Type | Description |
|---|---|
AppException
|
The markers are malformed (see :meth: |
render(text, body)
Return text with the block's body replaced by body.
When the block is absent it is appended to the end of text, separated by a blank line. Everything outside the markers is preserved byte for byte: the surrounding text keeps its own newline sequences, its indentation and its lack (or presence) of a terminal newline. Inside the markers the generator owns the bytes, so body is re-terminated with the newline sequence the file itself uses.
Raises:
| Type | Description |
|---|---|
AppException
|
A marker appears more than once, one marker is present without the other, or they appear in the wrong order. |