vim2bat 0.1.0__py3-none-any.whl

vim2bat/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from vim2bat.cli import main
+
+sys.exit(main())

vim2bat/cli.py

@@ -0,0 +1,761 @@
+"""Builds bat themes from Vim colorschemes.
+
+vim2bat runs Vim with your vimrc, records the colors and attributes a
+colorscheme gives each highlight group (Table 1), and writes bat themes that
+map TextMate scopes to them: share/strict.tsv (Table 2) for Vim's standard
+groups, and share/loose.tsv (Table 3) for language-specific groups. vim2bat
+compare measures a theme against Vim with share/vim-slots.vim.
+"""
+
+import argparse
+import fcntl
+import os
+import plistlib
+import re
+import select
+import shlex
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+import threading
+from collections import Counter
+from collections.abc import Iterator, Sequence
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from contextlib import contextmanager, suppress
+from importlib.metadata import version
+from pathlib import Path
+from types import FrameType
+from typing import IO, NamedTuple, NoReturn, NotRequired, TypedDict
+from xml.parsers.expat import ExpatError
+
+SHARE = Path(__file__).with_name("share")
+BACKGROUNDS = ("dark", "light")
+# A scheme that resets 'background' to Vim's guess, such as default, gets the
+# guess from the background color in COLORFGBG.
+COLORFGBG = {"dark": "15;0", "light": "0;15"}
+# bat themes support only these attributes.
+ATTRIBUTES = ("bold", "italic", "underline")
+SGR = re.compile(r"\x1b\[([0-9;]*)m")
+
+
+class Directories(NamedTuple):
+    themes: Path
+    cache: Path
+
+
+class Rule(TypedDict):
+    # A theme's first rule, which holds its global colors, has no name or scope.
+    name: NotRequired[str]
+    scope: NotRequired[str]
+    settings: dict[str, str]
+
+
+class Theme(TypedDict):
+    name: str
+    comment: str
+    settings: list[Rule]
+
+
+class Failure(Exception):
+    """Stops vim2bat with exit status 1, after printing the message if any."""
+
+
+class Stop(BaseException):
+    """Raised by a signal handler, so that vim2bat can stop Vim before exiting."""
+
+    def __init__(self, signum: int) -> None:
+        super().__init__(signum)
+        self.signum = signum
+
+
+# Vim processes still running, which vim2bat kills when it is stopped.
+_running: set[subprocess.Popen[bytes]] = set()
+_running_lock = threading.Lock()
+_stopping = threading.Event()
+
+
+@contextmanager
+def vim_error_file() -> Iterator[IO[bytes]]:
+    """Yields a temporary file to give Vim as its stderr."""
+    with tempfile.TemporaryFile() as errors:
+        # Vim writes some messages, such as a vimrc's errors, to its stderr
+        # directly. On Linux, the Vim scripts' writes through /dev/stderr keep
+        # their own offset, so without O_APPEND each would overwrite the other.
+        flags = fcntl.fcntl(errors, fcntl.F_GETFL)
+        fcntl.fcntl(errors, fcntl.F_SETFL, flags | os.O_APPEND)
+        yield errors
+
+
+def run_vim(
+    arguments: list[str], environment: dict[str, str], stderr: IO[bytes] | None = None
+) -> int:
+    """Runs Vim with your vimrc on a pseudo-terminal and returns its status.
+
+    Vim without a terminal numbers named cterm colors (such as DarkBlue)
+    differently from a terminal, so it gets one, as xterm-256color. What Vim
+    draws there is discarded, including most error messages, so the Vim
+    scripts write their errors to stderr.
+    """
+    if stderr is None:
+        # On Linux, /dev/stderr opens a redirected stderr's file anew, so
+        # vim2bat's own writes to a file opened with 2> would overwrite Vim's.
+        with vim_error_file() as errors:
+            try:
+                return run_vim(arguments, environment, errors)
+            finally:
+                errors.seek(0)
+                sys.stderr.write(errors.read().decode("utf-8", "replace"))
+    if _stopping.is_set():
+        raise Failure("")
+    controller, terminal = os.openpty()
+    # -n skips the swap file, whose warning for a file open in another Vim
+    # would count as an error. nomore keeps Vim from pausing at -- More --
+    # after a screenful of messages, which the Enter below would page through
+    # one line at a time.
+    command = [
+        "vim",
+        "-N",
+        "-i",
+        "NONE",
+        "-n",
+        "--cmd",
+        "set nomore",
+        *arguments,
+        "-c",
+        "qa!",
+    ]
+    # Its own session keeps Ctrl-C from interrupting Vim's script, which would
+    # leave Vim waiting for input instead of reaching qa!. vim2bat stops it
+    # instead.
+    try:
+        process = subprocess.Popen(
+            command,
+            stdin=terminal,
+            stdout=terminal,
+            stderr=stderr,
+            env={**os.environ, "TERM": "xterm-256color", **environment},
+            start_new_session=True,
+        )
+    except BaseException:
+        os.close(controller)
+        raise
+    finally:
+        os.close(terminal)
+    with _running_lock:
+        _running.add(process)
+        if _stopping.is_set():
+            process.kill()
+    try:
+        # A command the vimrc started in the background with :! can hold the
+        # terminal open after Vim exits.
+        while process.poll() is None:
+            if not select.select([controller], [], [], 0.5)[0]:
+                # Vim waits for a key at a prompt, such as the one after an
+                # error message, so an idle half second gets an Enter. If Vim
+                # was busy instead, it never reads the Enter, because it quits
+                # at the -c 'qa!' that ends its arguments.
+                try:
+                    os.write(controller, b"\r")
+                except OSError:
+                    break
+                continue
+            try:
+                if not os.read(controller, 65536):
+                    break
+            # Some systems report the closed terminal as an error rather than
+            # end of file.
+            except OSError:
+                break
+        return process.wait()
+    except BaseException:
+        process.kill()
+        raise
+    finally:
+        os.close(controller)
+        with _running_lock:
+            _running.discard(process)
+
+
+def stop_vims() -> None:
+    with _running_lock:
+        _stopping.set()
+        for process in _running:
+            process.kill()
+
+
+def bat_config_dir() -> Path:
+    result = subprocess.run(
+        ["bat", "--config-dir"], capture_output=True, text=True, check=True
+    )
+    folder = result.stdout.strip()
+    if not os.path.isabs(folder):
+        raise Failure(
+            f"bat's config folder {folder!r} isn't an absolute path; check "
+            "BAT_CONFIG_DIR"
+        )
+    return Path(folder)
+
+
+def cache_dir() -> Path:
+    # The XDG Base Directory spec says to ignore a relative path.
+    base = os.environ.get("XDG_CACHE_HOME", "")
+    return (Path(base) if os.path.isabs(base) else Path.home() / ".cache") / "vim2bat"
+
+
+def ask_vim(expression: str) -> list[str]:
+    """Returns the lines of a list or string that Vim evaluates with your vimrc."""
+    with tempfile.TemporaryDirectory() as directory:
+        out = Path(directory) / "out"
+        status = run_vim(
+            ["-c", f"call writefile(flatten([{expression}]), $OUTFILE)"],
+            {"OUTFILE": str(out)},
+        )
+        if status != 0 or not out.exists():
+            raise Failure(f"Vim couldn't evaluate {expression}")
+        return out.read_text(encoding="utf-8").splitlines()
+
+
+def color(value: str) -> str:
+    """Returns a Table 1 color as a bat theme color.
+
+    bat reads a color whose alpha is 00 as a palette slot number, and one whose
+    alpha is 01 as the terminal's default. Table 1 holds #rrggbb colors under
+    'termguicolors'.
+    """
+    if not value:
+        return "#00000001"
+    if value.startswith("#"):
+        return value
+    return f"#{int(value):02X}000000"
+
+
+def read_table(path: Path) -> dict[str, tuple[str, str, str]]:
+    """Returns Table 1 as {group: (foreground, background, font style)}."""
+    groups = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        group, foreground, background, attributes = line.split("\t")
+        style = " ".join(a for a in attributes.split(",") if a in ATTRIBUTES)
+        groups[group] = (foreground, background, style)
+    return groups
+
+
+def read_rules(strict: bool) -> list[tuple[str, str, bool]]:
+    """Returns (group, scopes, loose) for Table 2 and, unless strict, Table 3."""
+    rows = [(group, scopes, False) for group, scopes in tsv(SHARE / "strict.tsv", 2)]
+    if not strict:
+        rows += [
+            (group, scopes, True)
+            for _filetype, group, scopes in tsv(SHARE / "loose.tsv", 3)
+        ]
+    return rows
+
+
+def tsv(path: Path, fields: int) -> list[list[str]]:
+    return [
+        line.split("\t", fields - 1)
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line
+    ]
+
+
+def rule(
+    groups: dict[str, tuple[str, str, str]], group: str, scopes: str, loose: bool
+) -> Rule:
+    foreground, _background, style = groups[group]
+    # bat keeps the color of a less specific rule that also matches when this
+    # one has no foreground, so a loose rule always writes one, taking Normal's
+    # when its group has none.
+    if loose and not foreground:
+        foreground = groups["Normal"][0]
+    settings = {}
+    if foreground or loose:
+        settings["foreground"] = color(foreground)
+    # Written even when empty, so that a rule nested inside another doesn't
+    # inherit the outer rule's bold or italic.
+    settings["fontStyle"] = style
+    return {"name": group, "scope": scopes, "settings": settings}
+
+
+def theme(
+    name: str,
+    comment: str,
+    groups: dict[str, tuple[str, str, str]],
+    rules: list[tuple[str, str, bool]],
+) -> Theme:
+    globals_ = {
+        "foreground": color(groups["Normal"][0]),
+        # bat's --highlight-line, which fzf.vim's preview uses to mark the
+        # matched line, draws with lineHighlight.
+        "lineHighlight": color(groups["CursorLine"][1]),
+    }
+    # A group from a newer Vim can't color anything in this one, so it gets no
+    # rule.
+    scoped = [rule(groups, *row) for row in rules if row[0] in groups]
+    return {
+        "name": name,
+        # vim2bat compare reads the options a theme was built with from here.
+        "comment": comment,
+        "settings": [{"settings": globals_}, *scoped],
+    }
+
+
+def theme_names(scheme: str, backgrounds: Sequence[str]) -> dict[str, str]:
+    """Names the themes: the background is part of the name only when the
+    scheme has both."""
+    if len(backgrounds) > 1:
+        return {background: f"vim-{scheme}-{background}" for background in backgrounds}
+    return {background: f"vim-{scheme}" for background in backgrounds}
+
+
+def build_comment(scheme: str, options: argparse.Namespace) -> str:
+    words = ["vim2bat"]
+    if options.strict:
+        words.append("-s")
+    if options.truecolor:
+        words.append("-t")
+    if options.palette:
+        words += ["-p", options.palette]
+    if scheme.startswith("-"):
+        words.append("--")
+    return shlex.join([*words, scheme])
+
+
+def vim_environment(
+    scheme: str, background: str, options: argparse.Namespace
+) -> dict[str, str]:
+    return {
+        "SCHEME": scheme,
+        "BACKGROUND": background,
+        "COLORFGBG": COLORFGBG[background],
+        "T_CO": options.palette or "",
+        "TERMGUICOLORS": "1" if options.truecolor else "",
+    }
+
+
+def build(
+    scheme: str,
+    options: argparse.Namespace,
+    directories: Directories,
+    stderr: IO[bytes] | None = None,
+) -> None:
+    """Writes the themes for one scheme."""
+    tables = directories.cache / "tables" / scheme
+    tables.mkdir(parents=True, exist_ok=True)
+    found = []
+    for background in BACKGROUNDS:
+        table = tables / f"vim-groups-{background}.tsv"
+        environment = {
+            **vim_environment(scheme, background, options),
+            "OUTFILE": str(table),
+        }
+        table.unlink(missing_ok=True)
+        # vim-groups.vim prints why it failed.
+        status = run_vim(["-S", str(SHARE / "vim-groups.vim")], environment, stderr)
+        if status != 0:
+            raise Failure(f"Vim exited with status {status}")
+        if not table.exists():
+            raise Failure(f"Vim wrote no table for {scheme}")
+        # vim-groups.vim writes an empty table for a background the scheme lacks.
+        if table.stat().st_size:
+            found.append(background)
+    rules = read_rules(options.strict)
+    comment = build_comment(scheme, options)
+    directories.themes.mkdir(parents=True, exist_ok=True)
+    for background, name in theme_names(scheme, found).items():
+        groups = read_table(tables / f"vim-groups-{background}.tsv")
+        # Two schemes can build the same name in parallel, such as one with both
+        # backgrounds and another with its name plus -dark, so each write gets
+        # its own temporary file.
+        descriptor, temporary = tempfile.mkstemp(dir=directories.themes, suffix=".tmp")
+        try:
+            with os.fdopen(descriptor, "wb") as f:
+                plistlib.dump(theme(name, comment, groups, rules), f, sort_keys=False)
+            os.chmod(temporary, 0o644)
+            os.replace(temporary, directories.themes / f"{name}.tmTheme")
+        except BaseException:
+            Path(temporary).unlink(missing_ok=True)
+            raise
+
+
+def build_quietly(
+    scheme: str, options: argparse.Namespace, directories: Directories
+) -> tuple[bool, str]:
+    """Builds one scheme for --all and returns (succeeded, its error output)."""
+    with vim_error_file() as errors:
+        message = ""
+        try:
+            build(scheme, options, directories, errors)
+            succeeded = True
+        except Failure as failure:
+            succeeded = False
+            if str(failure):
+                message = f"vim2bat: {failure}\n"
+        errors.seek(0)
+        return succeeded, errors.read().decode("utf-8", "replace") + message
+
+
+def build_all(options: argparse.Namespace, directories: Directories) -> list[str]:
+    """Builds every scheme Vim lists, one per CPU at a time, and returns the
+    ones that failed."""
+    schemes = ask_vim('getcompletion("", "color")')
+    failed = []
+    with ThreadPoolExecutor(os.cpu_count() or 1) as pool:
+        try:
+            futures = {
+                pool.submit(build_quietly, scheme, options, directories): scheme
+                for scheme in schemes
+            }
+            for count, future in enumerate(as_completed(futures), 1):
+                scheme = futures[future]
+                succeeded, errors = future.result()
+                # Each scheme's errors follow its progress line, so that errors
+                # from schemes building at the same time don't interleave.
+                print(f"vim2bat: [{count}/{len(schemes)}] {scheme}", file=sys.stderr)
+                sys.stderr.write(errors)
+                if not succeeded:
+                    failed.append(scheme)
+        except BaseException:
+            pool.shutdown(wait=False, cancel_futures=True)
+            stop_vims()
+            raise
+    return failed
+
+
+def build_cache() -> None:
+    # bat reads cache as a file name instead of its subcommand when the current
+    # folder has an entry named cache.
+    with tempfile.TemporaryDirectory() as empty:
+        result = subprocess.run(
+            ["bat", "cache", "--build"],
+            cwd=empty,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    # bat reports a theme it can't parse on stdout and still exits 0, so only
+    # the lines a clean build prints are dropped.
+    for line in result.stdout.splitlines():
+        if not line.endswith(" ... okay") and not line.startswith(
+            "No syntaxes were found"
+        ):
+            print(line, file=sys.stderr)
+    sys.stderr.write(result.stderr)
+
+
+def generate_parser(
+    parser_class: type[argparse.ArgumentParser] = argparse.ArgumentParser,
+) -> argparse.ArgumentParser:
+    parser = parser_class(
+        prog="vim2bat",
+        description=(
+            "Builds bat themes from a Vim colorscheme, as Vim shows it with your "
+            "vimrc in a 256-color terminal. A scheme with both backgrounds gets "
+            "vim-SCHEME-dark and vim-SCHEME-light; one with a single background "
+            "gets vim-SCHEME. Then it rebuilds bat's cache."
+        ),
+        epilog=(
+            "To measure a theme against Vim, run vim2bat compare THEME FILE... "
+            "(see vim2bat compare --help). To build a scheme named compare, run "
+            "vim2bat -- compare."
+        ),
+    )
+    target = parser.add_mutually_exclusive_group(required=True)
+    target.add_argument("scheme", nargs="?", help="the colorscheme to build")
+    target.add_argument(
+        "-a", "--all", action="store_true", help="build every colorscheme Vim lists"
+    )
+    parser.add_argument(
+        "-c",
+        "--clean",
+        action="store_true",
+        help="first delete vim2bat's cache and the whole bat themes folder",
+    )
+    parser.add_argument(
+        "-s",
+        "--strict",
+        action="store_true",
+        help="map only Vim's standard groups (strict.tsv)",
+    )
+    parser.add_argument(
+        "-t",
+        "--truecolor",
+        action="store_true",
+        help="turn on 'termguicolors' to use the scheme's 24-bit colors",
+    )
+    parser.add_argument(
+        "-p",
+        "--palette",
+        choices=("16", "256"),
+        help="override your vimrc's 't_Co' with 16 or 256 colors",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {version('vim2bat')}"
+    )
+    return parser
+
+
+def generate(argv: list[str]) -> None:
+    parser = generate_parser()
+    options = parser.parse_args(argv)
+    # vim-groups.vim passes the name to :colorscheme, which reads a blank name,
+    # or one that starts with | or ", as no name and keeps the vimrc's scheme.
+    if options.scheme is not None and re.match(r'\s*($|["|])', options.scheme):
+        parser.error("the scheme name is empty")
+    # The scheme name becomes part of a theme's file name.
+    if "/" in (options.scheme or ""):
+        parser.error("a scheme name can't contain /")
+    directories = Directories(bat_config_dir() / "themes", cache_dir())
+    if options.clean:
+        folders = (directories.cache, directories.themes)
+        for folder in folders:
+            if folder.is_symlink():
+                raise Failure(
+                    f"{folder} is a symbolic link; -c deletes only a real folder"
+                )
+        for folder in folders:
+            with suppress(FileNotFoundError):
+                shutil.rmtree(folder)
+    if options.all:
+        failed = build_all(options, directories)
+        # This runs even when some schemes failed, so that the rest are usable.
+        build_cache()
+        if failed:
+            raise Failure(f"failed: {' '.join(failed)}")
+        return
+    build(options.scheme, options, directories)
+    build_cache()
+
+
+def compare_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="vim2bat compare",
+        description=(
+            "Reports how often a bat theme that vim2bat built shows each character "
+            "of FILE in the same color as Vim does, with the options the theme was "
+            "built with. To measure strict.tsv alone, build the theme with -s first, "
+            "since both builds use the same name."
+        ),
+    )
+    parser.add_argument("theme", metavar="THEME")
+    parser.add_argument("files", metavar="FILE", nargs="+")
+    return parser
+
+
+def bat_colors(text: str) -> dict[tuple[int, int], str | None]:
+    """Returns {(line, index): color} for each character of bat's output."""
+    colors = {}
+    for lnum, line in enumerate(text.split("\n"), 1):
+        current, idx = None, 0
+        for k, part in enumerate(SGR.split(line)):
+            if k % 2:
+                current = apply(current, part)
+                continue
+            for _ in part:
+                colors[(lnum, idx)] = current
+                idx += 1
+    return colors
+
+
+def apply(current: str | None, params: str) -> str | None:
+    """Returns the foreground color after one SGR sequence."""
+    codes = params.split(";") if params else ["0"]
+    k = 0
+    while k < len(codes):
+        code = codes[k]
+        if code == "38" and codes[k + 1] == "2":
+            current = "#" + "".join(f"{int(c):02x}" for c in codes[k + 2 : k + 5])
+            k += 5
+            continue
+        if code == "38":
+            current = codes[k + 2]
+            k += 3
+            continue
+        if code in ("0", "39"):
+            current = None
+        elif code.isdigit() and 30 <= int(code) <= 37:
+            current = str(int(code) - 30)
+        k += 1
+    return current
+
+
+class CommentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        raise ValueError(message)
+
+
+def built_with(theme_name: str, comment: str) -> argparse.Namespace:
+    """Returns the options in a theme's comment, if vim2bat built the theme
+    under its own name."""
+    options: argparse.Namespace | None
+    try:
+        words = shlex.split(comment)
+        if words[:1] != ["vim2bat"]:
+            raise ValueError
+        options = generate_parser(CommentParser).parse_args(words[1:])
+    except ValueError:
+        options = None
+    if (
+        options is None
+        or options.scheme is None
+        or theme_name
+        not in (
+            f"vim-{options.scheme}",
+            *theme_names(options.scheme, BACKGROUNDS).values(),
+        )
+    ):
+        raise Failure(f"{theme_name} wasn't built by vim2bat under that name")
+    return options
+
+
+def compare(argv: list[str]) -> None:
+    args = compare_parser().parse_args(argv)
+    # bat falls back to its default theme for an unknown name instead of failing.
+    listed = subprocess.run(
+        ["bat", "--list-themes", "--color=never"],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.splitlines()
+    if args.theme not in listed:
+        raise Failure(f"no bat theme named {args.theme}")
+    path = bat_config_dir() / "themes" / f"{args.theme}.tmTheme"
+    if not path.exists():
+        raise Failure(
+            f"{path} doesn't exist; vim2bat compare measures only themes that "
+            "vim2bat built"
+        )
+    try:
+        data = plistlib.loads(path.read_bytes())
+    except (ValueError, ExpatError) as error:
+        raise Failure(f"can't read {path}: {error}") from None
+    comment = data.get("comment") if isinstance(data, dict) else None
+    options = built_with(args.theme, comment if isinstance(comment, str) else "")
+    scheme = options.scheme
+    suffix = args.theme[len(f"vim-{scheme}") :]
+    # A scheme with one background sets 'background' itself.
+    background = suffix[1:] if suffix else "dark"
+    totals: Counter[str] = Counter()
+    agrees: Counter[str] = Counter()
+    mismatches: Counter[tuple[str, str, str, str | None]] = Counter()
+    with tempfile.TemporaryDirectory() as directory:
+        for index, name in enumerate(args.files):
+            out = Path(directory) / f"{index}.tsv"
+            environment = {
+                **vim_environment(scheme, background, options),
+                "TARGET": os.path.join(os.getcwd(), name),
+                "OUTFILE": str(out),
+            }
+            # The backtracking regex engine, which macOS's Vim uses by default,
+            # stalls on the TypeScript syntax. Other syntaxes keep the default
+            # because the NFA engine highlights some of them, such as ERB,
+            # differently. The autocmd gets its own group, which a bare
+            # autocmd! in your vimrc doesn't clear.
+            status = run_vim(
+                [
+                    "--cmd",
+                    "augroup vim2bat | augroup END",
+                    "--cmd",
+                    (
+                        "autocmd vim2bat FileType typescript,typescriptreact "
+                        "set regexpengine=2"
+                    ),
+                    "-S",
+                    str(SHARE / "vim-slots.vim"),
+                ],
+                environment,
+            )
+            if status != 0:
+                print(f"vim2bat: Vim reported an error on {name}", file=sys.stderr)
+            # vim-slots.vim writes nothing when the scheme fails to load.
+            if not out.exists():
+                raise Failure("")
+            # Without COLORTERM, bat rounds #rrggbb colors to the nearest of 256.
+            bat = subprocess.run(
+                [
+                    "bat",
+                    f"--theme={args.theme}",
+                    "--color=always",
+                    "--style=plain",
+                    "--tabs=0",
+                    "--wrap=never",
+                    "--",
+                    name,
+                ],
+                capture_output=True,
+                check=True,
+                env={**os.environ, "COLORTERM": "truecolor"},
+            )
+            got = bat_colors(bat.stdout.decode("utf-8"))
+            lines = out.read_text(encoding="utf-8").splitlines()
+            lang = lines[0].removeprefix("#ft=") if lines else ""
+            total = agree = 0
+            for row in lines[1:]:
+                lnum, idx, vim, chain = row.split("\t")
+                bat_color = got.get((int(lnum), int(idx)))
+                total += 1
+                # Vim has no color for text in a Normal without a foreground,
+                # which bat draws in the terminal's default.
+                if bat_color == (vim or None):
+                    agree += 1
+                else:
+                    mismatches[(lang, chain or "(no syntax item)", vim, bat_color)] += 1
+            print(f"{100 * agree / max(total, 1):5.1f}%  {total:6}  {lang:16} {name}")
+            for key in (lang, "all"):
+                totals[key] += total
+                agrees[key] += agree
+    print()
+    for key in sorted(totals, key=lambda key: key == "all"):
+        print(
+            f"{100 * agrees[key] / max(totals[key], 1):5.1f}%  {totals[key]:6}  {key}"
+        )
+    print("\nchars  language  Vim syntax item>links  Vim color  bat color")
+    for (lang, chain, vim, bat_color), n in mismatches.most_common(30):
+        print(
+            f"{n:5}  {lang}  {chain}  {vim or 'default'}  "
+            f"{'default' if bat_color is None else bat_color}"
+        )
+
+
+def stop(signum: int, _frame: FrameType | None) -> NoReturn:
+    raise Stop(signum)
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    for signum in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP):
+        signal.signal(signum, stop)
+    try:
+        if argv[:1] == ["compare"]:
+            compare(argv[1:])
+        else:
+            generate(argv)
+    except Stop as stopped:
+        stop_vims()
+        # A shell running vim2bat in a loop stops the loop on Ctrl-C only when
+        # vim2bat dies by the signal, not when it exits with 130. Dying skips the
+        # flush of stdout and stderr that exiting does.
+        sys.stdout.flush()
+        sys.stderr.flush()
+        signal.signal(stopped.signum, signal.SIG_DFL)
+        os.kill(os.getpid(), stopped.signum)
+        return 128 + stopped.signum
+    except Failure as failure:
+        if str(failure):
+            print(f"vim2bat: {failure}", file=sys.stderr)
+        return 1
+    except FileNotFoundError as error:
+        print(f"vim2bat: {error.filename} not found", file=sys.stderr)
+        return 1
+    except OSError as error:
+        print(f"vim2bat: {error}", file=sys.stderr)
+        return 1
+    except subprocess.CalledProcessError as error:
+        print(f"vim2bat: {shlex.join(error.cmd)} failed", file=sys.stderr)
+        reason = (
+            error.stderr.decode() if isinstance(error.stderr, bytes) else error.stderr
+        )
+        sys.stderr.write(SGR.sub("", reason or ""))
+        return 1
+    return 0

