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