python-color-math 0.1.0__py3-none-any.whl

color_math/parsers/math_parser.py

@@ -0,0 +1,366 @@
+"""Lossless structural inspection for the small math subset Color Math uses."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..utils.latex_helpers import read_braced
+from .latex_spans import read_operand
+from .markdown_scanner import scan_markdown
+
+
+COMMAND_RE = re.compile(r"\\[A-Za-z]+|\\.")
+NAME_RE = re.compile(r"[A-Za-z][A-Za-z0-9]*(?:')*")
+NUMBER_RE = re.compile(r"\d+(?:\.\d+)?")
+OPAQUE_MACROS = frozenset({
+    "mathbb",
+    "mathbf",
+    "mathcal",
+    "mathit",
+    "mathrm",
+    "operatorname",
+    "text",
+    "textbf",
+    "textit",
+    "textrm",
+    "texttt",
+    "verb",
+})
+
+
+@dataclass(frozen=True)
+class SemanticSpan:
+    """A recognized source range, kept without rewriting its LaTeX."""
+
+    kind: str
+    value: str
+    start: int
+    end: int
+    depth: int
+
+
+@dataclass(frozen=True)
+class ParsedMath:
+    source: str
+    normalized: str
+    expression: tuple[SemanticSpan, ...]
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+
+def _read_command(text: str, start: int, end: int) -> tuple[str, int] | None:
+    match = COMMAND_RE.match(text, start, end)
+    if match is None:
+        return None
+    return match.group(0), match.end()
+
+
+def _skip_whitespace(text: str, start: int, end: int) -> int:
+    while start < end and text[start].isspace():
+        start += 1
+    return start
+
+
+def _skip_comment(text: str, start: int, end: int) -> int:
+    index = start + 1
+    while index < end and text[index] not in "\r\n":
+        index += 1
+    if index < end and text[index] == "\r" and index + 1 < end and text[index + 1] == "\n":
+        return index + 2
+    return min(index + 1, end)
+
+
+def _read_delimiter(text: str, start: int, end: int) -> tuple[str, int] | None:
+    if start >= end:
+        return None
+    if text[start] != "\\":
+        return text[start], start + 1
+    return _read_command(text, start, end)
+
+
+def _skip_opaque_argument(text: str, start: int, end: int) -> int:
+    start = _skip_whitespace(text, start, end)
+    group = read_braced(text, start)
+    return group[1] if group is not None and group[1] <= end else start
+
+
+def _read_left_right_group(
+    text: str,
+    start: int,
+    end: int,
+) -> tuple[str, int, int, int] | None:
+    command = _read_command(text, start, end)
+    if command is None or command[0] != r"\left":
+        return None
+
+    delimiter_data = _read_delimiter(
+        text,
+        _skip_whitespace(text, command[1], end),
+        end,
+    )
+    if delimiter_data is None:
+        return None
+
+    opening, content_start = delimiter_data
+    depth = 1
+    index = content_start
+
+    while index < end:
+        if text[index] == "%":
+            index = _skip_comment(text, index, end)
+            continue
+        if text[index] == "{":
+            group = read_braced(text, index)
+            if group is None or group[1] > end:
+                return None
+            index = group[1]
+            continue
+
+        if text[index] != "\\":
+            index += 1
+            continue
+
+        nested_command = _read_command(text, index, end)
+        if nested_command is None:
+            index += 1
+            continue
+
+        name, command_end = nested_command
+        if name == r"\left":
+            delimiter = _read_delimiter(
+                text,
+                _skip_whitespace(text, command_end, end),
+                end,
+            )
+            if delimiter is not None:
+                depth += 1
+                index = delimiter[1]
+                continue
+        elif name == r"\right":
+            delimiter = _read_delimiter(
+                text,
+                _skip_whitespace(text, command_end, end),
+                end,
+            )
+            if delimiter is not None:
+                depth -= 1
+                if depth == 0:
+                    return opening, content_start, index, delimiter[1]
+                index = delimiter[1]
+                continue
+        else:
+            operand = read_operand(text, index, end)
+            if operand is not None and operand.kind == "opaque":
+                index = operand.end
+                continue
+
+        if name[1:] in OPAQUE_MACROS:
+            opaque_end = _skip_opaque_argument(text, command_end, end)
+            if opaque_end != command_end:
+                index = opaque_end
+                continue
+
+        index = command_end
+
+    return None
+
+
+def _read_plain_parentheses(
+    text: str,
+    start: int,
+    end: int,
+) -> tuple[int, int, int] | None:
+    depth = 1
+    index = start + 1
+
+    while index < end:
+        if text[index] == "%":
+            index = _skip_comment(text, index, end)
+            continue
+        if text[index] == "{":
+            group = read_braced(text, index)
+            if group is None or group[1] > end:
+                return None
+            index = group[1]
+            continue
+
+        if text[index] == "\\":
+            operand = read_operand(text, index, end)
+            if operand is not None and operand.kind == "opaque":
+                index = operand.end
+                continue
+            command = _read_command(text, index, end)
+            if command is None:
+                index += 1
+                continue
+
+            name, command_end = command
+            if name == r"\left":
+                group = _read_left_right_group(text, index, end)
+                if group is not None:
+                    index = group[3]
+                    continue
+            elif name[1:] in OPAQUE_MACROS:
+                opaque_end = _skip_opaque_argument(text, command_end, end)
+                if opaque_end != command_end:
+                    index = opaque_end
+                    continue
+
+            index = command_end
+            continue
+
+        if text[index] == "(":
+            depth += 1
+        elif text[index] == ")":
+            depth -= 1
+            if depth == 0:
+                return start + 1, index, index + 1
+
+        index += 1
+
+    return None
+
+
+def _read_function_arguments(
+    text: str,
+    start: int,
+    end: int,
+) -> tuple[int, int, int] | None:
+    if start >= end:
+        return None
+    if text[start] == "(":
+        return _read_plain_parentheses(text, start, end)
+
+    group = _read_left_right_group(text, start, end)
+    if group is None or group[0] not in {"(", r"\("}:
+        return None
+    return group[1:]
+
+
+def _collect_semantic_spans(
+    text: str,
+    start: int,
+    end: int,
+    depth: int,
+    spans: list[SemanticSpan],
+    errors: list[str],
+) -> None:
+    index = start
+    while index < end:
+        if text[index] == "%":
+            index = _skip_comment(text, index, end)
+            continue
+        if text[index] == "\\":
+            operand = read_operand(text, index, end)
+            if operand is not None and operand.kind == "opaque":
+                index = operand.end
+                continue
+            command = _read_command(text, index, end)
+            if command is not None:
+                name, command_end = command
+                if name[1:] in OPAQUE_MACROS:
+                    opaque_end = _skip_opaque_argument(text, command_end, end)
+                    if opaque_end != command_end:
+                        index = opaque_end
+                        continue
+                index = command_end
+                continue
+
+        name_match = NAME_RE.match(text, index, end)
+        if name_match is not None:
+            name_end = name_match.end()
+            arguments = _read_function_arguments(text, name_end, end)
+            if arguments is not None:
+                argument_start, argument_end, call_end = arguments
+                spans.append(
+                    SemanticSpan(
+                        "function",
+                        name_match.group(0),
+                        index,
+                        name_end,
+                        depth,
+                    )
+                )
+                _collect_semantic_spans(
+                    text,
+                    argument_start,
+                    argument_end,
+                    depth + 1,
+                    spans,
+                    errors,
+                )
+                index = call_end
+                continue
+
+            if name_end < end and text[name_end] == "(":
+                errors.append(f"unclosed function call after {name_match.group(0)!r}")
+            index = name_end
+            continue
+
+        number_match = NUMBER_RE.match(text, index, end) if depth else None
+        if number_match is not None:
+            spans.append(
+                SemanticSpan(
+                    "constant",
+                    number_match.group(0),
+                    index,
+                    number_match.end(),
+                    depth,
+                )
+            )
+            index = number_match.end()
+            continue
+
+        index += 1
+
+
+def find_semantic_spans(source: str) -> tuple[tuple[SemanticSpan, ...], str | None]:
+    """Recognize plain nested calls and constants without rewriting LaTeX."""
+    spans: list[SemanticSpan] = []
+    errors: list[str] = []
+    _collect_semantic_spans(source, 0, len(source), 0, spans, errors)
+    return tuple(spans), errors[0] if errors else None
+
+
+def format_math_structure(parsed: ParsedMath) -> str:
+    if not parsed.expression:
+        return "No nested function calls found."
+    return "\n".join(
+        f"{'  ' * span.depth}{span.kind.title()} {span.value}"
+        for span in parsed.expression
+    )
+
+
+def parser_available() -> bool:
+    """The built-in structural inspector has no optional dependencies."""
+    return True
+
+
+def parse_math_body(body: str) -> ParsedMath:
+    spans, error = find_semantic_spans(body)
+    return ParsedMath(body, body, spans, error)
+
+
+def parse_math_blocks(text: str) -> list[ParsedMath]:
+    return [
+        parse_math_body(text[span.content_start:span.content_end])
+        for span in scan_markdown(text).math_blocks
+    ]
+
+
+def describe_math_blocks(text: str) -> str:
+    blocks = parse_math_blocks(text)
+    if not blocks:
+        return "No $$...$$ math blocks found."
+
+    lines: list[str] = []
+    for index, parsed in enumerate(blocks, 1):
+        lines.append(f"Block {index}: {'OK' if parsed.ok else 'FAIL'}")
+        lines.append(format_math_structure(parsed) if parsed.ok else parsed.error or "unknown parse error")
+        lines.append("")
+
+    return "\n".join(lines).rstrip()

color_math/parsers/scanner.py

@@ -0,0 +1,351 @@
+"""Collect generic, source-preserving LaTeX color spans."""
+
+from __future__ import annotations
+
+import re
+
+from ..config import COLORS, FUNCTION_COMMANDS, SORTED_COLOR_COMMANDS
+from ..utils.coloring import command_color
+from ..utils.latex_helpers import read_color_command
+from ..utils.spans import ColorSpan, apply_color_spans
+from .latex_spans import (
+    MATRIX_ENVIRONMENTS,
+    UNARY_MACROS,
+    find_all_operator_spans,
+    find_operand_spans,
+    find_script_argument_spans,
+    read_command,
+    read_environment_end,
+    read_group_end,
+    read_operand,
+    skip_ignorable,
+)
+
+
+COMMAND_RE = re.compile(r"\\[A-Za-z]+|\\.")
+LAYOUT_ENVIRONMENTS = MATRIX_ENVIRONMENTS | frozenset({
+    "align",
+    "align*",
+    "aligned",
+    "cases",
+    "gather",
+    "gather*",
+    "gathered",
+    "split",
+})
+STRUCTURED_COMMANDS = {
+    "binom": 2,
+    "boxed": 1,
+    "cancel": 1,
+    "dfrac": 2,
+    "frac": 2,
+    "overbrace": 1,
+    "phantom": 1,
+    "tfrac": 2,
+    "underbrace": 1,
+}
+SEMANTIC_COLOR_NAMES = ("main", "derivative", "chain")
+
+
+def _argument_range(
+    source: str,
+    start: int,
+    end: int,
+) -> tuple[int, int, int] | None:
+    start = skip_ignorable(source, start, end)
+    if start >= end:
+        return None
+    if source[start] in "{([":
+        group_end = read_group_end(source, start, end)
+        if group_end is None:
+            return None
+        return start + 1, group_end - 1, group_end
+    if source[start] != "\\":
+        return start, start + 1, start + 1
+    operand = read_operand(source, start, end)
+    if operand is None:
+        return start, start + 1, start + 1
+    return operand.start, operand.end, operand.end
+
+
+def _operand_color_spans(
+    source: str,
+    start: int,
+    end: int,
+    offset: int,
+) -> list[ColorSpan]:
+    spans: list[ColorSpan] = []
+    semantic_index = 0
+    for operand in find_operand_spans(source, start, end):
+        if operand.kind == "number":
+            color = COLORS["orange"]
+        else:
+            color = COLORS[
+                SEMANTIC_COLOR_NAMES[
+                    (offset + semantic_index) % len(SEMANTIC_COLOR_NAMES)
+                ]
+            ]
+            semantic_index += 1
+        spans.append(ColorSpan(operand.start, operand.end, color, priority=5))
+    return spans
+
+
+def _environment_content(
+    source: str,
+    start: int,
+    end: int,
+) -> tuple[str, int, int, int] | None:
+    command = read_command(source, start, end)
+    if command is None or command[0] != "begin":
+        return None
+    name_start = skip_ignorable(source, command[1], end)
+    name_end = read_group_end(source, name_start, end)
+    environment = read_environment_end(source, start, end)
+    if name_end is None or environment is None:
+        return None
+    name, environment_end = environment
+    content_start = name_end
+    if name == "array":
+        preamble_start = skip_ignorable(source, content_start, environment_end)
+        preamble_end = read_group_end(source, preamble_start, environment_end)
+        if preamble_end is not None:
+            content_start = preamble_end
+    closing_start = source.rfind(r"\end", content_start, environment_end)
+    if closing_start < content_start:
+        return None
+    return name, content_start, closing_start, environment_end
+
+
+def _layout_cells(source: str, start: int, end: int) -> list[tuple[int, int]]:
+    cells: list[tuple[int, int]] = []
+    cell_start = start
+    index = start
+    while index < end:
+        if source[index] == "%":
+            newline = source.find("\n", index + 1, end)
+            index = end if newline < 0 else newline + 1
+            continue
+        if source[index] == "&":
+            cells.append((cell_start, index))
+            cell_start = index + 1
+            index += 1
+            continue
+        if source[index] == "\\":
+            command = read_command(source, index, end)
+            if command is not None and command[0] == "\\":
+                cells.append((cell_start, index))
+                cell_start = command[1]
+                index = command[1]
+                continue
+        operand = read_operand(source, index, end)
+        if operand is not None:
+            index = max(index + 1, operand.end)
+            continue
+        index += 1
+    cells.append((cell_start, end))
+    return cells
+
+
+def collect_structured_spans(body: str) -> list[ColorSpan]:
+    """Color operands inside structured commands and layout environments."""
+    spans: list[ColorSpan] = []
+    index = 0
+    while index < len(body):
+        if body[index] != "\\":
+            index += 1
+            continue
+        command = read_command(body, index, len(body))
+        if command is None:
+            index += 1
+            continue
+        name, command_end = command
+
+        if name == "begin":
+            environment = _environment_content(body, index, len(body))
+            if environment is not None and environment[0] in LAYOUT_ENVIRONMENTS:
+                _, content_start, content_end, _ = environment
+                for offset, (start, end) in enumerate(
+                    _layout_cells(body, content_start, content_end)
+                ):
+                    spans.extend(_operand_color_spans(body, start, end, offset))
+
+        argument_count = STRUCTURED_COMMANDS.get(name)
+        if name in UNARY_MACROS:
+            argument_count = 1
+        if name == "sqrt":
+            optional_start = skip_ignorable(body, command_end, len(body))
+            if optional_start < len(body) and body[optional_start] == "[":
+                optional_end = read_group_end(body, optional_start, len(body))
+                if optional_end is not None:
+                    spans.extend(
+                        _operand_color_spans(
+                            body,
+                            optional_start + 1,
+                            optional_end - 1,
+                            1,
+                        )
+                    )
+                    command_end = optional_end
+            argument_count = 1
+
+        argument_start = command_end
+        for offset in range(argument_count or 0):
+            argument = _argument_range(body, argument_start, len(body))
+            if argument is None:
+                break
+            start, end, argument_start = argument
+            spans.extend(_operand_color_spans(body, start, end, offset))
+        index = command[1]
+    return spans
+
+
+def collect_operator_spans(
+    body: str,
+    start: int = 0,
+    end: int | None = None,
+) -> list[ColorSpan]:
+    """Color complete operators, including attached limits and scripts."""
+    spans: list[ColorSpan] = []
+    for operator in find_all_operator_spans(body, start, end):
+        command = COMMAND_RE.match(body, operator.start, operator.end)
+        if command is not None:
+            spans.append(
+                ColorSpan(
+                    operator.start,
+                    operator.end,
+                    command_color(command.group(0)),
+                    priority=30,
+                )
+            )
+    return spans
+
+
+def collect_scanner_spans(body: str) -> list[ColorSpan]:
+    """Find generic operators and script arguments without rewriting LaTeX."""
+    scripts = find_script_argument_spans(body)
+    operators = find_all_operator_spans(body)
+    spans = [
+        ColorSpan(
+            item.start,
+            item.end,
+            COLORS["chain" if item.kind == "subscript" else "upper"],
+            priority=10,
+        )
+        for item in scripts
+    ]
+    spans.extend(collect_operator_spans(body))
+    spans.extend(collect_structured_spans(body))
+    script_ranges = tuple((item.start, item.end) for item in scripts)
+    operator_ranges = tuple((item.start, item.end) for item in operators)
+
+    index = 0
+    while index < len(body):
+        if body[index] == "%":
+            line_end = index + 1
+            while line_end < len(body) and body[line_end] not in "\r\n":
+                line_end += 1
+            if (
+                line_end < len(body)
+                and body[line_end] == "\r"
+                and line_end + 1 < len(body)
+                and body[line_end + 1] == "\n"
+            ):
+                line_end += 2
+            elif line_end < len(body):
+                line_end += 1
+            index = line_end
+            continue
+
+        existing = read_color_command(body, index)
+        if existing is not None:
+            index = existing[1]
+            continue
+
+        operand = read_operand(body, index)
+        if operand is not None and operand.kind == "opaque":
+            index = operand.end
+            continue
+
+        containing_operator = next(
+            (
+                (start, end)
+                for start, end in operator_ranges
+                if start <= index < end
+            ),
+            None,
+        )
+        if containing_operator is not None:
+            index = containing_operator[1]
+            continue
+
+        containing_script = next(
+            (
+                (start, end)
+                for start, end in script_ranges
+                if start <= index < end
+            ),
+            None,
+        )
+        if containing_script is not None:
+            index = containing_script[1]
+            continue
+
+        command_match = COMMAND_RE.match(body, index)
+        if command_match is not None:
+            command = command_match.group(0)
+            if command in SORTED_COLOR_COMMANDS:
+                spans.append(
+                    ColorSpan(
+                        index,
+                        command_match.end(),
+                        command_color(command),
+                    )
+                )
+            elif command in FUNCTION_COMMANDS:
+                spans.append(
+                    ColorSpan(
+                        index,
+                        command_match.end(),
+                        COLORS["main"],
+                        priority=20,
+                    )
+                )
+            elif command == r"\operatorname":
+                argument_start = command_match.end()
+                if argument_start < len(body) and body[argument_start] == "*":
+                    argument_start += 1
+                argument_start = skip_ignorable(body, argument_start, len(body))
+                argument_end = read_group_end(body, argument_start, len(body))
+                if argument_end is not None:
+                    spans.append(
+                        ColorSpan(index, argument_end, COLORS["main"], priority=20)
+                    )
+            index = command_match.end()
+            if index < len(body) and body[index] == "*":
+                index += 1
+            continue
+
+        command = next(
+            (
+                candidate
+                for candidate in SORTED_COLOR_COMMANDS
+                if not candidate.startswith("\\")
+                and body.startswith(candidate, index)
+            ),
+            None,
+        )
+        if command is not None:
+            spans.append(
+                ColorSpan(index, index + len(command), command_color(command))
+            )
+            index += len(command)
+            continue
+
+        index += 1
+
+    return spans
+
+
+def color_latex_body_with_scanner(body: str) -> str:
+    """Color generic LaTeX tokens by inserting scoped wrappers."""
+    return apply_color_spans(body, collect_scanner_spans(body))