vim2bat/share/loose.tsv

@@ -0,0 +1,84 @@
+ruby	Normal	punctuation.accessor.dot.ruby, punctuation.accessor.double-colon.ruby, punctuation.definition.group.begin.ruby, punctuation.definition.group.end.ruby, punctuation.section.array.ruby, punctuation.section.scope.ruby, punctuation.separator.sequence.ruby, punctuation.separator.ruby, punctuation.separator.key-value.ruby, punctuation.separator.inheritance.ruby, punctuation.definition.parameters.begin.ruby, punctuation.definition.parameters.end.ruby, punctuation.terminator.statement.ruby
+ruby	Normal	punctuation.definition.constant.ruby
+ruby	Normal	keyword.operator.arithmetic.ruby, keyword.operator.assignment.ruby, keyword.operator.assignment.augmented.ruby, keyword.operator.bitwise.ruby, keyword.operator.comparison.ruby, keyword.operator.conditional.ruby, keyword.operator.logical.ruby, keyword.operator.other.ruby, keyword.operator.range.ruby, keyword.operator.ruby, keyword.operator.splat.ruby
+ruby	Normal	support.function.builtin.ruby
+ruby	Normal	variable.parameter.ruby
+ruby	rubySymbol	constant.other.symbol.ruby, constant.other.symbol.single-quoted.ruby, constant.other.symbol.double-quoted.ruby
+ruby	rubyConstant	support.class.ruby, variable.other.constant.ruby, entity.name.constant.ruby, entity.other.inherited-class.ruby, support.other.namespace.ruby
+ruby	rubyClassName	entity.name.class.ruby
+ruby	rubyModuleName	entity.name.namespace.ruby
+ruby	rubyDefine	keyword.declaration.function.ruby
+ruby	rubyClass	keyword.declaration.class.ruby
+ruby	rubyModule	keyword.declaration.namespace.ruby
+ruby	rubyMacro	keyword.other.special-method.ruby
+ruby	rubyInclude	keyword.control.import.ruby
+ruby	rubyPseudoVariable	variable.language.ruby
+ruby	rubyInstanceVariable	punctuation.definition.variable.ruby
+ruby	rubyComment	punctuation.definition.comment.ruby
+ruby	rubyFloat	punctuation.separator.decimal.ruby
+ruby	rubyDocumentation	punctuation.definition.comment.begin.ruby, punctuation.definition.comment.end.ruby
+ruby	rubyRegexpDelimiter	keyword.other.ruby
+ruby	rubyInteger	punctuation.definition.numeric.base.ruby
+html	htmlTagName	entity.name.tag.structure.any.html, entity.name.tag.block.any.html, entity.name.tag.block.form.html, entity.name.tag.inline.any.html, entity.name.tag.inline.form.html, entity.name.tag.inline.a.html, entity.name.tag.inline.table.html
+html	htmlArg	entity.other.attribute-name.html, entity.other.attribute-name.class.html, entity.other.attribute-name.id.html, entity.other.attribute-name.style.html
+html	htmlTag	punctuation.definition.tag.begin.html, punctuation.definition.tag.end.html
+html	htmlString	punctuation.definition.string.begin.html, punctuation.definition.string.end.html
+css	cssClassName	source.css entity.other.attribute-name.class.css
+css	cssBraces	source.css punctuation.section.property-list.css
+css	cssUnitDecorators	source.css keyword.other.unit.css
+css	cssNoise	source.css punctuation.separator.key-value.css, source.css punctuation.terminator.rule.css
+css	cssTagName	source.css entity.name.tag.css
+css	cssClassNameDot	source.css punctuation.definition.entity.css
+css	cssImportant	source.css keyword.other.important.css
+typescript	Normal	source.ts variable.other, source.tsx variable.other, variable.other.constant.ts, variable.other.constant.tsx, variable.other.constant.object.ts, variable.other.constant.object.tsx, variable.other.constant.property.ts, variable.other.constant.property.tsx, variable.other.constant.object.property.ts, variable.other.constant.object.property.tsx
+typescript	Normal	source.ts punctuation.separator.comma, source.tsx punctuation.separator.comma, source.ts punctuation.accessor, source.tsx punctuation.accessor, source.ts punctuation.separator.key-value, source.tsx punctuation.separator.key-value, source.ts punctuation.terminator.statement, source.tsx punctuation.terminator.statement
+typescript	typescriptBraces	source.ts punctuation.definition.block, source.tsx punctuation.definition.block
+typescript	Normal	entity.name.function.ts, entity.name.function.tsx
+typescript	typescriptObjectLabel	meta.object-literal.key.ts, meta.object-literal.key.tsx
+typescript	typescriptTypeReference	entity.name.type.ts, entity.name.type.tsx
+typescript	Keyword	support.variable.property.dom.ts, support.variable.property.dom.tsx
+typescript	typescriptCall	variable.parameter.ts, variable.parameter.tsx
+typescript	typescriptVariable	storage.type.ts, storage.type.tsx
+typescript	typescriptString	punctuation.definition.string.begin.ts, punctuation.definition.string.begin.tsx, punctuation.definition.string.end.ts, punctuation.definition.string.end.tsx
+typescriptreact	tsxTagName	support.class.component.tsx
+typescriptreact	tsxAttrib	entity.other.attribute-name.tsx
+typescriptreact	tsxTag	punctuation.definition.tag.begin.tsx, punctuation.definition.tag.end.tsx
+javascript	Normal	variable.other.readwrite.js, variable.other.object.js, variable.other.property.js, variable.other.property.static.js, variable.other.class.js, variable.other.constant.js, variable.parameter.function.js, variable.function.js, variable.function.constructor.js, variable.function.tagged-template.js, entity.name.function.js
+javascript	Normal	string.unquoted.label.js
+javascript	Normal	keyword.operator.accessor.js, keyword.operator.assignment.js, keyword.operator.assignment.augmented.js, keyword.operator.arithmetic.js, keyword.operator.comparison.js, keyword.operator.relational.js, keyword.operator.logical.js, keyword.operator.bitwise.js, keyword.operator.ternary.js, keyword.operator.spread.js, storage.type.function.arrow.js
+javascript	Normal	punctuation.terminator.statement.js, punctuation.separator.key-value.js, punctuation.separator.parameter.function.js
+javascriptreact	Normal	punctuation.definition.tag.begin.jsx, punctuation.definition.tag.end.jsx, keyword.operator.assignment.jsx
+javascript	javaScriptReserved	storage.type.js, storage.type.class.js, storage.type.extends.js
+javascript	javaScriptFunction	storage.type.function.js
+javascript	javaScriptBraces	meta.brace.curly.begin.js, meta.brace.curly.end.js, meta.brace.square.begin.js, meta.brace.square.end.js, punctuation.section.embedded.begin.jsx, punctuation.section.embedded.end.jsx
+javascript	String	punctuation.definition.string.begin.js, punctuation.definition.string.end.js, punctuation.definition.string.begin.jsx, punctuation.definition.string.end.jsx
+scss	Normal	source.scss variable.function, source.scss entity.name.function
+scss	PreProc	source.scss keyword.control.at-rule
+sass	sassClass	source.scss entity.other.attribute-name.class
+css	cssTagName	source.scss entity.name.tag
+css	cssPseudoClassId	source.scss entity.other.pseudo-class, source.scss entity.other.pseudo-element
+scss	Normal	source.scss punctuation.terminator.rule
+scss	Normal	source.scss punctuation.separator.key-value
+scss	Normal	source.scss punctuation.separator.sequence
+scss	Normal	source.scss punctuation.definition.group
+css	cssBraces	source.scss punctuation.section.property-list
+sass	sassVariable	source.scss punctuation.definition.variable
+yaml	yamlPlainScalar	string.unquoted.plain.out.yaml
+yaml	yamlBlockString	string.unquoted.block.yaml
+yaml	yamlBlockMappingKey	entity.name.tag.yaml
+yaml	yamlAlias	variable.other.alias.yaml
+vim	vimFunctionBang	meta.function.viml
+vim	vimCommand	storage.function.viml
+vim	vimFunctionName	entity.name.function.viml
+vim	vimCommand	keyword.control.viml
+vim	vimCommand	support.function.viml
+vim	Special	support.type.viml
+gitcommit	gitcommitSummary	markup.heading.subject.git.commit
+gitcommit	gitcommitComment	punctuation.definition.comment.git.commit
+gitcommit	gitcommitSelectedFile	markup.changed.file.content.git.commit
+diff	diffLine	meta.range.unified.diff, punctuation.definition.range.diff
+diff	diffSubname	entity.name.section.diff
+diff	diffOldFile	meta.header.from-file.diff, punctuation.definition.from-file.diff
+diff	diffNewFile	meta.header.to-file.diff, punctuation.definition.to-file.diff
+diff	diffAdded	punctuation.definition.inserted.diff
+diff	diffRemoved	punctuation.definition.deleted.diff

