myform 0.7.0__py3-none-any.whl

myform/Ignore.py

@@ -0,0 +1,191 @@
+"""Skip-formatting ("ignore") comments -- the mdformat #53 gap, filled for MyST.
+
+mdformat core has no way to exempt content from formatting. This module adds the family every
+other formatter ships, as configurable HTML comments (already valid CommonMark, so no new grammar):
+
+- ``<!-- myform-ignore -->`` preserves the *next* block verbatim;
+- ``<!-- myform-ignore-start -->`` ... ``<!-- myform-ignore-end -->`` a range;
+- ``<!-- myform-ignore-file -->`` the whole file.
+
+Markers act only at the **document top level**: one nested inside a list item or blockquote is left
+as an ordinary comment and does not suppress formatting -- acting on it would unbalance the spliced
+token tree and re-apply the container's prefix to the preserved source every run. The marker strings
+are configurable via `MystOptions`.
+
+The mechanism is a ``markdown-it`` core rule that runs after block parsing: the tokens of an ignored
+span are replaced by a single ``myst_ignored`` token carrying the span's *original source*, which
+`Renderer.render_myst_ignored` emits verbatim (an ``html_block`` carrier would ``lstrip`` the first
+line and de-indent preserved code). The replacement is ephemeral -- internal to one render -- and
+the emitted markdown is re-parsed fresh on the next run, so formatting stays idempotent (the marker
+comments are themselves preserved and re-detected).
+"""
+
+############
+### HEAD ###
+############
+### STANDARD
+### EXTERNAL
+import regex as re
+from markdown_it.token import Token
+from markdown_it.rules_core import StateCore
+
+### INTERNAL
+from .options import MystOptions
+
+############
+### DATA ###
+############
+#: Matches an HTML-comment block whose entire content is a single comment, capturing the inner text.
+COMMENT = re.compile(r'\s*<!--\s*(?P<body>.*?)\s*-->\s*\Z', re.DOTALL)
+
+
+############
+### BODY ###
+############
+class Ignore:
+    """The ignore-comment core rule and its token-surgery helpers."""
+
+    @staticmethod
+    def apply(state: StateCore) -> None:
+        """Core rule: replace ignore-marked spans with verbatim-source ``html_block`` tokens."""
+        opts = MystOptions.from_options(
+            state.md.options.get('mdformat', {}).get('plugin', {}).get('myst', {})
+        )
+        markers = (
+            opts.ignore_comment,
+            opts.ignore_start_comment,
+            opts.ignore_end_comment,
+            opts.ignore_file_comment,
+        )
+        # Fast path: nothing that could be a marker appears in the source at all.
+        if not any(marker in state.src for marker in markers):
+            return
+
+        tokens = state.tokens
+        src_lines = state.src.split('\n')
+
+        # File-level: any file marker (at any nesting) preserves the whole document, unchanged.
+        if any(Ignore._marker(tok, opts) == 'file' for tok in tokens):
+            state.tokens = [Ignore._verbatim(src_lines, 0, len(src_lines))]
+            return
+
+        new: list[Token] = []
+        i, n = 0, len(tokens)
+        while i < n:
+            tok = tokens[i]
+            kind = Ignore._marker(tok, opts)
+
+            # `next`/`start` markers act only at the document top level. A marker nested inside a
+            # container (list item, blockquote) is left as an ordinary comment: acting on it would
+            # unbalance the spliced token tree (crash) and re-apply the container prefix to the
+            # preserved source every run (unbounded ``> > x``). The verbatim carrier is always
+            # emitted at level 0, so container blocks it *contains* still round-trip (their source
+            # already carries the right prefixes).
+            if kind == 'next' and tok.level == 0:
+                new.append(tok)  # keep the marker comment itself
+                i += 1
+                # The block to preserve is the next token (markdown-it emits no blank tokens between
+                # blocks). Skip if it is another marker, is nested, or has no source map.
+                nxt = tokens[i] if i < n else None
+                if nxt and nxt.level == 0 and nxt.map and Ignore._marker(nxt, opts) is None:
+                    span, i = Ignore._consume_block(tokens, i)
+                    Ignore._emit_verbatim(new, src_lines, span[0], span[1])
+                continue
+
+            if kind == 'start' and tok.level == 0:
+                new.append(tok)
+                start_map = tok.map
+                start_line = start_map[1] if start_map else 0
+                # Match only a top-level end marker; a nested one would leave the splice unbalanced.
+                j = i + 1
+                while j < n and not (
+                    tokens[j].level == 0 and Ignore._marker(tokens[j], opts) == 'end'
+                ):
+                    j += 1
+                if j < n:  # matched end marker at top level
+                    end_map = tokens[j].map
+                    end_line = end_map[0] if end_map else len(src_lines)
+                    Ignore._emit_verbatim(new, src_lines, start_line, end_line)
+                    new.append(tokens[j])  # keep the end marker
+                    i = j + 1
+                else:  # unterminated range -> preserve to end of document
+                    Ignore._emit_verbatim(new, src_lines, start_line, len(src_lines))
+                    i = n
+                continue
+
+            new.append(tok)
+            i += 1
+
+        state.tokens = new
+
+    # -------------------
+    # `.` Helpers
+    # -------------------
+    @staticmethod
+    def _marker(token: Token, opts: MystOptions) -> str | None:
+        """Classify *token* as an ignore marker: ``next``/``start``/``end``/``file`` or ``None``."""
+        if token.type != 'html_block':
+            return None
+        match = COMMENT.fullmatch(token.content)
+        if not match:
+            return None
+        body = match['body']
+        if body == opts.ignore_file_comment:
+            return 'file'
+        if body == opts.ignore_start_comment:
+            return 'start'
+        if body == opts.ignore_end_comment:
+            return 'end'
+        if body == opts.ignore_comment:
+            return 'next'
+        return None
+
+    @staticmethod
+    def _consume_block(tokens: list[Token], i: int) -> tuple[list[int], int]:
+        """Return ``(source_span, next_index)`` for the block starting at ``tokens[i]``.
+
+        Walks the open/close nest to its matching close, taking the source span from the opener's
+        first line through the *maximum* end line of any token inside. This is required because the
+        plugin's ``myst_directive_open`` maps only the opener line (its closer sits on a separate
+        ``myst_directive_close`` token), unlike stock markdown-it blocks whose opener spans the
+        whole block; the max-end walk is correct for both.
+        """
+        start = tokens[i]
+        start_map = start.map or [0, 0]
+        first_line, last_line = start_map[0], start_map[1]
+        depth = start.nesting
+        j = i + 1
+        while depth > 0 and j < len(tokens):
+            child_map = tokens[j].map
+            if child_map:
+                last_line = max(last_line, child_map[1])
+            depth += tokens[j].nesting
+            j += 1
+        return [first_line, last_line], j
+
+    @staticmethod
+    def _emit_verbatim(new: list[Token], src_lines: list[str], start: int, end: int) -> None:
+        """Append a verbatim carrier for ``src_lines[start:end]`` only when it has content.
+
+        Guards the degenerate empty span (e.g. a bare unterminated ``ignore-start`` at EOF) so no
+        empty block is emitted, which would otherwise add a stray trailing blank line.
+        """
+        token = Ignore._verbatim(src_lines, start, end)
+        if token.content:
+            new.append(token)
+
+    @staticmethod
+    def _verbatim(src_lines: list[str], start_line: int, end_line: int) -> Token:
+        """Build a ``myst_ignored`` token holding ``src_lines[start_line:end_line]`` verbatim.
+
+        Always emitted at the document top level (``level == 0``); its renderer
+        (`Renderer.render_myst_ignored`) returns the source untouched -- unlike an ``html_block``
+        carrier, whose renderer would ``lstrip`` the first line and de-indent preserved code.
+        """
+        token = Token('myst_ignored', '', 0)
+        # ``strip('\n')`` drops the blank lines surrounding a range's content (between the markers)
+        # without touching leading *spaces*, so an indented code block keeps its indent.
+        token.content = '\n'.join(src_lines[start_line:end_line]).strip('\n')
+        token.block = True
+        token.map = [start_line, end_line]
+        return token