a_maze_ing.py

"""A-Maze-ing CLI: parse a config file, generate the maze, write the
output file, then launch the MLX visualizer.

Usage::

    python3 a_maze_ing.py config.txt

The config file is a plain ``KEY=VALUE`` document; ``#``-prefixed lines and
blank lines are ignored. Required keys are ``WIDTH``, ``HEIGHT``,
``ENTRY``, ``EXIT``, ``OUTPUT_FILE``, ``PERFECT``. Optional keys are
``SEED`` (RNG reproducibility) and ``IMPRATE`` (0-100, imperfection rate).
"""

from __future__ import annotations

import os
import sys
import time
from enum import IntEnum
from typing import Any, Optional, Tuple

from cffi import FFI


SCRIPT_DIR: str = os.path.dirname(os.path.abspath(__file__))
DEFAULT_LIB: str = os.path.join(SCRIPT_DIR, "libamazing.so")
DEFAULT_CONFIG: str = os.path.join(SCRIPT_DIR, "config.txt")


class Direction(IntEnum):
    """Maze wall direction; matches ``e_direction`` in ``mazegen.h``."""

    NORTH = 0
    EAST = 1
    SOUTH = 2
    WEST = 3


class KeyCodes(IntEnum):
    """X11 keysyms for the on-screen panel buttons (digits 1-4)."""

    REGEN = 49
    SOLVE = 50
    RECOLOR = 51
    QUIT = 52


_REQUIRED_KEYS: Tuple[str, ...] = (
    "WIDTH", "HEIGHT", "ENTRY", "EXIT", "OUTPUT_FILE", "PERFECT",
)
_OPTIONAL_KEYS: Tuple[str, ...] = ("SEED", "IMPRATE")
_ALLOWED_KEYS: set[str] = set(_REQUIRED_KEYS) | set(_OPTIONAL_KEYS)


def _coerce(key: str, value: str, lineno: int, path: str) -> Any:
    """Convert a raw config value to its typed Python representation.

    :raises ValueError: with file:line context if the value is malformed.
    """
    try:
        if key in ("WIDTH", "HEIGHT", "SEED", "IMPRATE"):
            return int(value)
        if key in ("ENTRY", "EXIT"):
            parts: list[str] = value.split(",")
            if len(parts) != 2:
                raise ValueError("expected 'x,y'")
            return (int(parts[0].strip()), int(parts[1].strip()))
        if key == "PERFECT":
            v: str = value.strip().lower()
            if v in ("true", "1", "yes"):
                return True
            if v in ("false", "0", "no"):
                return False
            raise ValueError("expected true/false")
        return value
    except ValueError as e:
        raise ValueError(
            f"{path}:{lineno}: invalid value for {key}: {e}"
        ) from None


def _parse_config(path: str) -> dict[str, Any]:
    """Parse a ``KEY=VALUE`` config file into a typed dict.

    Lines starting with ``#`` and blank lines are skipped. Inline trailing
    ``# comments`` are also stripped.

    :param path: filesystem path to the config file.
    :raises FileNotFoundError: if ``path`` does not exist.
    :raises ValueError: on missing/extra keys, malformed lines, or
        type-coercion failures.
    """
    cfg: dict[str, Any] = {}
    with open(path, "r", encoding="utf-8") as fp:
        for lineno, raw in enumerate(fp, 1):
            line: str = raw.split("#", 1)[0].strip()
            if not line:
                continue
            if "=" not in line:
                raise ValueError(
                    f"{path}:{lineno}: expected KEY=VALUE, got {raw!r}"
                )
            key_raw, value_raw = line.split("=", 1)
            key: str = key_raw.strip().upper()
            value: str = value_raw.strip()
            if key not in _ALLOWED_KEYS:
                raise ValueError(
                    f"{path}:{lineno}: unknown config key {key!r}"
                )
            cfg[key] = _coerce(key, value, lineno, path)
    missing: list[str] = [k for k in _REQUIRED_KEYS if k not in cfg]
    if missing:
        raise ValueError(
            f"{path}: missing required keys: {', '.join(missing)}"
        )
    w: int = int(cfg["WIDTH"])
    h: int = int(cfg["HEIGHT"])
    if w < 1 or h < 1:
        raise ValueError(
            f"WIDTH and HEIGHT must be >= 1; got {w}x{h}"
        )
    for label in ("ENTRY", "EXIT"):
        x, y = cfg[label]
        if not (0 <= x < w and 0 <= y < h):
            raise ValueError(
                f"{label}={x},{y} out of bounds for {w}x{h}"
            )
    if cfg["ENTRY"] == cfg["EXIT"]:
        raise ValueError("ENTRY and EXIT must differ")
    if cfg.get("IMPRATE") is not None:
        r: int = int(cfg["IMPRATE"])
        if r < 0 or r > 100:
            raise ValueError(f"IMPRATE must be in [0, 100]; got {r}")
    return cfg


