fzf-gnat 0.1.1__tar.gz

fzf_gnat-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include packaging/build_deb.py
+recursive-include tests *.py

fzf_gnat-0.1.1/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: fzf-gnat
+Version: 0.1.1
+Summary: Fuzzy search Ada sources by unit name and krunched file name
+Author-email: Zakaria Fadli <zakaria1193@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-ada>=0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+
+# fzf-gnat
+
+Search Ada source trees by unit name, file name, or declaration with fzf.
+Find `Ada.Strings.Unbounded` even when GNAT names its source file `a-strunb.ads`.
+Preview the source, then open your selection in `$EDITOR`.
+
+## Examples
+
+Run these commands from an Ada source tree, or append the directory you want to search.
+
+### Find a unit by its Ada name
+
+You know the unit is `Ada.Strings.Unbounded`, but its file is named `a-strunb.ads`:
+
+```bash
+fzf-gnat -q Ada.Strings.Unbounded
+```
+
+The list shows the unit name beside the file name, so either spelling works:
+
+```bash
+fzf-gnat -q strunb
+```
+
+### Find a declaration without knowing its file
+
+Search for `Append` in package specs:
+
+```bash
+fzf-gnat -ss -q Ada.Strings.Unbounded.Append
+```
+
+Preview each declaration, then press Enter to open it in your editor.
+The editor starts at the declaration when it supports line arguments.
+Use `-s` instead of `-ss` to include declarations in package bodies.
+
+### Find local declarations
+
+Include local variables and nested subprograms when searching for a name such as `Count`:
+
+```bash
+fzf-gnat -sa -q Count
+```
+
+### Search another source tree
+
+Pass a directory to search without changing your working directory:
+
+```bash
+fzf-gnat -ss -q Ada.Strings.Unbounded.Append ~/work/toolchain/gnat
+```
+
+## Install
+
+Requires Python 3.10 or later and `fzf` on your `PATH`.
+On Debian or Ubuntu, install fzf with:
+
+```bash
+sudo apt install fzf
+```
+
+After the first PyPI release, install with pip:
+
+```bash
+pip install fzf-gnat
+```
+
+Or use pipx:
+
+```bash
+pipx install fzf-gnat
+```
+
+For a local checkout, use `pip install .` or `pipx install .`.
+Install `bat` for syntax highlighting in the preview. Without it, the preview uses `cat`.
+
+## Search files
+
+```bash
+fzf-gnat ~/work/toolchain/gnat
+```
+
+Each row shows the file name, its kind (spec, body, or subunit), the unit name, and the path.
+Search any field, for example `strunb` or `Strings.Unb`.
+Press Enter to open a file in `$EDITOR`. The default editor is `vi`.
+Press Tab to select several files.
+
+The first run parses the source tree with tree-sitter-ada.
+Later runs parse only files that changed.
+Use `--rebuild` to parse everything again.
+Use `--print` to print the index without fzf.
+Use `-v` to show warnings.
+A file that contains only `pragma No_Body;` has no unit and shows as `?`.
+
+## Search declarations
+
+```bash
+fzf-gnat -s  ~/work/toolchain/gnat
+fzf-gnat -ss ~/work/toolchain/gnat
+fzf-gnat -sa ~/work/toolchain/gnat
+```
+
+* `-s` searches package-level declarations in specs and bodies.
+* `-ss` searches package-level declarations in specs only.
+* `-sa` searches every declaration, including local declarations.
+
+Each row shows the qualified name, kind, unit, and file.
+Press Enter to open the editor at the declaration when the editor supports line arguments.
+Use `-q TEXT` to start fzf with an initial query.
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev,release]'
+.venv/bin/python -m pytest
+.venv/bin/python -m build
+.venv/bin/python -m twine check --strict dist/*.whl dist/*.tar.gz
+```
+
+The build produces a source archive and a wheel in `dist/`.
+
+## Publish to PyPI
+
+The GitHub Actions workflow `.github/workflows/publish.yml` tests pushes and pull requests on Python 3.10, 3.12, and 3.14.
+It builds and checks both distributions after the tests pass.
+It tests the installed wheel and checks installation with pipx before publication.
+A manual workflow run builds artifacts without publishing.
+A published GitHub release publishes to PyPI unless GitHub marks it as a prerelease.
+
+Before the first release:
+
+1. Host this repository on GitHub.
+2. Sign in to the PyPI account associated with `zakaria1193@gmail.com`.
+3. Register a pending trusted publisher for `fzf-gnat` on PyPI.
+4. Enter the GitHub owner, repository name, workflow filename `publish.yml`, and environment name `pypi`.
+5. Create the `pypi` environment in the GitHub repository.
+
+See the [PyPI trusted publisher instructions](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+This method does not require a stored PyPI API token.
+The author email in the package metadata does not authenticate uploads.
+
+For each release, update `version` in `pyproject.toml` and publish a matching GitHub release.
+For version `0.1.0`, use the tag `v0.1.0`.
+PyPI does not permit replacement of an existing release file.

fzf_gnat-0.1.1/README.md

@@ -0,0 +1,145 @@
+# fzf-gnat
+
+Search Ada source trees by unit name, file name, or declaration with fzf.
+Find `Ada.Strings.Unbounded` even when GNAT names its source file `a-strunb.ads`.
+Preview the source, then open your selection in `$EDITOR`.
+
+## Examples
+
+Run these commands from an Ada source tree, or append the directory you want to search.
+
+### Find a unit by its Ada name
+
+You know the unit is `Ada.Strings.Unbounded`, but its file is named `a-strunb.ads`:
+
+```bash
+fzf-gnat -q Ada.Strings.Unbounded
+```
+
+The list shows the unit name beside the file name, so either spelling works:
+
+```bash
+fzf-gnat -q strunb
+```
+
+### Find a declaration without knowing its file
+
+Search for `Append` in package specs:
+
+```bash
+fzf-gnat -ss -q Ada.Strings.Unbounded.Append
+```
+
+Preview each declaration, then press Enter to open it in your editor.
+The editor starts at the declaration when it supports line arguments.
+Use `-s` instead of `-ss` to include declarations in package bodies.
+
+### Find local declarations
+
+Include local variables and nested subprograms when searching for a name such as `Count`:
+
+```bash
+fzf-gnat -sa -q Count
+```
+
+### Search another source tree
+
+Pass a directory to search without changing your working directory:
+
+```bash
+fzf-gnat -ss -q Ada.Strings.Unbounded.Append ~/work/toolchain/gnat
+```
+
+## Install
+
+Requires Python 3.10 or later and `fzf` on your `PATH`.
+On Debian or Ubuntu, install fzf with:
+
+```bash
+sudo apt install fzf
+```
+
+After the first PyPI release, install with pip:
+
+```bash
+pip install fzf-gnat
+```
+
+Or use pipx:
+
+```bash
+pipx install fzf-gnat
+```
+
+For a local checkout, use `pip install .` or `pipx install .`.
+Install `bat` for syntax highlighting in the preview. Without it, the preview uses `cat`.
+
+## Search files
+
+```bash
+fzf-gnat ~/work/toolchain/gnat
+```
+
+Each row shows the file name, its kind (spec, body, or subunit), the unit name, and the path.
+Search any field, for example `strunb` or `Strings.Unb`.
+Press Enter to open a file in `$EDITOR`. The default editor is `vi`.
+Press Tab to select several files.
+
+The first run parses the source tree with tree-sitter-ada.
+Later runs parse only files that changed.
+Use `--rebuild` to parse everything again.
+Use `--print` to print the index without fzf.
+Use `-v` to show warnings.
+A file that contains only `pragma No_Body;` has no unit and shows as `?`.
+
+## Search declarations
+
+```bash
+fzf-gnat -s  ~/work/toolchain/gnat
+fzf-gnat -ss ~/work/toolchain/gnat
+fzf-gnat -sa ~/work/toolchain/gnat
+```
+
+* `-s` searches package-level declarations in specs and bodies.
+* `-ss` searches package-level declarations in specs only.
+* `-sa` searches every declaration, including local declarations.
+
+Each row shows the qualified name, kind, unit, and file.
+Press Enter to open the editor at the declaration when the editor supports line arguments.
+Use `-q TEXT` to start fzf with an initial query.
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev,release]'
+.venv/bin/python -m pytest
+.venv/bin/python -m build
+.venv/bin/python -m twine check --strict dist/*.whl dist/*.tar.gz
+```
+
+The build produces a source archive and a wheel in `dist/`.
+
+## Publish to PyPI
+
+The GitHub Actions workflow `.github/workflows/publish.yml` tests pushes and pull requests on Python 3.10, 3.12, and 3.14.
+It builds and checks both distributions after the tests pass.
+It tests the installed wheel and checks installation with pipx before publication.
+A manual workflow run builds artifacts without publishing.
+A published GitHub release publishes to PyPI unless GitHub marks it as a prerelease.
+
+Before the first release:
+
+1. Host this repository on GitHub.
+2. Sign in to the PyPI account associated with `zakaria1193@gmail.com`.
+3. Register a pending trusted publisher for `fzf-gnat` on PyPI.
+4. Enter the GitHub owner, repository name, workflow filename `publish.yml`, and environment name `pypi`.
+5. Create the `pypi` environment in the GitHub repository.
+
+See the [PyPI trusted publisher instructions](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+This method does not require a stored PyPI API token.
+The author email in the package metadata does not authenticate uploads.
+
+For each release, update `version` in `pyproject.toml` and publish a matching GitHub release.
+For version `0.1.0`, use the tag `v0.1.0`.
+PyPI does not permit replacement of an existing release file.

fzf_gnat-0.1.1/packaging/build_deb.py

@@ -0,0 +1,70 @@
+"""Build a Debian archive with private Python dependencies for the current interpreter."""
+
+import argparse
+from email.parser import BytesParser
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+ROOT = Path(__file__).resolve().parents[1]
+NAME = "fzf-gnat"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, default=ROOT / "dist")
+    args = parser.parse_args()
+    args.output.mkdir(parents=True, exist_ok=True)
+    architecture = subprocess.check_output(["dpkg", "--print-architecture"], text=True).strip()
+    python = f"python{sys.version_info.major}.{sys.version_info.minor}"
+    with tempfile.TemporaryDirectory(prefix=f"{NAME}-") as temp:
+        stage = Path(temp) / "package"
+        library = stage / "usr/lib" / NAME
+        subprocess.run(
+            [sys.executable, "-m", "pip", "install", "--no-compile", "--target", str(library), str(ROOT)],
+            check=True,
+        )
+        shutil.rmtree(library / "bin", ignore_errors=True)
+        metadata = BytesParser().parsebytes(
+            next(library.glob("fzf_gnat-*.dist-info/METADATA")).read_bytes()
+        )
+        version = metadata["Version"]
+        binary = stage / "usr/bin" / NAME
+        binary.parent.mkdir(parents=True)
+        binary.write_text(
+            f"#!/usr/bin/{python} -I\n"
+            "import sys\n"
+            "from pathlib import Path\n"
+            f"sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'lib/{NAME}'))\n"
+            "from fzf_gnat.cli import main\n"
+            "sys.exit(main())\n"
+        )
+        binary.chmod(0o755)
+        documentation = stage / "usr/share/doc" / NAME
+        documentation.mkdir(parents=True)
+        shutil.copyfile(ROOT / "README.md", documentation / "README.md")
+        control = stage / "DEBIAN/control"
+        control.parent.mkdir()
+        control.write_text(
+            f"Package: {NAME}\n"
+            f"Version: {version}\n"
+            "Section: devel\n"
+            "Priority: optional\n"
+            f"Architecture: {architecture}\n"
+            "Maintainer: Zakaria Fadli <zakaria1193@gmail.com>\n"
+            f"Depends: {python}, libc6, fzf\n"
+            "Recommends: bat\n"
+            "Description: Fuzzy search Ada sources by unit name and declaration\n"
+            " Search GNAT source trees by unit name, shortened file name, or declaration.\n"
+            " Python parser dependencies are included in a private directory.\n"
+        )
+        archive = args.output.resolve() / f"{NAME}_{version}_{architecture}.deb"
+        subprocess.run(["dpkg-deb", "--root-owner-group", "--build", str(stage), str(archive)], check=True)
+        print(archive)
+
+
+if __name__ == "__main__":
+    main()

fzf_gnat-0.1.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fzf-gnat"
+version = "0.1.1"
+description = "Fuzzy search Ada sources by unit name and krunched file name"
+readme = "README.md"
+authors = [{name = "Zakaria Fadli", email = "zakaria1193@gmail.com"}]
+requires-python = ">=3.10"
+dependencies = ["tree-sitter>=0.23", "tree-sitter-ada>=0.1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+release = ["build>=1", "twine>=6"]
+
+[project.scripts]
+fzf-gnat = "fzf_gnat.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

fzf_gnat-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fzf_gnat-0.1.1/src/fzf_gnat/__init__.py

@@ -0,0 +1 @@
+"""Fuzzy search an Ada tree by unit name and krunched file name; start at ``cli.main``."""

fzf_gnat-0.1.1/src/fzf_gnat/cli.py

@@ -0,0 +1,220 @@
+"""The ``fzf-gnat`` command."""
+
+import argparse
+import logging
+import os
+import shlex
+import shutil
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+from fzf_gnat.index import Entry, SymbolEntry, build_index, build_symbol_index
+
+
+class ProgressBar:
+    """Draw a one-line progress bar on a terminal, and erase it when done."""
+
+    def __init__(self, out, width: int = 40):
+        self.out = out
+        self.width = width
+
+    def __call__(self, done: int, total: int) -> None:
+        filled = self.width * done // total
+        bar = "#" * filled + " " * (self.width - filled)
+        self.out.write(f"\r[{bar}] {done:4}/{total} ")
+        if done == total:
+            self.out.write("\r\x1b[K")
+        self.out.flush()
+
+
+DEFAULT_COLUMNS = 120
+
+# fzf's pointer and marker take two columns on the left, its scrollbar one on
+# the right.
+FZF_GUTTER = 3
+
+MIN_PATH_WIDTH = 20
+
+
+def shorten(path: str, width: int) -> str:
+    """Return ``path``, cut in the middle with ``...`` if it is longer than ``width``."""
+    if len(path) <= width:
+        return path
+    # Keep more of the end, which holds the directory and file names.
+    keep = width - 3
+    head = keep // 3
+    return f"{path[:head]}...{path[len(path) - (keep - head):]}"
+
+
+def _columns(rows: list[tuple[str, str, str, Path, int]], columns: int) -> list[str]:
+    # The first three columns take their longest value and the shown path
+    # gets what is left of the line. The full path and the line follow,
+    # hidden, for the preview and the editor. fzf runs with --tabstop 1, so
+    # each tab shows as one space.
+    widths = [max((len(row[i]) for row in rows), default=0) for i in range(3)]
+    path_width = max(MIN_PATH_WIDTH, columns - FZF_GUTTER - sum(widths) - 3)
+    return [
+        f"{a:<{widths[0]}}\t{b:<{widths[1]}}\t{c:<{widths[2]}}\t"
+        f"{shorten(str(path), path_width):<{path_width}}\t{path}\t{line}"
+        for a, b, c, path, line in rows
+    ]
+
+
+def format_lines(entries: list[Entry], root: Path, columns: int = DEFAULT_COLUMNS) -> list[str]:
+    """Return one fzf line per entry, ``columns`` wide: file name, kind, unit and shortened path, then the hidden full path and unit line."""
+    return _columns(
+        [(Path(e.relpath).name, e.kind, e.unit, root / e.relpath, e.line) for e in entries],
+        columns,
+    )
+
+
+def format_symbol_lines(
+    entries: list[SymbolEntry], root: Path, columns: int = DEFAULT_COLUMNS
+) -> list[str]:
+    """Return one fzf line per symbol, ``columns`` wide: name, kind, unit and shortened path, then the hidden full path and line."""
+    return _columns(
+        [(e.name, e.kind, e.unit, root / e.relpath, e.line) for e in entries],
+        columns,
+    )
+
+
+def preview_command() -> str:
+    """Return the fzf preview command, using bat when it is installed."""
+    # Debian and Ubuntu install bat as batcat.
+    for bat in ("bat", "batcat"):
+        if shutil.which(bat):
+            return f"{bat} --color=always --style=numbers {{5}} --highlight-line {{6}}"
+    return "cat {5}"
+
+
+def fzf_argv(preview: str, query: str = "") -> list[str]:
+    return [
+        "fzf",
+        "--multi",
+        "--delimiter", "\t",
+        "--tabstop", "1",
+        "--preview", preview,
+        # Fields 5 and 6, the full path and the line, stay hidden; the line
+        # centres the preview.
+        "--with-nth", "1..4",
+        "--preview-window", "up,60%,+{6}/2",
+        "--query", query,
+    ]
+
+
+# Editors that take +LINE before a file. With several files, it applies to
+# the first one only.
+_PLUS_LINE_EDITORS = {"vi", "vim", "nvim", "gvim", "view", "nano", "emacs", "emacsclient", "micro"}
+_GOTO_EDITORS = {"code", "codium"}
+
+
+def editor_argv(files: list[tuple[str, int]]) -> list[str]:
+    """Return the $EDITOR command that opens ``files``, at the given line of the first one when the editor supports it."""
+    editor = shlex.split(os.environ.get("EDITOR") or "vi")
+    name = os.path.basename(editor[0])
+    (first, line), rest = files[0], [path for path, _ in files[1:]]
+    if name in _PLUS_LINE_EDITORS:
+        return [*editor, f"+{line}", first, *rest]
+    if name in _GOTO_EDITORS:
+        return [*editor, "-g", f"{first}:{line}", *rest]
+    return [*editor, first, *rest]
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Python keeps SIGINT ignored when the parent ignored it, which leaves
+    # Ctrl-C dead during a long parse.
+    signal.signal(signal.SIGINT, signal.default_int_handler)
+    try:
+        return _main(argv)
+    except KeyboardInterrupt:
+        if sys.stderr.isatty():
+            sys.stderr.write("\r\x1b[K")
+        return 130
+
+
+def _main(argv: list[str] | None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="fzf-gnat",
+        description="Fuzzy search Ada sources by unit name and krunched file name, or by declaration.",
+    )
+    parser.add_argument("root", nargs="?", default=".", help="tree to search (default: .)")
+    parser.add_argument("--rebuild", action="store_true", help="ignore the cache")
+    parser.add_argument("--print", action="store_true", help="print the index, do not run fzf")
+    parser.add_argument("-v", "--verbose", action="store_true", help="show warnings")
+    parser.add_argument("-q", "--query", default="", help="start fzf with this query")
+    symbols = parser.add_mutually_exclusive_group()
+    symbols.add_argument(
+        "-s", dest="symbols", action="store_const", const="package",
+        help="search declarations at package level instead of files",
+    )
+    symbols.add_argument(
+        "-ss", dest="symbols", action="store_const", const="spec",
+        help="search declarations at package level in specs only",
+    )
+    symbols.add_argument(
+        "-sa", dest="symbols", action="store_const", const="all",
+        help="search all declarations, including locals",
+    )
+    args = parser.parse_args(argv)
+    tty = sys.stderr.isatty()
+    # On a terminal, a warning first erases the progress bar it would
+    # otherwise be printed over.
+    erase = "\r\x1b[K" if tty else ""
+    logging.basicConfig(
+        level=logging.WARNING if args.verbose else logging.ERROR,
+        format=f"{erase}fzf-gnat: %(message)s",
+        force=True,
+    )
+
+    root = Path(args.root).resolve()
+    if not root.is_dir():
+        print(f"fzf-gnat: {args.root}: not a directory", file=sys.stderr)
+        return 2
+    if not args.print and not shutil.which("fzf"):
+        print("fzf-gnat: fzf not found on PATH", file=sys.stderr)
+        return 2
+
+    progress = ProgressBar(sys.stderr) if tty else None
+    columns = os.get_terminal_size(sys.stderr.fileno()).columns if tty else DEFAULT_COLUMNS
+    if args.symbols:
+        found = build_symbol_index(
+            root, local=args.symbols == "all", rebuild=args.rebuild, progress=progress
+        )
+        if args.symbols == "spec":
+            found = [e for e in found if e.relpath.endswith(".ads")]
+        formatted = format_symbol_lines(found, root, columns)
+    else:
+        entries = build_index(root, rebuild=args.rebuild, progress=progress)
+        formatted = format_lines(entries, root, columns)
+    lines = "".join(f"{line}\n" for line in formatted)
+    if args.print:
+        try:
+            sys.stdout.write(lines)
+            sys.stdout.flush()
+        except BrokenPipeError:
+            # The reader quit early, as `head` does. Point stdout at devnull
+            # so that the flush at interpreter exit does not fail again.
+            os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 0
+
+    result = subprocess.run(
+        fzf_argv(preview_command(), args.query), input=lines, stdout=subprocess.PIPE, text=True, cwd=root
+    )
+    if result.returncode != 0:
+        return 0
+    selected = [
+        (fields[4], int(fields[5]))
+        for fields in (line.split("\t") for line in result.stdout.splitlines())
+        if len(fields) == 6
+    ]
+    if not selected:
+        return 0
+    editor = editor_argv(selected)
+    try:
+        subprocess.run(editor)
+    except FileNotFoundError:
+        print(f"fzf-gnat: editor not found: {editor[0]}", file=sys.stderr)
+        return 2
+    return 0