vim2bat/share/strict.tsv

@@ -0,0 +1,37 @@
+Comment	comment, punctuation.definition.comment
+Constant	constant, entity.name.constant, variable.other.constant, support.constant
+String	string
+Character	constant.character
+Number	constant.numeric
+Boolean	constant.language.boolean
+Float	constant.numeric.float
+Identifier	variable, support.variable
+Function	entity.name.function, variable.function, support.function
+Statement	keyword
+Conditional	keyword.control.conditional, keyword.control.switch
+Repeat	keyword.control.loop
+Label	keyword.control.conditional.case, keyword.control.conditional.default, entity.name.label, variable.label
+Operator	keyword.operator
+Keyword	keyword.other
+Exception	keyword.control.exception, keyword.control.trycatch, keyword.control.flow.throw, keyword.control.flow.raise
+PreProc	keyword.control.preprocessor, keyword.other.preprocessor
+Include	keyword.control.import.include
+Define	keyword.control.import.define
+Macro	entity.name.macro, support.macro, variable.macro, entity.name.constant.preprocessor, entity.name.function.preprocessor, variable.function.assumed-macro
+PreCondit	keyword.control.import.else, meta.preprocessor keyword.control.import
+Type	storage.type, entity.name.type, support.type
+StorageClass	storage.modifier
+Structure	storage.type.struct, storage.type.union, storage.type.enum, storage.type.class, keyword.declaration.struct, keyword.declaration.union, keyword.declaration.enum, keyword.declaration.class, storage.type.keyword.struct
+Typedef	entity.name.type.typedef
+SpecialChar	constant.character.escape
+Delimiter	punctuation
+SpecialComment	keyword.other.documentation
+Underlined	markup.underline
+Bold	markup.bold
+Italic	markup.italic
+BoldItalic	markup.bold markup.italic, markup.italic markup.bold
+Error	invalid
+Todo	comment.line.todo, keyword.other.todo
+Added	markup.inserted
+Changed	markup.changed
+Removed	markup.deleted