class MazeGenerator:
    """Application orchestrator: load libamazing, drive maze + MLX loop."""

    _CDEF: str = """
        typedef struct s_img {
            char          *purpose;
            void          *img;
            unsigned char *addr;
            unsigned int   bits_per_pixel;
            unsigned int   line_length;
            unsigned int   endian;
            unsigned int   width;
            unsigned int   height;
        } t_img;

        typedef struct s_cell {
            struct s_cell *parent;
            int           *options;
            int            visited;
            int            wall;
            int            patterned;
            int            x;
            int            y;
        } t_cell;

        typedef struct s_maze {
            int     width;
            int     height;
            int     entry_x;
            int     entry_y;
            int     exit_x;
            int     exit_y;
            char   *output_filename;
            bool    is_solved;
            bool    is_perfect;
            t_cell **grid;
            int     imprate;
        } t_maze;

        typedef struct s_mlx {
            void         *ptr;
            void         *win;
            unsigned int  mlx_width;
            unsigned int  mlx_height;
            t_img       **images;
            t_maze       *maze;
        } t_mlx;

        typedef struct s_colorpair {
            struct s_colorpair *next;
            unsigned int        color1;
            unsigned int        color2;
        } t_colorpair;

        typedef struct s_func_data {
            t_mlx       *mlx;
            t_colorpair *bundle;
            t_colorpair *pair;
        } t_func_data;

        t_maze *init_grid(t_maze *maze);
        void    free_maze(t_maze *maze);
        void    generate_maze(t_maze *maze);
        void    pattern_42(t_maze *maze);
        void    set_seed(unsigned int s);
        void    solve(t_maze *maze);
        int     write_output(t_maze *maze);

        int     mlx_ready(t_mlx *mlx);
        int     mlx_render_grid(t_mlx *mlx,
                                unsigned int color1,
                                unsigned int color2);
        int     mlx_destroy(t_mlx *mlx);
        int     mlx_handle(int key, t_func_data *data);
        int     mlx_key_hook(void *win_ptr,
                             int (*funct_ptr)(int, t_func_data *),
                             void *param);

        t_colorpair *init_bundle(void);
        t_colorpair *random_pair(t_colorpair *bundle);
        void         free_bundle(t_colorpair *bundle);

        void   *mlx_init(void);
        int     mlx_loop(void *mlx_ptr);
    """

    def __init__(self, lib_path: str = DEFAULT_LIB) -> None:
        """Load ``libamazing.so`` and prepare CFFI bindings.

        :raises SystemExit: if the library cannot be loaded.
        """
        self.ffi: FFI = FFI()
        self.ffi.cdef(self._CDEF)
        try:
            self.lib: Any = self.ffi.dlopen(lib_path)
        except OSError as exc:
            print(
                f"ERROR: cannot load {lib_path}: {exc}",
                file=sys.stderr,
            )
            sys.exit(1)
        self._anchor: dict[str, Any] = {}

    def run(self, config_file: Optional[str] = None) -> None:
        """Parse config, generate, write output, then launch MLX.

        Always cleans up the C maze and color bundle on exit.

        :raises SystemExit: on user errors (missing config, malformed
            values, allocation failures).
        """
        cfg_path: str = config_file or DEFAULT_CONFIG
        if not os.path.exists(cfg_path):
            print(
                f"ERROR: config file '{cfg_path}' not found.",
                file=sys.stderr,
            )
            sys.exit(1)

        try:
            cfg: dict[str, Any] = _parse_config(cfg_path)
        except (OSError, ValueError) as exc:
            print(f"ERROR: {exc}", file=sys.stderr)
            sys.exit(1)

        maze_ptr: Any = self.ffi.new("t_maze *")
        bundle: Any = self.ffi.NULL
        try:
            self._fill_maze(maze_ptr, cfg)
            self._anchor["output"] = self.ffi.new(
                "char[]", cfg["OUTPUT_FILE"].encode("utf-8")
            )
            maze_ptr.output_filename = self._anchor["output"]
            self._seed_rng(cfg)

            if not self.lib.init_grid(maze_ptr):
                print(
                    "ERROR: failed to allocate maze grid",
                    file=sys.stderr,
                )
                sys.exit(1)

            print(
                f"Generating {int(maze_ptr.width)}x"
                f"{int(maze_ptr.height)} maze..."
            )
            self.lib.pattern_42(maze_ptr)
            self.lib.generate_maze(maze_ptr)

            if not self.lib.write_output(maze_ptr):
                print(
                    "ERROR: failed to write output file",
                    file=sys.stderr,
                )
                sys.exit(1)
            print(f"Output written to {cfg['OUTPUT_FILE']}.")

            bundle = self._launch_mlx(maze_ptr)
        finally:
            if bundle and bundle != self.ffi.NULL:
                self.lib.free_bundle(bundle)
            self.lib.free_maze(maze_ptr)
            self._anchor.clear()

    def _fill_maze(
        self, maze_ptr: Any, cfg: dict[str, Any]
    ) -> None:
        """Copy parsed config fields onto the maze struct."""
        maze_ptr.width = cfg["WIDTH"]
        maze_ptr.height = cfg["HEIGHT"]
        ex, ey = cfg["ENTRY"]
        ox, oy = cfg["EXIT"]
        maze_ptr.entry_x = ex
        maze_ptr.entry_y = ey
        maze_ptr.exit_x = ox
        maze_ptr.exit_y = oy
        maze_ptr.is_perfect = cfg["PERFECT"]
        maze_ptr.is_solved = False
        maze_ptr.imprate = int(cfg.get("IMPRATE", 50))

    def _seed_rng(self, cfg: dict[str, Any]) -> None:
        """Seed the C RNG; default to a 32-bit time-derived value."""
        seed: int = int(
            cfg.get("SEED", time.time_ns() & 0xFFFFFFFF)
        )
        self.lib.set_seed(seed & 0xFFFFFFFF)

    def _launch_mlx(self, maze_ptr: Any) -> Any:
        """Set up MLX, render, run the event loop. Returns the bundle.

        Returns ``ffi.NULL`` if MLX initialization fails (so the caller
        can still write the output file in headless contexts).
        """
        mlx_ptr: Any = self.ffi.new("t_mlx *")
        mlx_ptr.maze = maze_ptr
        self._anchor["images"] = self.ffi.new("t_img *[64]")
        mlx_ptr.images = self._anchor["images"]
        self._anchor["mlx"] = mlx_ptr

        if not self.lib.mlx_ready(mlx_ptr):
            print(
                "WARN: MLX init failed; output file already written.",
                file=sys.stderr,
            )
            return self.ffi.NULL

        bundle: Any = self.lib.init_bundle()
        if bundle == self.ffi.NULL:
            print(
                "WARN: color bundle init failed; skipping render.",
                file=sys.stderr,
            )
            return self.ffi.NULL

        pair: Any = self.lib.random_pair(bundle)
        if pair == self.ffi.NULL:
            print(
                "WARN: color pair selection failed; skipping render.",
                file=sys.stderr,
            )
            return bundle

        func_data: Any = self.ffi.new("t_func_data *")
        func_data.mlx = mlx_ptr
        func_data.bundle = bundle
        func_data.pair = pair
        self._anchor["func_data"] = func_data

        print("Rendering maze...")
        self.lib.mlx_render_grid(mlx_ptr, pair.color1, pair.color2)
        self.lib.mlx_key_hook(
            mlx_ptr.win, self.lib.mlx_handle, func_data
        )
        print(
            "MLX loop: 1 (Regen), 2 (Solve), 3 (Color), 4 (Quit)."
        )
        self.lib.mlx_loop(mlx_ptr.ptr)
        return bundle


def main() -> None:
    """CLI entry point. Parses ``sys.argv[1]`` as the config path."""
    config_file: str = (
        sys.argv[1] if len(sys.argv) > 1 else DEFAULT_CONFIG
    )
    MazeGenerator().run(config_file)


if __name__ == "__main__":
    main()