byteforge-figlet 2.0.4__py3-none-any.whl

byteforge_figlet/__init__.py

@@ -0,0 +1,21 @@
+"""ByteForge FIGLet — Python FIGLet rendering library.
+
+Quickstart::
+
+    from byteforge_figlet import FIGFont, FIGLetRenderer, LayoutMode
+
+    print(FIGLetRenderer.render("Hello!"))
+
+Or use the bundled CLI::
+
+    python -m byteforge_figlet "Hello World"
+    figprint "Hello World" --font small
+"""
+
+from .fig_font import FIGFont
+from .fig_let_renderer import FIGLetRenderer
+from .layout_mode import LayoutMode
+from .smushing_rules import SmushingRules
+
+__version__ = "2.0.4"
+__all__ = ["FIGFont", "FIGLetRenderer", "LayoutMode", "SmushingRules"]

byteforge_figlet/__main__.py

@@ -0,0 +1,61 @@
+"""CLI entry point — ``python -m byteforge_figlet``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .fig_font import FIGFont
+from .fig_let_renderer import FIGLetRenderer
+from .layout_mode import LayoutMode
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="figprint",
+        description="Render text as ASCII art using FIGLet fonts.",
+    )
+    parser.add_argument("text", nargs="?", help="Text to render (reads stdin if omitted)")
+    parser.add_argument(
+        "-f", "--font",
+        metavar="PATH",
+        default=None,
+        help="Path to a .flf font file (default: built-in 'small')",
+    )
+    parser.add_argument(
+        "-m", "--mode",
+        choices=["full", "kerning", "smush"],
+        default="smush",
+        help="Layout mode (default: smush)",
+    )
+    parser.add_argument(
+        "--width",
+        type=int,
+        default=0,
+        help="Target output width in characters (0 = unlimited)",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv)
+
+    text = args.text
+    if not text:
+        if sys.stdin.isatty():
+            print("Usage: figprint <text> [--font PATH] [--mode full|kerning|smush]", file=sys.stderr)
+            return 1
+        text = sys.stdin.read().rstrip("\n")
+
+    font = FIGFont.from_file(args.font) if args.font else None
+
+    mode_map = {"full": LayoutMode.FullSize, "kerning": LayoutMode.Kerning, "smush": LayoutMode.Smushing}
+    mode = mode_map[args.mode]
+
+    result = FIGLetRenderer.render(text, font=font, mode=mode, line_separator="\n")
+    print(result, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

byteforge_figlet/fig_font.py

@@ -0,0 +1,255 @@
+"""FIGFont parser — loads and exposes .flf font files."""
+
+from __future__ import annotations
+
+import importlib.resources
+import io
+import zipfile
+from typing import Dict, List, Optional
+
+from .smushing_rules import SmushingRules
+
+
+class _ClassProperty:
+    """Descriptor for a lazily-evaluated class-level property.
+
+    ``@classmethod @property`` was deprecated in Python 3.11 and removed in
+    3.13.  This descriptor replicates that behaviour across all supported
+    Python versions.
+    """
+    __slots__ = ("_func",)
+
+    def __init__(self, func):
+        self._func = func
+
+    def __get__(self, obj, objtype=None):
+        return self._func(objtype if objtype is not None else type(obj))
+
+
+class FIGFont:
+    """Represents a FIGfont loaded from a .flf file."""
+
+    # ------------------------------------------------------------------ #
+    # Class-level default font cache
+    # ------------------------------------------------------------------ #
+    _default: Optional["FIGFont"] = None
+
+    @_ClassProperty
+    def default(cls) -> "FIGFont":
+        """Return the built-in 'small' FIGfont (loaded once and cached)."""
+        if cls._default is None:
+            cls._default = cls._load_default_font()
+        if cls._default is None:
+            raise RuntimeError("Default FIGfont could not be loaded")
+        return cls._default
+
+    # ------------------------------------------------------------------ #
+    # Instance attributes
+    # ------------------------------------------------------------------ #
+    def __init__(self) -> None:
+        self.signature: str = "flf2a"
+        self.hard_blank: str = "#"
+        self.height: int = 0
+        self.baseline: int = 0
+        self.max_length: int = 0
+        self.old_layout: int = 0
+        self.print_direction: int = 0
+        self.full_layout: int = 0
+        self.characters: Dict[int, List[str]] = {}
+        self.smushing_rules: SmushingRules = SmushingRules.NONE
+        self.comments: str = ""
+
+    # ------------------------------------------------------------------ #
+    # Factory methods
+    # ------------------------------------------------------------------ #
+    @classmethod
+    def from_file(cls, path: Optional[str]) -> Optional["FIGFont"]:
+        """Load a FIGFont from a file path (supports .flf and .zip)."""
+        if not path:
+            return None
+        with open(path, "rb") as fh:
+            return cls.from_stream(fh)
+
+    @classmethod
+    def from_stream(cls, stream: Optional[io.RawIOBase]) -> Optional["FIGFont"]:
+        """Load a FIGFont from a binary stream (supports .flf inside .zip)."""
+        if stream is None:
+            return None
+        data = stream.read()
+        # Detect ZIP archive
+        if data[:2] == b"PK":
+            try:
+                zf_obj = zipfile.ZipFile(io.BytesIO(data))
+            except zipfile.BadZipFile:
+                return None
+            with zf_obj as zf:
+                flf_names = [n for n in zf.namelist() if n.lower().endswith(".flf")]
+                if not flf_names:
+                    return None
+                with zf.open(flf_names[0]) as entry:
+                    data = entry.read()
+        # Decode using latin-1 (FIGlet standard)
+        try:
+            text = data.decode("latin-1")
+        except UnicodeDecodeError:
+            text = data.decode("utf-8", errors="replace")
+        return cls.from_lines(text.splitlines())
+
+    @classmethod
+    def from_text(cls, text: Optional[str]) -> Optional["FIGFont"]:
+        """Load a FIGFont from a string containing the full .flf content."""
+        if not text:
+            return None
+        return cls.from_lines(text.splitlines())
+
+    @classmethod
+    def from_lines(cls, lines: Optional[List[str]]) -> Optional["FIGFont"]:
+        """Load a FIGFont from a list of lines."""
+        if not lines:
+            return None
+
+        font = cls()
+
+        # --- Parse header ---
+        header = lines[0].rstrip()
+        if not header.startswith("flf2a"):
+            raise ValueError("Invalid FIGfont format: header must start with 'flf2a'")
+
+        try:
+            parts = header.split()
+            font.signature = parts[0]
+            font.hard_blank = parts[0][5] if len(parts[0]) > 5 else "#"
+            font.height = int(parts[1])
+            font.baseline = int(parts[2])
+            font.max_length = int(parts[3])
+            font.old_layout = int(parts[4])
+            comment_lines = int(parts[5])
+            if len(parts) > 6:
+                try:
+                    font.print_direction = int(parts[6])
+                except ValueError:
+                    pass
+            if len(parts) > 7:
+                try:
+                    font.full_layout = int(parts[7])
+                except ValueError:
+                    pass
+        except (IndexError, ValueError) as exc:
+            raise ValueError(f"Error parsing FIGfont header: {exc}") from exc
+
+        # --- Collect comments ---
+        font.comments = "\n".join(lines[1 : 1 + comment_lines])
+
+        current_line = 1 + comment_lines
+
+        # --- Load required characters ASCII 32–126 ---
+        for code_point in range(32, 127):
+            char_lines = cls._read_char_lines(lines, font, current_line)
+            font.characters[code_point] = char_lines
+            current_line += font.height
+
+        # --- Load optional extra characters ---
+        while current_line < len(lines):
+            code_line = lines[current_line].strip()
+            if not code_line or not (code_line[0].isdigit() or code_line.startswith("-")):
+                break
+            # The code point is the first token; optional comment follows
+            token = code_line.split(None, 1)[0]
+            try:
+                code_point = cls._parse_int(token)
+            except ValueError:
+                break
+            current_line += 1
+            if current_line + font.height > len(lines):
+                break
+            char_lines = cls._read_char_lines(lines, font, current_line)
+            font.characters[code_point] = char_lines
+            current_line += font.height
+
+        # --- Derive smushing rules ---
+        cls._parse_layout_parameters(font)
+
+        return font
+
+    # ------------------------------------------------------------------ #
+    # Helpers
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _strip_endmark(raw: str, endmark: str) -> str:
+        """Strip the FIGlet end-of-line endmark character(s) from a raw line.
+
+        FIGlet fonts mark the end of each glyph row with one endmark character
+        (two on the final row).  We strip all trailing occurrences so that
+        glyphs whose visual shape happens to be the endmark character itself
+        (e.g. ``@`` in a font using ``@`` as its endmark) are rendered as empty
+        rather than as a stray endmark column.
+        """
+        stripped = raw.rstrip("\r\n")
+        if not endmark:
+            return stripped
+        return stripped.rstrip(endmark)
+
+    @staticmethod
+    def _read_char_lines(lines: List[str], font: "FIGFont", start: int) -> List[str]:
+        # Detect the endmark from the last character of the first raw line.
+        first_raw = lines[start].rstrip("\r\n") if start < len(lines) else ""
+        endmark = first_raw[-1] if first_raw else "@"
+        result: List[str] = []
+        for i in range(font.height):
+            raw = lines[start + i] if start + i < len(lines) else ""
+            stripped = FIGFont._strip_endmark(raw, endmark)
+            # Workaround: some fonts use '#' as a secondary endmark even when
+            # hard_blank != '#'.  Mirrors the same special case in the C# port.
+            if stripped.endswith("#") and font.hard_blank != "#":
+                stripped = stripped.rstrip("#")
+            result.append(stripped)
+        return result
+
+    @staticmethod
+    def _parse_int(text: str) -> int:
+        text = text.strip()
+        if not text:
+            return 0
+        if text.startswith("-"):
+            return -FIGFont._parse_int(text[1:])
+        if text.lower().startswith("0x"):
+            return int(text[2:], 16)
+        if text.lower().startswith("0b"):
+            return int(text[2:], 2)
+        if len(text) > 1 and text.startswith("0"):
+            return int(text, 8)
+        return int(text)
+
+    @staticmethod
+    def _parse_layout_parameters(font: "FIGFont") -> None:
+        if font.full_layout > 0:
+            layout_mask = font.full_layout
+            horizontal_smushing_enabled = (layout_mask & 1) == 1
+            if not horizontal_smushing_enabled:
+                font.smushing_rules = SmushingRules.NONE
+                return
+            layout_mask = (layout_mask >> 1) & 0x3F
+        else:
+            layout_mask = font.old_layout
+            if layout_mask <= 0:
+                font.smushing_rules = SmushingRules.NONE
+                return
+            layout_mask &= 0x3F
+
+        font.smushing_rules = SmushingRules(layout_mask)
+
+    @classmethod
+    def _load_default_font(cls) -> Optional["FIGFont"]:
+        try:
+            pkg = importlib.resources.files("byteforge_figlet") / "fonts" / "small.flf"
+            data = pkg.read_bytes()
+            return cls.from_stream(io.BytesIO(data))
+        except Exception:
+            return None
+
+    # ------------------------------------------------------------------ #
+    # Public helpers
+    # ------------------------------------------------------------------ #
+    def has_smushing_rule(self, rule: SmushingRules) -> bool:
+        """Return True if the font defines the given smushing rule."""
+        return self.smushing_rules.has_rule(rule)

byteforge_figlet/fig_let_renderer.py

@@ -0,0 +1,333 @@
+"""FIGLetRenderer — renders text using a FIGFont."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Dict, List, Optional
+
+from .fig_font import FIGFont
+from .layout_mode import LayoutMode
+from .smushing_rules import SmushingRules
+
+_HIERARCHY_CHARS = r"|/\[]{}()<>"
+_OPPOSITE_PAIRS: Dict[str, str] = {
+    "[": "]", "]": "[",
+    "{": "}", "}": "{",
+    "(": ")", ")": "(",
+    "<": ">", ">": "<",
+}
+_ANSI_COLOR_RESET = "\x1b[0m"
+
+_RE_LAST_NON_WS = re.compile(r"\S(?=\s*$)")
+_RE_FIRST_NON_WS = re.compile(r"\S")
+
+
+class FIGLetRenderer:
+    """Renders strings to multi-line ASCII art using a FIGFont."""
+
+    def __init__(
+        self,
+        font: Optional[FIGFont] = None,
+        mode: LayoutMode = LayoutMode.Smushing,
+        line_separator: Optional[str] = None,
+        use_ansi_colors: bool = False,
+        paragraph_mode: bool = True,
+    ) -> None:
+        self.font: FIGFont = font if font is not None else FIGFont.default
+        self.layout_mode: LayoutMode = mode
+        self.line_separator: str = line_separator if line_separator is not None else os.linesep
+        self.use_ansi_colors: bool = use_ansi_colors
+        self.paragraph_mode: bool = paragraph_mode
+
+    # ------------------------------------------------------------------ #
+    # Static convenience method
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def render(
+        text: str,
+        font: Optional[FIGFont] = None,
+        mode: LayoutMode = LayoutMode.Smushing,
+        line_separator: Optional[str] = None,
+        use_ansi_colors: bool = False,
+        paragraph_mode: bool = True,
+    ) -> str:
+        """Render *text* and return the ASCII-art string."""
+        if not text:
+            return ""
+        renderer = FIGLetRenderer(font, mode, line_separator, use_ansi_colors, paragraph_mode)
+        return renderer.render_text(text)
+
+    # ------------------------------------------------------------------ #
+    # Instance render
+    # ------------------------------------------------------------------ #
+    def render_text(self, text: str) -> str:
+        """Render *text* using the current font and settings."""
+        if not text:
+            return ""
+
+        sep = self.line_separator
+
+        if self.paragraph_mode:
+            empty_line = sep * self.font.height
+            paragraphs = text.replace("\r\n", "\n").split("\n")
+            parts: List[str] = []
+            for para in paragraphs:
+                if not para.strip():
+                    parts.append(empty_line)
+                else:
+                    parts.append(self._render_line(para))
+            return "".join(parts)
+
+        clean = text.replace("\r", "").replace("\n", " ")
+        return self._render_line(clean)
+
+    # ------------------------------------------------------------------ #
+    # Core line renderer
+    # ------------------------------------------------------------------ #
+    def _render_line(self, text: str) -> str:
+        font = self.font
+        mode = self.layout_mode
+        sep = self.line_separator
+        use_colors = self.use_ansi_colors
+
+        output_lines: List[List[str]] = [[] for _ in range(font.height)]
+
+        # First pass: strip ANSI, build plain text + color map
+        plain_chars: List[str] = []
+        color_dict: Dict[int, str] = {}
+        ansi = _ANSIProcessor(preserve_colors=use_colors)
+
+        for ch in text:
+            is_ansi = ansi.process_char(ch)
+            if is_ansi:
+                continue
+            if use_colors and ansi.current_color_sequence:
+                color_dict[len(plain_chars)] = ansi.current_color_sequence
+                ansi.reset_color_state()
+            if ord(ch) in font.characters:
+                plain_chars.append(ch)
+
+        plain_text = "".join(plain_chars)
+
+        # RTL: reverse text and color map
+        if font.print_direction == 1:
+            plain_text = plain_text[::-1]
+            reversed_colors: Dict[int, str] = {}
+            for pos, seq in color_dict.items():
+                reversed_colors[len(plain_text) - pos - 1] = seq
+            color_dict = reversed_colors
+
+        # Second pass: composite characters
+        char_index = 0
+        i = 0
+        while i < len(plain_text):
+            cp = ord(plain_text[i])
+            i += 1
+
+            char_lines = font.characters[cp]
+            color_code = color_dict.get(char_index, "")
+            char_index += 1
+
+            if not output_lines[0]:
+                # First character
+                for li in range(font.height):
+                    row: List[str] = []
+                    if use_colors:
+                        row.append(color_code)
+                    row.append(char_lines[li])
+                    output_lines[li] = row
+            else:
+                # Calculate minimum overlap across all rows
+                overlap = None
+                for li in range(font.height):
+                    existing = "".join(output_lines[li])
+                    ov = self._calculate_overlap(existing, char_lines[li], mode)
+                    overlap = ov if overlap is None else min(overlap, ov)
+
+                assert overlap is not None
+
+                # Apply smushing
+                for li in range(font.height):
+                    existing = "".join(output_lines[li])
+                    self._smush(output_lines[li], existing, char_lines[li], overlap, mode, color_code)
+
+        # Build final string
+        rows: List[str] = []
+        for li in range(font.height):
+            row = "".join(output_lines[li]).replace(font.hard_blank, " ")
+            if use_colors:
+                row += _ANSI_COLOR_RESET
+            rows.append(row)
+
+        return sep.join(rows) + sep
+
+    # ------------------------------------------------------------------ #
+    # Smushing helpers
+    # ------------------------------------------------------------------ #
+    def _smush(
+        self,
+        line_parts: List[str],
+        existing: str,
+        character: str,
+        overlap: int,
+        mode: LayoutMode,
+        color_code: str,
+    ) -> None:
+        """Mutate *line_parts* in-place to smush *character* into the existing line."""
+        # Rebuild without trailing overlap
+        trimmed = existing[: len(existing) - overlap]
+        line_end = existing[len(existing) - overlap :]
+
+        line_parts.clear()
+
+        if mode == LayoutMode.Kerning:
+            line_parts.append(trimmed)
+            if self.use_ansi_colors:
+                line_parts.append(color_code)
+            line_parts.append(character)
+            return
+
+        line_parts.append(trimmed)
+        for idx in range(overlap):
+            c1 = line_end[idx] if idx < len(line_end) else " "
+            c2 = character[idx] if idx < len(character) else " "
+            line_parts.append(
+                self._smush_characters(c1, c2, self.font.hard_blank, mode, self.font.smushing_rules)
+            )
+        if self.use_ansi_colors:
+            line_parts.append(color_code)
+        line_parts.append(character[overlap:])
+
+    def _calculate_overlap(self, line: str, character: str, mode: LayoutMode) -> int:
+        if mode == LayoutMode.FullSize:
+            return 0
+
+        eol = line if len(line) <= len(character) else line[len(line) - len(character):]
+        m1 = _RE_LAST_NON_WS.search(eol)
+        m2 = _RE_FIRST_NON_WS.search(character)
+
+        if not m1 or not m2:
+            return len(character)
+
+        can = self._can_smush(m1.group()[0], m2.group()[0], self.font.hard_blank, mode, self.font.smushing_rules)
+        overlap = max(len(eol) - m1.start(), m2.start()) + 1 if can else 0
+        overlap = min(overlap, len(character))
+
+        # Special case: opposing slashes reduce overlap by 1
+        if can and (
+            (m1.group()[0] == "/" and m2.group()[0] == "\\")
+            or (m1.group()[0] == "\\" and m2.group()[0] == "/")
+        ):
+            overlap = max(overlap - 1, 0)
+
+        return overlap
+
+    @staticmethod
+    def _can_smush(
+        c1: str, c2: str, hard_blank: str, mode: LayoutMode, rules: SmushingRules
+    ) -> bool:
+        if mode == LayoutMode.Kerning:
+            return c1 == c2 == " "
+        if mode == LayoutMode.FullSize:
+            return False
+        if c1 == hard_blank or c2 == hard_blank:
+            return rules.has_rule(SmushingRules.HardBlank)
+        if c1 == " " and c2 == " ":
+            return True
+        if c1 == " " or c2 == " ":
+            return True
+        if rules.has_rule(SmushingRules.EqualCharacter) and c1 == c2:
+            return True
+        if rules.has_rule(SmushingRules.Underscore):
+            if (c1 == "_" and c2 in _HIERARCHY_CHARS) or (c2 == "_" and c1 in _HIERARCHY_CHARS):
+                return True
+        if rules.has_rule(SmushingRules.Hierarchy):
+            if c1 in _HIERARCHY_CHARS and c2 in _HIERARCHY_CHARS:
+                return True
+        if rules.has_rule(SmushingRules.OppositePair):
+            if _OPPOSITE_PAIRS.get(c1) == c2:
+                return True
+        if rules.has_rule(SmushingRules.BigX):
+            if (c1 == ">" and c2 == "<") or (c1 == "/" and c2 == "\\") or (c1 == "\\" and c2 == "/"):
+                return True
+        return False
+
+    @staticmethod
+    def _smush_characters(
+        c1: str, c2: str, hard_blank: str, mode: LayoutMode, rules: SmushingRules
+    ) -> str:
+        if mode == LayoutMode.Kerning:
+            return c1
+        if c1 == " " and c2 == " ":
+            return " "
+        if c1 == " ":
+            return c2
+        if c2 == " ":
+            return c1
+        if c1 == hard_blank or c2 == hard_blank:
+            if rules.has_rule(SmushingRules.HardBlank):
+                return hard_blank
+            return c1
+        if rules.has_rule(SmushingRules.EqualCharacter) and c1 == c2:
+            return c1
+        if rules.has_rule(SmushingRules.Underscore):
+            if c1 == "_" and c2 in _HIERARCHY_CHARS:
+                return c2
+            if c2 == "_" and c1 in _HIERARCHY_CHARS:
+                return c1
+        if rules.has_rule(SmushingRules.Hierarchy):
+            rank1 = _HIERARCHY_CHARS.index(c1) if c1 in _HIERARCHY_CHARS else -1
+            rank2 = _HIERARCHY_CHARS.index(c2) if c2 in _HIERARCHY_CHARS else -1
+            if rank1 >= 0 and rank2 >= 0:
+                return _HIERARCHY_CHARS[max(rank1, rank2)]
+        if rules.has_rule(SmushingRules.OppositePair):
+            if _OPPOSITE_PAIRS.get(c1) == c2:
+                return "|"
+        if rules.has_rule(SmushingRules.BigX):
+            if c1 == "/" and c2 == "\\":
+                return "|"
+            if c1 == "\\" and c2 == "/":
+                return "Y"
+            if c1 == ">" and c2 == "<":
+                return "X"
+        if rules.has_rule(SmushingRules.HardBlank):
+            if c1 == hard_blank and c2 == hard_blank:
+                return hard_blank
+        return c1
+
+
+# --------------------------------------------------------------------------- #
+# Internal ANSI escape sequence processor
+# --------------------------------------------------------------------------- #
+class _ANSIProcessor:
+    _NON_COLOR_TERMINATORS = set("ABCDEFGHfJKSTsunhlitrP@XLM")
+
+    def __init__(self, preserve_colors: bool = False) -> None:
+        self._preserve = preserve_colors
+        self._in_esc = False
+        self._buf: List[str] = []
+        self.current_color_sequence: str = ""
+
+    def process_char(self, ch: str) -> bool:
+        if ch == "\x1b":
+            self._in_esc = True
+            self._buf = [ch]
+            return True
+        if self._in_esc:
+            self._buf.append(ch)
+            if len(self._buf) == 2 and ch != "[":
+                self._in_esc = False
+                return True
+            if len(self._buf) >= 3 and (("\x40" <= ch <= "\x7e") or ch == "m"):
+                self._in_esc = False
+                seq = "".join(self._buf)
+                self._buf = []
+                if ch == "m" and self._preserve:
+                    self.current_color_sequence += seq
+                return True
+            return True
+        return False
+
+    def reset_color_state(self) -> None:
+        self.current_color_sequence = ""