vim2bat/share/vim-groups.vim

@@ -0,0 +1,58 @@
+" Writes $OUTFILE: every highlight group with the foreground color, background
+" color (palette slots, or #rrggbb under 'termguicolors') and attributes that
+" the colorscheme $SCHEME gives it when 'background' is $BACKGROUND (dark or
+" light), or no groups if $SCHEME lacks that background.
+
+" vim2bat's -p and -t options, which override your vimrc.
+if $T_CO !=# ''
+  let &t_Co = $T_CO
+endif
+if $TERMGUICOLORS !=# ''
+  set termguicolors
+endif
+let &background = $BACKGROUND
+" The standard groups, and the links of the language groups, exist only with
+" syntax highlighting on, which a vimrc can leave off.
+if !exists('g:syntax_on')
+  syntax enable
+endif
+
+" Vim on a terminal exits 0 after an error, so any error here makes it exit 1
+" instead, but not one that silent! hides. That includes a scheme that fails to
+" load, which would leave the colors of whatever scheme your vimrc loaded.
+try
+  execute 'colorscheme' $SCHEME
+
+  let s:dir = expand('<sfile>:p:h')
+  " Language groups exist only once their syntax file has run. They load after
+  " the colorscheme because its :hi clear hides them from getcompletion().
+  for s:ft in uniq(sort(map(readfile(s:dir . '/loose.tsv'), 'split(v:val, "\t")[0]')))
+    let &syntax = s:ft
+  endfor
+
+  let s:attrs = ['bold', 'italic', 'underline', 'undercurl', 'strikethrough', 'reverse', 'standout']
+  let s:rows = []
+  for s:group in filter(getcompletion('', 'highlight'), 'hlexists(v:val)')
+    let s:id = synIDtrans(hlID(s:group))
+    let s:on = []
+    for s:attr in s:attrs
+      if synIDattr(s:id, s:attr, 'cterm') == '1'
+        call add(s:on, s:attr)
+      endif
+    endfor
+    " With 'termguicolors', Vim draws a group's GUI colors, or its cterm colors
+    " if it has none, and always its cterm attributes.
+    let s:colors = &termguicolors ? [synIDattr(s:id, 'fg#', 'gui'), synIDattr(s:id, 'bg#', 'gui')] : ['', '']
+    if s:colors == ['', '']
+      let s:colors = [synIDattr(s:id, 'fg', 'cterm'), synIDattr(s:id, 'bg', 'cterm')]
+    endif
+    call add(s:rows, join([s:group] + s:colors + [join(s:on, ',')], "\t"))
+  endfor
+  " A scheme with one background switches 'background' to it.
+  call writefile(&background ==# $BACKGROUND ? s:rows : [], $OUTFILE)
+catch
+  " On Linux, /dev/stderr opens a redirected stderr's file anew, which Vim
+  " would truncate without 'a'.
+  call writefile([v:exception], '/dev/stderr', 'a')
+  cquit
+endtry

vim2bat/share/vim-slots.vim

@@ -0,0 +1,80 @@
+" Writes $OUTFILE: for each non-blank character of $TARGET, its line, its
+" character index, the color (palette slot, or #rrggbb under 'termguicolors')
+" the colorscheme $SCHEME shows it in after 'background' is set to $BACKGROUND,
+" and the chain of links from its syntax item to the group that colors it. The
+" first line is the filetype.
+
+" See vim-groups.vim.
+if $T_CO !=# ''
+  let &t_Co = $T_CO
+endif
+if $TERMGUICOLORS !=# ''
+  set termguicolors
+endif
+let &background = $BACKGROUND
+if !exists('g:syntax_on')
+  syntax enable
+endif
+try | execute 'colorscheme' $SCHEME | catch | call writefile([v:exception], '/dev/stderr', 'a') | cquit | endtry
+
+let s:chains = {}
+function s:Chain(name) abort
+  if !has_key(s:chains, a:name)
+    let l:chain = [a:name]
+    while 1
+      let l:next = matchstr(execute('highlight ' . l:chain[-1]), 'links to \zs\S\+')
+      if l:next ==# '' || index(l:chain, l:next, 0, v:true) >= 0
+        break
+      endif
+      call add(l:chain, l:next)
+    endwhile
+    let s:chains[a:name] = join(l:chain, '>')
+  endif
+  return s:chains[a:name]
+endfunction
+
+" As in vim-groups.vim.
+let s:fgs = {}
+function s:Fg(id) abort
+  if !has_key(s:fgs, a:id)
+    let l:colors = &termguicolors ? [synIDattr(a:id, 'fg#', 'gui'), synIDattr(a:id, 'bg#', 'gui')] : ['', '']
+    let s:fgs[a:id] = l:colors == ['', ''] ? synIDattr(a:id, 'fg', 'cterm') : l:colors[0]
+  endif
+  return s:fgs[a:id]
+endfunction
+
+let s:rows = []
+" As in vim-groups.vim, but $OUTFILE is still written after an error, so that
+" vim2bat compare compares what there is and reports the error.
+try
+  execute 'edit' fnameescape($TARGET)
+  " Highlight each line as Vim would after scrolling down from the top.
+  syntax sync fromstart
+  call add(s:rows, '#ft=' . &filetype)
+  let s:normal = s:Fg(synIDtrans(hlID('Normal')))
+  for s:lnum in range(1, line('$'))
+    let s:col = 1
+    let s:idx = 0
+    for s:char in split(getline(s:lnum), '\zs')
+      " synID() misses a match that starts on a blank unless it visits that
+      " column too.
+      let s:id = synID(s:lnum, s:col, 1)
+      if s:char !~# '\s'
+        let s:fg = s:Fg(synIDtrans(s:id))
+        let s:name = synIDattr(s:id, 'name')
+        call add(s:rows, join([s:lnum, s:idx, s:fg ==# '' ? s:normal : s:fg, s:name ==# '' ? '' : s:Chain(s:name)], "\t"))
+      endif
+      let s:col += len(s:char)
+      " split() keeps composing characters with their base character. Count
+      " each one, as vim2bat compare does.
+      let s:idx += strchars(s:char)
+    endfor
+  endfor
+catch
+  call writefile([v:exception], '/dev/stderr', 'a')
+  let s:failed = 1
+endtry
+call writefile(s:rows, $OUTFILE)
+if exists('s:failed')
+  cquit
+endif

vim2bat-0.1.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: vim2bat
+Version: 0.1.0
+Summary: Generate bat themes from Vim colorschemes
+Project-URL: Homepage, https://github.com/redodson01/vim2bat
+Project-URL: Repository, https://github.com/redodson01/vim2bat
+Project-URL: Issues, https://github.com/redodson01/vim2bat/issues
+Project-URL: Changelog, https://github.com/redodson01/vim2bat/blob/main/CHANGELOG.md
+Author: Richard E. Dodson
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Text Editors
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# vim2bat
+
+[![CI](https://github.com/redodson01/vim2bat/actions/workflows/ci.yml/badge.svg)](https://github.com/redodson01/vim2bat/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/github/v/release/redodson01/vim2bat)](https://github.com/redodson01/vim2bat/releases/latest)
+[![Release Date](https://img.shields.io/github/release-date/redodson01/vim2bat)](https://github.com/redodson01/vim2bat/releases/latest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/redodson01/vim2bat/blob/main/LICENSE)
+
+Builds [bat](https://github.com/sharkdp/bat) themes from Vim colorschemes, so
+that bat, and tools that use it such as fzf.vim's previews and delta, color code
+the way Vim does.
+
+## The problem
+
+bat ships its own themes, and most of them use 24-bit colors. If you use a Vim
+colorscheme, especially one built on your terminal's palette like solarized8
+with `g:solarized_use16`, the previews and diffs that bat colors look different
+from the code you edit in Vim. A matching bat theme means mapping Vim's
+highlight groups to TextMate scopes by hand, for each scheme and background.
+
+vim2bat asks Vim which colors a colorscheme gives each highlight group, with
+your vimrc, and writes bat themes that use the same palette slots, or the same
+24-bit colors.
+
+## Install
+
+### Homebrew (macOS and Linux)
+
+```bash
+brew install redodson01/tap/vim2bat
+```
+
+### PyPI
+
+```bash
+uv tool install vim2bat   # or: pipx install vim2bat
+```
+
+### From source
+
+```bash
+git clone https://github.com/redodson01/vim2bat.git
+cd vim2bat
+uv tool install .   # or: uv tool install --editable . to follow edits to the checkout
+```
+
+The PyPI and source installs put the `vim2bat` command in `~/.local/bin` by
+default. Make sure that folder is on your `$PATH` (`uv tool update-shell` or
+`pipx ensurepath` adds it).
+
+## Runtime requirements
+
+- Vim 9.1 or newer, with the colorschemes you want to convert
+- bat (0.25 or newer for the `--theme-dark` and `--theme-light` settings below)
+- Python 3.11 or newer
+
+Debian and Ubuntu install bat as `batcat`. vim2bat runs `bat`, so link it:
+`ln -s /usr/bin/batcat ~/.local/bin/bat`.
+
+## Usage
+
+```bash
+vim2bat retrobox     # builds vim-retrobox-dark and vim-retrobox-light
+vim2bat --all        # builds every colorscheme Vim lists
+bat --theme=vim-retrobox-dark file.rb
+```
+
+| Option | Effect |
+|---|---|
+| `-a`, `--all` | Builds every colorscheme Vim lists, several at a time |
+| `-c`, `--clean` | First deletes vim2bat's cache and the whole bat themes folder |
+| `-s`, `--strict` | Maps only Vim's standard highlight groups, such as `Comment` and `String` |
+| `-t`, `--truecolor` | Turns on `termguicolors`, so the themes use the scheme's 24-bit colors |
+| `-p`, `--palette 16\|256` | Overrides your vimrc's `t_Co` |
+
+vim2bat rebuilds bat's cache when it finishes, so the themes are available right
+away.
+
+### Theme names
+
+A scheme that supports both backgrounds gets `vim-SCHEME-dark` and
+`vim-SCHEME-light`. A scheme that supports a single background, by setting
+`background` itself, gets `vim-SCHEME`.
+
+### What decides the colors
+
+Vim runs with your vimrc in a 256-color terminal, so your vimrc decides what the
+themes look like: a scheme's own options (such as `g:solarized_use16`), `t_Co`
+and `termguicolors` all apply. `-p` and `-t` override `t_Co` and
+`termguicolors` for one run. Each theme records the options it was built with in
+its `comment` entry. `-p` has no effect while `termguicolors` is on, whether
+from `-t` or your vimrc.
+
+With `-t`, bat prints the exact colors only when `COLORTERM` is `truecolor` or
+`24bit`. Otherwise it rounds them to the nearest of 256.
+
+## Using the themes
+
+### bat
+
+Add these lines to bat's config file, whose path `bat --config-file` prints:
+
+```
+--theme-dark="vim-retrobox-dark"
+--theme-light="vim-retrobox-light"
+--italic-text=always
+```
+
+bat's default, `--theme=auto`, picks between them by asking the terminal for its
+background. It doesn't ask when its output goes to a pipe, as in fzf.vim's
+previews, and then uses its own default theme. On macOS, `--theme="auto:system"`
+follows the system appearance instead, and works in pipes too.
+
+bat leaves out italics unless `--italic-text` is `always`.
+
+### delta
+
+delta takes a single syntax theme:
+
+```ini
+[delta]
+    syntax-theme = vim-retrobox-dark
+```
+
+On macOS, git's pager command can pick the theme from the system appearance:
+
+```ini
+[core]
+    pager = delta --syntax-theme=vim-retrobox-$(defaults read -g AppleInterfaceStyle 2>/dev/null | grep -qx Dark && echo dark || echo light)
+```
+
+## Measuring a theme
+
+`vim2bat compare THEME FILE...` reports how often the theme gives each
+character the color Vim does, per file and per language, then the most common
+mismatches:
+
+```bash
+vim2bat compare vim-retrobox-dark app/models/*.rb
+```
+
+Expect 85 to 90 percent on real code in the languages Table 3 covers (see
+below): bat's syntax definitions don't split code exactly the way Vim's do.
+Other languages get only Table 2 and score lower.
+
+## How it works
+
+1. For each background, vim2bat runs Vim with your vimrc on a pseudo-terminal,
+   loads the scheme, and records each highlight group's colors and attributes
+   (Table 1, cached in `$XDG_CACHE_HOME/vim2bat/tables`, or
+   `~/.cache/vim2bat/tables`). Vim gets a terminal because
+   without one it numbers named colors such as `DarkBlue` differently.
+2. `src/vim2bat/share/strict.tsv` (Table 2) maps Vim's standard groups, such
+   as `Comment` and `String`, to the TextMate scopes with the same meaning.
+3. `src/vim2bat/share/loose.tsv` (Table 3) maps language-specific scopes to the
+   Vim syntax groups that Vim gives the same tokens, for Ruby, ERB, HTML, CSS
+   and SCSS, TypeScript and TSX, JavaScript and JSX, YAML, Vim script, git
+   commit messages and diffs. The languages and tokens follow what
+   vim-solarized8 colors.
+4. Palette colors use bat's palette notation, where `#0E000000` means slot 14,
+   and the terminal's default color is `#00000001`.
+
+## Known limits
+
+- bat doesn't paint a scheme's background color, so a scheme with its own
+  background, such as habamax, sits on your terminal's.
+- bat themes support only bold, italic and underline, so reverse and undercurl
+  are dropped.
+- `-c` deletes the whole bat themes folder, including themes vim2bat didn't
+  build.
+- A single-background scheme whose own name ends in `-dark` or `-light` gets a
+  name that looks like another scheme's background variant.
+- Colorschemes in a subfolder of `colors/`, whose names contain `/`, aren't
+  supported. vim2bat rejects those names.
+
+## Uninstall
+
+```bash
+brew uninstall vim2bat   # or: uv tool uninstall vim2bat, or pipx uninstall vim2bat
+rm "$(bat --config-dir)"/themes/vim-*.tmTheme && (cd / && bat cache --build)
+rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/vim2bat"
+```
+
+## Development
+
+Development uses [uv](https://docs.astral.sh/uv/) (`brew install uv`).
+
+```bash
+git clone https://github.com/redodson01/vim2bat.git
+cd vim2bat
+uv sync                    # creates .venv with vim2bat and the dev tools
+uv run pre-commit install  # runs ruff and file checks before each commit
+uv run pytest              # unit tests, plus integration tests when vim and bat are installed
+uv run mypy                # type checks src and tests
+uv run ruff check          # lints
+uv run ruff format         # formats
+```
+
+[CONTRIBUTING.md](https://github.com/redodson01/vim2bat/blob/main/CONTRIBUTING.md)
+covers the golden files, measuring a change, the rules for the tables, and
+releasing.
+
+## License
+
+[MIT](https://github.com/redodson01/vim2bat/blob/main/LICENSE)

vim2bat-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+vim2bat/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vim2bat/__main__.py,sha256=1UwKOIuKO4tg-OJmllVm1m-JuWMPSkFBdMEm1f1HJkU,59
+vim2bat/cli.py,sha256=n_j9PKHO7tUtbIdg-ln23JAFjgwjpRXDPBnQ1DJjBWA,27725
+vim2bat/share/loose.tsv,sha256=F62TtLnNvMB4yiXMz1xpmFaLuXn6NHSm4pvaO_aHb00,7945
+vim2bat/share/strict.tsv,sha256=ik4d5ZmLy68EHirQvB8I96WkBNOWzD1YZ6AChBpsH6U,1829
+vim2bat/share/vim-groups.vim,sha256=BtplNbxbAvDYri4P4KCRMSGkqN7m4WGvsnSycWm2F7c,2381
+vim2bat/share/vim-slots.vim,sha256=SXuOtiHud2vaEX-BDA8XAHR7C0sYCrqG4KVmLmZebp8,2661
+vim2bat-0.1.0.dist-info/METADATA,sha256=gxE4NgwgTfFf4TBauOC0lKXy1AjWrymBXCh-iTepckk,8667
+vim2bat-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+vim2bat-0.1.0.dist-info/entry_points.txt,sha256=L0E9B0oCMWjAb1bZqt-pzqknvwM_N3BpHwC_eYdabVc,45
+vim2bat-0.1.0.dist-info/licenses/LICENSE,sha256=sCNhPkNLzVVbaoxdKKVGk_QAbxxx4YDrNfX_7vQGFis,1074
+vim2bat-0.1.0.dist-info/RECORD,,

vim2bat-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vim2bat-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vim2bat = vim2bat.cli:main

vim2bat-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard E. Dodson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.