texer 0.5.12__py3-none-any.whl

texer/tables.py

@@ -0,0 +1,338 @@
+"""Table classes for LaTeX table generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from texer.specs import Spec, resolve_value, Iter
+from texer.utils import escape_latex, format_options, indent
+
+
+@dataclass
+class Cell:
+    """A table cell with optional formatting.
+
+    Examples:
+        Cell(Ref("value"))
+        Cell(Ref("value"), bold=True)
+        Cell(Format(Ref("price"), ".2f"), align="r")
+        Cell(Ref("name"), bold=Cond(Ref("important"), True, False))
+    """
+
+    content: Any
+    bold: bool | Spec = False
+    italic: bool | Spec = False
+    align: str | None = None
+
+    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
+        """Render the cell to LaTeX."""
+        from texer.eval import _evaluate_impl, evaluate_value
+
+        content = _evaluate_impl(self.content, data, scope or {}, escape=False)
+
+        # Resolve bold/italic if they are Specs
+        bold = evaluate_value(self.bold, data, scope) if isinstance(self.bold, Spec) else self.bold
+        italic = evaluate_value(self.italic, data, scope) if isinstance(self.italic, Spec) else self.italic
+
+        if bold:
+            content = f"\\textbf{{{content}}}"
+        if italic:
+            content = f"\\textit{{{content}}}"
+
+        return content
+
+
+@dataclass
+class MultiColumn:
+    """A cell spanning multiple columns.
+
+    Examples:
+        MultiColumn(3, "c", "Header Title")
+    """
+
+    ncols: int
+    align: str
+    content: Any
+
+    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
+        """Render the multicolumn cell."""
+        from texer.eval import _evaluate_impl
+
+        content = _evaluate_impl(self.content, data, scope or {}, escape=False)
+        return f"\\multicolumn{{{self.ncols}}}{{{self.align}}}{{{content}}}"
+
+
+@dataclass
+class MultiRow:
+    """A cell spanning multiple rows.
+
+    Examples:
+        MultiRow(2, "Category")
+    """
+
+    nrows: int
+    content: Any
+    width: str = "*"
+
+    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
+        """Render the multirow cell."""
+        from texer.eval import _evaluate_impl
+
+        content = _evaluate_impl(self.content, data, scope or {}, escape=False)
+        return f"\\multirow{{{self.nrows}}}{{{self.width}}}{{{content}}}"
+
+
+@dataclass
+class Row:
+    """A table row containing cells.
+
+    Examples:
+        Row("Name", "Value", "Unit")
+        Row(Ref("name"), Ref("value"), Ref("unit"))
+        Row(Cell(Ref("x"), bold=True), Ref("y"))
+        Row("A", "B", "C", end=r"\\[4pt]")  # Extra vertical space
+        Row("A", "B", "C", end="")  # No line ending
+    """
+
+    cells: tuple[Any, ...] = field(default_factory=tuple)
+    end: str = field(default=r"\\")
+    _raw_options: str | None = None
+
+    def __init__(self, *cells: Any, end: str = r"\\", _raw_options: str | None = None):
+        object.__setattr__(self, "cells", cells)
+        object.__setattr__(self, "end", end)
+        object.__setattr__(self, "_raw_options", _raw_options)
+
+    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
+        """Render the row to LaTeX."""
+        from texer.eval import _evaluate_impl
+
+        rendered_cells = []
+        for cell in self.cells:
+            if isinstance(cell, (Cell, MultiColumn, MultiRow)):
+                rendered_cells.append(cell.render(data, scope))
+            else:
+                rendered_cells.append(_evaluate_impl(cell, data, scope or {}, escape=False))
+
+        row_content = " & ".join(rendered_cells)
+        if self.end:
+            return f"{row_content} {self.end}"
+        return row_content
+
+
+@dataclass
+class HLine:
+    """A horizontal line in a table."""
+
+    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
+        return "\\hline"
+
+
+@dataclass
+class CLine:
+    """A partial horizontal line (cline)."""
+
+    start: int
+    end: int
+
+    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
+        return f"\\cline{{{self.start}-{self.end}}}"
+
+
+@dataclass
+class Tabular:
+    """A LaTeX tabular environment.
+
+    Examples:
+        Tabular(
+            columns="lcc",
+            header=Row("Name", "Value 1", "Value 2"),
+            rows=Iter(Ref("data"), template=Row(Ref("name"), Ref("v1"), Ref("v2")))
+        )
+    """
+
+    columns: str
+    header: Row | list[Row] | None = None
+    rows: Any = None  # Iter, list of Rows, or single Row
+    toprule: bool = False
+    midrule: bool = False
+    bottomrule: bool = False
+    _raw_options: str | None = None
+
+    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
+        """Render the tabular environment."""
+        if scope is None:
+            scope = {}
+
+        lines = []
+
+        # Opening
+        lines.append(f"\\begin{{tabular}}{{{self.columns}}}")
+
+        # Top rule (booktabs)
+        if self.toprule:
+            lines.append("  \\toprule")
+
+        # Header
+        if self.header is not None:
+            if isinstance(self.header, list):
+                for h in self.header:
+                    lines.append(f"  {h.render(data, scope)}")
+            else:
+                lines.append(f"  {self.header.render(data, scope)}")
+
+            # Mid rule after header
+            if self.midrule or self.toprule:
+                lines.append("  \\midrule")
+
+        # Body rows
+        if self.rows is not None:
+            rendered_rows = self._render_rows(data, scope)
+            for row in rendered_rows:
+                lines.append(f"  {row}")
+
+        # Bottom rule
+        if self.bottomrule:
+            lines.append("  \\bottomrule")
+
+        # Closing
+        lines.append("\\end{tabular}")
+
+        return "\n".join(lines)
+
+    def _render_iter(self, iter_obj: Iter, data: Any, scope: dict[str, Any]) -> list[str]:
+        """Render an Iter object to a list of row strings."""
+        # Get the source items
+        if isinstance(iter_obj.source, str):
+            import glom  # type: ignore[import-untyped]
+            items = glom.glom(data, iter_obj.source)
+        else:
+            items = iter_obj.source.resolve(data, scope)
+
+        if iter_obj.template is not None:
+            # Render the template for each item
+            results = []
+            for item in items:
+                if isinstance(iter_obj.template, Row):
+                    results.append(iter_obj.template.render(item, scope))
+                elif hasattr(iter_obj.template, "render"):
+                    results.append(iter_obj.template.render(item, scope))
+                else:
+                    from texer.eval import _evaluate_impl
+                    results.append(_evaluate_impl(iter_obj.template, item, scope, escape=False))
+            return results
+        else:
+            # No template, just resolve
+            return [str(item) for item in items]
+
+    def _render_rows(self, data: Any, scope: dict[str, Any]) -> list[str]:
+        """Render the body rows."""
+        if isinstance(self.rows, Iter):
+            return self._render_iter(self.rows, data, scope)
+        elif isinstance(self.rows, list):
+            results = []
+            for row in self.rows:
+                if isinstance(row, Iter):
+                    results.extend(self._render_iter(row, data, scope))
+                else:
+                    results.append(row.render(data, scope))
+            return results
+        elif isinstance(self.rows, Row):
+            return [self.rows.render(data, scope)]
+        elif isinstance(self.rows, Spec):
+            resolved = self.rows.resolve(data, scope)
+            if isinstance(resolved, list):
+                return [str(r) for r in resolved]
+            return [str(resolved)]
+        return []
+
+
+@dataclass
+class Table:
+    """A LaTeX table environment (floating).
+
+    Examples:
+        Table(
+            Tabular(...),
+            caption="My Table",
+            label="tab:mytable",
+            position="htbp"
+        )
+    """
+
+    content: Tabular
+    caption: Any = None
+    label: str | None = None
+    position: str = "htbp"
+    centering: bool = True
+    _raw_options: str | None = None
+
+    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
+        """Render the table environment."""
+        if scope is None:
+            scope = {}
+
+        lines = []
+
+        # Opening
+        lines.append(f"\\begin{{table}}[{self.position}]")
+
+        if self.centering:
+            lines.append("  \\centering")
+
+        # Caption (before table for some styles)
+        if self.caption is not None:
+            from texer.eval import _evaluate_impl
+            caption_text = _evaluate_impl(self.caption, data, scope, escape=False)
+            lines.append(f"  \\caption{{{caption_text}}}")
+
+        # Label
+        if self.label is not None:
+            lines.append(f"  \\label{{{self.label}}}")
+
+        # Tabular content
+        tabular_lines = self.content.render(data, scope)
+        for line in tabular_lines.split("\n"):
+            lines.append(f"  {line}" if line else line)
+
+        # Closing
+        lines.append("\\end{table}")
+
+        return "\n".join(lines)
+
+
+# Convenience function for simple tables
+def simple_table(
+    headers: list[str],
+    rows: list[list[Any]],
+    caption: str | None = None,
+    label: str | None = None,
+) -> Table:
+    """Create a simple table from headers and row data.
+
+    Args:
+        headers: List of column headers.
+        rows: List of row data (each row is a list of values).
+        caption: Optional table caption.
+        label: Optional label for referencing.
+
+    Returns:
+        A Table object ready for rendering.
+    """
+    ncols = len(headers)
+    columns = "l" + "c" * (ncols - 1)  # First column left, rest centered
+
+    header_row = Row(*headers)
+    data_rows = [Row(*row) for row in rows]
+
+    tabular = Tabular(
+        columns=columns,
+        header=header_row,
+        rows=data_rows,
+        toprule=True,
+        midrule=True,
+        bottomrule=True,
+    )
+
+    return Table(tabular, caption=caption, label=label)

texer/utils.py

@@ -0,0 +1,311 @@
+"""Utility functions for LaTeX generation."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+# Regex pattern for hex color codes (with or without #)
+HEX_COLOR_PATTERN = re.compile(r"^#?([0-9A-Fa-f]{6})$")
+
+
+def hex_to_pgf_rgb(color: str) -> str:
+    """Convert a hex color code to PGF/TikZ RGB format.
+
+    Args:
+        color: A hex color code like "#5D8AA8" or "5D8AA8".
+
+    Returns:
+        The color in PGF format: "{rgb,255:red,93; green,138; blue,168}"
+
+    Raises:
+        ValueError: If the color is not a valid 6-character hex code.
+
+    Examples:
+        >>> hex_to_pgf_rgb("#5D8AA8")
+        '{rgb,255:red,93; green,138; blue,168}'
+        >>> hex_to_pgf_rgb("#FF0000")
+        '{rgb,255:red,255; green,0; blue,0}'
+        >>> hex_to_pgf_rgb("00FF00")
+        '{rgb,255:red,0; green,255; blue,0}'
+    """
+    match = HEX_COLOR_PATTERN.match(color)
+    if not match:
+        raise ValueError(
+            f"Invalid hex color code: {color!r}. "
+            "Expected format: '#RRGGBB' or 'RRGGBB'"
+        )
+
+    hex_str = match.group(1)
+    red = int(hex_str[0:2], 16)
+    green = int(hex_str[2:4], 16)
+    blue = int(hex_str[4:6], 16)
+
+    return f"{{rgb,255:red,{red}; green,{green}; blue,{blue}}}"
+
+
+def is_hex_color(color: str) -> bool:
+    """Check if a string is a valid hex color code.
+
+    Args:
+        color: A string to check.
+
+    Returns:
+        True if the string is a valid hex color code (with or without #).
+
+    Examples:
+        >>> is_hex_color("#5D8AA8")
+        True
+        >>> is_hex_color("FF0000")
+        True
+        >>> is_hex_color("blue")
+        False
+        >>> is_hex_color("#GGG")
+        False
+    """
+    return HEX_COLOR_PATTERN.match(color) is not None
+
+# Characters that need escaping in LaTeX
+LATEX_SPECIAL_CHARS = {
+    "&": r"\&",
+    "%": r"\%",
+    "$": r"\$",
+    "#": r"\#",
+    "_": r"\_",
+    "{": r"\{",
+    "}": r"\}",
+    "~": r"\textasciitilde{}",
+    "^": r"\textasciicircum{}",
+    "\\": r"\textbackslash{}",
+}
+
+# Regex pattern for special characters
+LATEX_ESCAPE_PATTERN = re.compile(
+    "|".join(re.escape(char) for char in LATEX_SPECIAL_CHARS.keys())
+)
+
+
+def escape_latex(text: str) -> str:
+    """Escape special LaTeX characters in text.
+
+    Args:
+        text: The text to escape.
+
+    Returns:
+        The escaped text safe for LaTeX.
+
+    Examples:
+        >>> escape_latex("10% off")
+        '10\\% off'
+        >>> escape_latex("$100")
+        '\\$100'
+    """
+    return LATEX_ESCAPE_PATTERN.sub(
+        lambda m: LATEX_SPECIAL_CHARS[m.group()], text
+    )
+
+
+def format_option_value(value: Any) -> str:
+    """Format a Python value for use in LaTeX options.
+
+    Args:
+        value: The value to format.
+
+    Returns:
+        LaTeX-formatted string.
+
+    Examples:
+        >>> format_option_value("north west")
+        '{north west}'
+        >>> format_option_value(True)
+        'true'
+        >>> format_option_value(3.14)
+        '3.14'
+    """
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if value is None:
+        return ""
+    if isinstance(value, (int, float)):
+        return str(value)
+    # Strings get wrapped in braces if they contain spaces or special chars
+    s = str(value)
+    # Don't double-wrap if already wrapped in braces
+    if s.startswith("{") and s.endswith("}"):
+        return s
+    if " " in s or any(c in s for c in ",=[]"):
+        return f"{{{s}}}"
+    return s
+
+
+def format_options(options: dict[str, Any], raw_options: str | None = None) -> str:
+    """Format a dictionary of options for LaTeX.
+
+    Args:
+        options: Dictionary of option key-value pairs.
+        raw_options: Raw LaTeX options string to append.
+
+    Returns:
+        Formatted options string (without surrounding brackets).
+
+    Examples:
+        >>> format_options({"xlabel": "Time", "ylabel": "Value"})
+        'xlabel={Time}, ylabel={Value}'
+    """
+    parts = []
+    for key, value in options.items():
+        if value is None:
+            continue
+        if value is True:
+            # Boolean true options are just the key
+            parts.append(key)
+        elif value is False:
+            continue  # Skip false options
+        else:
+            formatted = format_option_value(value)
+            # Convert Python-style names to LaTeX style (legend_pos -> legend pos)
+            latex_key = key.replace("_", " ")
+            parts.append(f"{latex_key}={formatted}")
+
+    if raw_options:
+        parts.append(raw_options)
+
+    return ", ".join(parts)
+
+
+def indent(text: str, spaces: int = 2) -> str:
+    """Indent each line of text.
+
+    Args:
+        text: The text to indent.
+        spaces: Number of spaces to indent.
+
+    Returns:
+        Indented text.
+    """
+    prefix = " " * spaces
+    return "\n".join(prefix + line if line else line for line in text.split("\n"))
+
+
+def wrap_environment(name: str, content: str, options: str = "") -> str:
+    """Wrap content in a LaTeX environment.
+
+    Args:
+        name: Environment name.
+        content: Content to wrap.
+        options: Optional options string.
+
+    Returns:
+        Complete environment string.
+    """
+    if options:
+        begin = f"\\begin{{{name}}}[{options}]"
+    else:
+        begin = f"\\begin{{{name}}}"
+    end = f"\\end{{{name}}}"
+    return f"{begin}\n{indent(content)}\n{end}"
+
+
+def _single_cmidrule(
+    start: int,
+    end: int,
+    trim_left: str | bool = False,
+    trim_right: str | bool = False,
+) -> str:
+    """Generate a single \\cmidrule command."""
+    trim = ""
+    if trim_left or trim_right:
+        left_part = ""
+        right_part = ""
+        if trim_left is True:
+            left_part = "l"
+        elif trim_left:
+            left_part = f"l{{{trim_left}}}"
+        if trim_right is True:
+            right_part = "r"
+        elif trim_right:
+            right_part = f"r{{{trim_right}}}"
+        trim = f"({left_part}{right_part})"
+
+    return f"\\cmidrule{trim}{{{start}-{end}}}"
+
+
+def cmidrule(
+    start: int | list[tuple[int, int]],
+    end: int | None = None,
+    trim_left: str | bool = False,
+    trim_right: str | bool = False,
+    trim_between: bool = False,
+) -> str:
+    """Generate \\cmidrule command(s) from the booktabs package.
+
+    Can generate a single cmidrule or multiple cmidrules from a list of ranges.
+
+    Args:
+        start: Either:
+            - Starting column number (1-indexed) for a single rule, OR
+            - List of (start, end) tuples for multiple rules
+        end: Ending column number (1-indexed). Required if start is an int.
+        trim_left: Left trim specification. Can be:
+            - False: no left trim
+            - True: default left trim ("l")
+            - str: custom trim width (e.g., "0.5em")
+        trim_right: Right trim specification. Can be:
+            - False: no right trim
+            - True: default right trim ("r")
+            - str: custom trim width (e.g., "0.5em")
+        trim_between: If True and multiple ranges given, automatically add
+            trim_right to all but the last rule and trim_left to all but
+            the first rule, creating gaps between adjacent rules.
+
+    Returns:
+        The \\cmidrule command string(s), space-separated if multiple.
+
+    Examples:
+        >>> cmidrule(1, 3)
+        '\\\\cmidrule{1-3}'
+        >>> cmidrule(2, 4, trim_left=True, trim_right=True)
+        '\\\\cmidrule(lr){2-4}'
+        >>> cmidrule([(2, 4), (5, 7)])
+        '\\\\cmidrule{2-4} \\\\cmidrule{5-7}'
+        >>> cmidrule([(2, 4), (5, 7)], trim_between=True)
+        '\\\\cmidrule(r){2-4} \\\\cmidrule(l){5-7}'
+        >>> cmidrule([(1, 2), (3, 4), (5, 6)], trim_between=True)
+        '\\\\cmidrule(r){1-2} \\\\cmidrule(lr){3-4} \\\\cmidrule(l){5-6}'
+    """
+    # Handle list of ranges
+    if isinstance(start, list):
+        ranges = start
+        if not ranges:
+            return ""
+
+        results = []
+        for i, (s, e) in enumerate(ranges):
+            # Determine trim for this rule
+            left = trim_left
+            right = trim_right
+
+            if trim_between and len(ranges) > 1:
+                # First rule: no left trim (unless specified), add right trim
+                # Middle rules: add both trims
+                # Last rule: add left trim, no right trim (unless specified)
+                if i == 0:
+                    right = right or True
+                elif i == len(ranges) - 1:
+                    left = left or True
+                else:
+                    left = left or True
+                    right = right or True
+
+            results.append(_single_cmidrule(s, e, left, right))
+
+        return " ".join(results)
+
+    # Single range (original API)
+    if end is None:
+        raise ValueError("end is required when start is an integer")
+
+    return _single_cmidrule(start, end, trim_left, trim_right)