topmark.processors.builtins.cblock

topmark / processors / builtins / cblock

Header processor for C-like block comments: / ... / with per-line *.

This is ideal for CSS and friends (SCSS, Less, Stylus), and works for any format that accepts C-style block comments (SQL, Solidity, etc.).

Layout example:

/ * topmark:start * * project : TopMark * file : styles.css * ... * * topmark:end /

We emit the wrapper lines '/' and '/' and render inner lines as '* ...'.

CBlockHeaderProcessor

CBlockHeaderProcessor()

Bases: BlockCommentMixin, HeaderProcessor

Processor for C-style block comment headers (uses BlockCommentMixin).

Source code in src/topmark/processors/builtins/cblock.py

def __init__(self) -> None:
    # Defer to base initializer; class attributes define affixes/indent.
    super().__init__()

line_has_directive

line_has_directive(line, directive)

Check whether a line contains the directive with the expected affixes.

This method is used by get_header_bounds() to locate header start/end markers. Subclasses may override this method for more flexible or format-specific matching.

Parameters:

Name	Type	Description	Default
line	str	The line of text to check (whitespace is trimmed internally).	required
directive	str	The directive string to look for.	required

Returns:

Type	Description
bool	True if the line contains the directive with the configured prefix/suffix,
bool	otherwise False.

Source code in src/topmark/processors/builtins/cblock.py

def line_has_directive(self, line: str, directive: str) -> bool:
    """Check whether a line contains the directive with the expected affixes.

    This method is used by ``get_header_bounds()`` to locate header start/end markers.
    Subclasses may override this method for more flexible or format-specific matching.

    Args:
        line: The line of text to check (whitespace is trimmed internally).
        directive: The directive string to look for.

    Returns:
        ``True`` if the line contains the directive with the configured prefix/suffix,
        otherwise ``False``.
    """
    s: str = line.strip()
    # Case 1: "* <directive>"
    if s.startswith(self.line_prefix):
        candidate: str = s[len(self.line_prefix) :].strip()
        if candidate == directive:
            return True
    # Case 2: "<directive>" (no per-line prefix)
    return s == directive

prepare_header_for_insertion

prepare_header_for_insertion(
    *,
    original_lines,
    insert_index,
    rendered_header_lines,
    newline_style,
)

Ensure sensible padding around the header.

• At top-of-file: no leading blank; ensure >=1 trailing blank unless next line is blank/EOF.
• After preceding content: ensure exactly one leading blank; ensure >=1 trailing blank.

Parameters:

Name	Type	Description	Default
original_lines	list[str]	The original file lines.	required
insert_index	int	Line index at which the header will be inserted.	required
rendered_header_lines	list[str]	The header lines to insert.	required
newline_style	str	Newline style (LF, CR, CRLF).	required

Returns:

Type	Description
list[str]	Possibly modified header lines to insert at insert_index.

Source code in src/topmark/processors/builtins/cblock.py

def prepare_header_for_insertion(
    self,
    *,
    original_lines: list[str],
    insert_index: int,
    rendered_header_lines: list[str],
    newline_style: str,
) -> list[str]:
    """Ensure sensible padding around the header.

    - At top-of-file: no leading blank; ensure >=1 trailing blank unless next line is blank/EOF.
    - After preceding content: ensure exactly one leading blank; ensure >=1 trailing blank.

    Args:
        original_lines: The original file lines.
        insert_index: Line index at which the header will be inserted.
        rendered_header_lines: The header lines to insert.
        newline_style: Newline style (``LF``, ``CR``, ``CRLF``).

    Returns:
        Possibly modified header lines to insert at ``insert_index``.
    """
    out: list[str] = list(rendered_header_lines)

    # Leading padding
    if insert_index > 0:
        prev_is_blank: bool = (
            insert_index - 1 < len(original_lines)
            and original_lines[insert_index - 1].strip() == ""
        )
        if not prev_is_blank:
            out = [newline_style] + out

    # Trailing padding
    next_is_blank: bool = (
        insert_index < len(original_lines) and original_lines[insert_index].strip() == ""
    )
    if not next_is_blank:
        out = out + [newline_style]

    return out