offgrep 0.0.2__tar.gz → 0.1.0__tar.gz

{offgrep-0.0.2 → offgrep-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: offgrep
-Version: 0.0.2
+Version: 0.1.0
 Summary: A lousy ripgrep rip-off in pure Python
 Keywords: grep,recursive
 Author: Rainer Schwarzbach
@@ -40,6 +40,7 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Requires-Python: >=3.11
 Project-URL: Homepage, https://gitlab.com/blackstream-x/offgrep
+Project-URL: Changelog, https://gitlab.com/blackstream-x/offgrep/-/blob/main/CHANGELOG.md
 Project-URL: CI, https://gitlab.com/blackstream-x/offgrep/-/pipelines
 Project-URL: Bug Tracker, https://gitlab.com/blackstream-x/offgrep/-/issues
 Project-URL: Repository, https://gitlab.com/blackstream-x/offgrep.git

{offgrep-0.0.2 → offgrep-0.1.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "uv_build"
 
 [project]
 name = "offgrep"
-version = "0.0.2"
+version = "0.1.0"
 description = "A lousy ripgrep rip-off in pure Python"
 readme = "README.md"
 authors = [
@@ -43,6 +43,7 @@ og = "offgrep.__main__:main"
 
 [project.urls]
 Homepage = "https://gitlab.com/blackstream-x/offgrep"
+Changelog = "https://gitlab.com/blackstream-x/offgrep/-/blob/main/CHANGELOG.md"
 CI = "https://gitlab.com/blackstream-x/offgrep/-/pipelines"
 "Bug Tracker" = "https://gitlab.com/blackstream-x/offgrep/-/issues"
 Repository = "https://gitlab.com/blackstream-x/offgrep.git"

offgrep-0.1.0/src/offgrep/__main__.py

@@ -0,0 +1,228 @@
+# -*- coding: utf-8 -*-
+
+"""
+Call as script
+"""
+
+import sys
+
+from argparse import ArgumentParser, Namespace, REMAINDER
+from importlib.metadata import PackageNotFoundError, version as metadata_version
+from logging import DEBUG, WARNING, basicConfig, debug, error, warning
+from pathlib import Path
+from re import compile as re_compile
+from tomllib import loads as tomli_loads
+
+from .commons import UTF_8
+from .filesystem import IgnoredDirectoryError, iter_target_files
+
+
+PACKAGE_NAME = "offgrep"
+"""The package name for metadata inspection"""
+ANSI_HI = "\x1b[1m"
+ANSI_NORMAL = "\x1b[0m"
+
+
+def get_file_contents(file_name: str, up_dirs: int = 0) -> str:
+    """get contents of a file in an ancestor directory
+    of the current file
+
+    ...
+    """
+    file_dir_path = Path(__file__).resolve()
+    for _ in range(up_dirs):
+        file_dir_path = file_dir_path.parent
+    #
+    file_path = file_dir_path / file_name
+    return file_path.read_text(encoding=UTF_8)
+
+
+def get_metadata_version(
+    metadata_file_name: str = "pyproject.toml", up_dirs: int = 3
+) -> str:
+    """get version information from _metadata_file_name_ in an ancestor directory
+
+    ...
+    """
+    try:
+        metadata_file_contents = get_file_contents(metadata_file_name, up_dirs=up_dirs)
+    except IOError as io_error:
+        return str(io_error)
+    #
+    metadata = tomli_loads(metadata_file_contents)
+    try:
+        # logging.warning(str(metadata.items()))
+        version = metadata["project"]["version"]
+    except KeyError:
+        return f"Error: no version information in metadata from {metadata_file_name}"
+    #
+    return f"{version} (read directly from {metadata_file_name})"
+
+
+def find_in_files(
+    target_paths: list[Path], pattern: str, show_files: bool = False
+) -> int:
+    """Find a regular expression in all files"""
+    compiled_re = re_compile(pattern)
+    previous_matches = 0
+    for single_file in target_paths:
+        findings: list[tuple[int, str]] = []
+        try:
+            with open(single_file, mode="rt", encoding=UTF_8) as input_file:
+                for lineno, line in enumerate(input_file, start=1):
+                    if compiled_re.search(line):
+                        findings.append((lineno, line.rstrip()))
+                    #
+                #
+            #
+        except UnicodeDecodeError as unicode_error:
+            debug("assuming binary file %s because of %r", single_file, unicode_error)
+        except OSError as os_error:
+            error(str(os_error))
+            continue
+        #
+        line_numbers = [lineno for (lineno, line) in findings]
+        if line_numbers:
+            number_width = max(len(str(max(line_numbers))), 6)
+            if show_files:
+                if previous_matches:
+                    print()
+                #
+                print(f"{ANSI_HI}{single_file} ::{ANSI_NORMAL}")
+            #
+            for lineno, line in findings:
+                print(f"{lineno:{number_width}d}: {line}")
+            #
+            previous_matches += 1
+        #
+    #
+    return previous_matches
+
+
+def grep_files(arguments: Namespace) -> int:
+    """Search for text in files"""
+    # TODO: arguments.file → read regexps from the provided file
+    pattern_and_or_paths = list(arguments.pattern_and_or_paths)
+    try:
+        pattern = pattern_and_or_paths.pop(0)
+    except IndexError:
+        error("No pattern provided")
+        return 1
+    #
+    debug("Provided pattern: %r", pattern)
+    paths = [Path(single_path) for single_path in pattern_and_or_paths]
+    if not paths:
+        paths.append(Path.cwd())
+    #
+    if not paths:
+        raise NotImplementedError("Filter functionality is planned, but …")
+    #
+    show_files = True
+    if len(paths) == 1 and paths[0].is_file():
+        show_files = False
+    #
+    target_paths = []
+    for single_path in paths:
+        if single_path.is_file():
+            debug("Omitting ignore rules for file %s", single_path)
+            target_paths.append(single_path)
+        elif single_path.is_dir():
+            try:
+                target_paths.extend(iter_target_files(single_path))
+            except IgnoredDirectoryError as id_error:
+                error(str(id_error))
+            #
+        #
+    #
+    find_in_files(target_paths, pattern, show_files=show_files)
+    return 0
+
+
+def list_files(arguments: Namespace) -> int:
+    """List files that would be searched"""
+    paths = [Path(item) for item in arguments.pattern_and_or_paths]
+    if not paths:
+        paths.append(Path.cwd())
+    #
+    for single_path in paths:
+        if single_path.is_file():
+            debug("Omitting ignore rules for file %s", single_path)
+            print(single_path)
+        elif single_path.is_dir():
+            try:
+                for target_path in iter_target_files(single_path):
+                    print(target_path)
+                #
+            except IgnoredDirectoryError as id_error:
+                error(str(id_error))
+            #
+        else:
+            warning("Ingored %s, neither a regular file nor a directory", single_path)
+        #
+    #
+    return 0
+
+
+# pylint: enable=unused-argument
+
+
+def get_arguments() -> Namespace:
+    """Parse commandline arguments and configure logging
+
+    Returns:
+        the parsed command line arguments
+    """
+    try:
+        version = metadata_version(PACKAGE_NAME)
+    except PackageNotFoundError:
+        version = get_metadata_version()
+    #
+    main_parser = ArgumentParser(
+        prog="offgrep", description="searches text in (text) files recursively"
+    )
+    main_parser.set_defaults(loglevel=WARNING)
+    main_parser.add_argument("-V", "--version", action="version", version=version)
+    main_parser.add_argument(
+        "--debug",
+        action="store_const",
+        const=DEBUG,
+        dest="loglevel",
+        help="log with debug level",
+    )
+    main_parser.add_argument(
+        "--files",
+        action="store_true",
+        help="print each file that would be searched without actually"
+        " performing the search.",
+    )
+    main_parser.add_argument(
+        "pattern_and_or_paths",
+        nargs=REMAINDER,
+        metavar="Pattern and/or path(s)",
+        help="Exact usage depends on the other options:"
+        " No pattern with --file … or -files,"
+        " no path(s) when used as a filter."
+        " With --type-list, these argumemts are ignored completely.",
+    )
+    arguments = main_parser.parse_args()
+    basicConfig(level=arguments.loglevel)
+    return arguments
+
+
+def main() -> int:
+    """Main script interface
+
+    Returns:
+        the script rteurncode
+    """
+    arguments = get_arguments()
+    if arguments.files:
+        return list_files(arguments)
+    #
+    return grep_files(arguments)
+
+
+if __name__ == "__main__":
+    sys.exit(main())  # pragma: no cover
+
+# vim: fileencoding=utf-8 ts=4 sts=4 sw=4 autoindent expandtab syntax=python:

offgrep-0.1.0/src/offgrep/commons.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+
+"""
+Common constants and functions
+"""
+
+ASTERISK = "*"
+"""ASCII star, fnmatch wildcard"""
+
+BACKSLASH = "\\"
+"""ASCII backslash character"""
+
+CARET = "^"
+"""ASCII caret character"""
+
+CLOSING_BRACKET = "]"
+"""ASCII closing square bracket character"""
+
+CRLF = "\r\n"
+"""Carriage return and line feed characters"""
+
+DASH = "-"
+"""ASCII dash character"""
+
+EMPTY = ""
+"""Empty string"""
+
+EXCLAMATION_MARK = "!"
+"""ASCII exclamation mark character"""
+
+OPENING_BRACKET = "["
+"""ASCII opening square bracket character"""
+
+QUESTION_MARK = "?"
+"""ASCII question mark character, fnmatch wildcard for any single character"""
+
+SLASH = "/"
+"""ASCII slash character (Path segments separator)"""
+
+UTF_8 = "utf-8"
+"""Explicit default encoding"""

offgrep-0.1.0/src/offgrep/filesystem.py

@@ -0,0 +1,182 @@
+# -*- coding: utf-8 -*-
+
+"""
+Filesystem related functionality
+"""
+
+from collections.abc import Iterator
+from logging import debug
+from pathlib import Path
+
+from .git import GIT_DIR, get_configured_global_gitignore_path
+from .ignore import CompiledPattern, IgnoreFile
+
+
+GIT_IGNORE_FILE = ".gitignore"
+
+DEFAULT_IGNORE_FILES = (GIT_IGNORE_FILE,)
+
+
+class IgnoredDirectoryError(Exception):
+    """raised if a directory was explicitly excluded"""
+
+
+def load_gitignore_file(path: Path, handles: Path, description: str) -> IgnoreFile:
+    """load an ignore file"""
+    if path.is_file():
+        return IgnoreFile.from_gitignore(path, handles)
+    #
+    raise ValueError(f"{description} ignore file {path} not found")
+
+
+def iter_target_files(start_directory: Path) -> Iterator[Path]:
+    """Iterate over target files"""
+    absolute_start = start_directory.resolve()
+    debug("Compiling ignore files for directory %s …", absolute_start)
+    ignore_files = compile_ignore_files(absolute_start)
+    debug("Walking down directory %s", absolute_start)
+    yield from walk_files(absolute_start, absolute_start, ignore_files)
+
+
+# pylint: disable=too-many-locals ; refactoring candidate
+
+
+def compile_ignore_files(
+    start_directory: Path, check_git: bool = True
+) -> list[IgnoreFile]:
+    """Compile ignore files for start_directory"""
+    absolute_start = start_directory.resolve()
+    assert absolute_start.is_dir()
+    git_ignore_files: list[IgnoreFile] = []
+    if check_git:
+        dirs_to_check = [absolute_start, *absolute_start.parents]
+        checked_dirs = []
+        for pointer in dirs_to_check:
+            debug("Checking %s for %s …", pointer, GIT_DIR)
+            checked_dirs.append(pointer)
+            candidate = pointer / GIT_DIR
+            if candidate.is_dir():
+                debug("… found! Compiling ignore rules …")
+                git_ignore_files.append(
+                    IgnoreFile(
+                        handles_directory=pointer,
+                        rules=(CompiledPattern.from_gitignore_line(f"{GIT_DIR}/"),),
+                    )
+                )
+                for description, file_path in (
+                    ("user global", get_configured_global_gitignore_path()),
+                    ("repo private", candidate / "info" / "exclude"),
+                ):
+                    try:
+                        git_ignore_files.append(
+                            load_gitignore_file(file_path, pointer, description)
+                        )
+                    except (OSError, ValueError) as error:
+                        debug(str(error))
+                    #
+                #
+                break
+            #
+        else:
+            debug("No git repository found in any parent, continuing without …")
+        #
+        # walk back up and handle intermediate ignore files,
+        # except for the start directory itself (that is done when walking it)
+        if git_ignore_files:
+            for idx in range(len(checked_dirs) - 1, 0, -1):
+                current_dir = checked_dirs[idx]
+                try:
+                    intermediate_ignore_file = load_gitignore_file(
+                        current_dir / GIT_IGNORE_FILE,
+                        current_dir,
+                        "intermediate",
+                    )
+                except (OSError, ValueError) as error:
+                    debug(str(error))
+                else:
+                    git_ignore_files.append(intermediate_ignore_file)
+                #
+                dir_to_check = checked_dirs[idx - 1]
+                is_excluded = False
+                for current_ignore_file in git_ignore_files:
+                    is_excluded = current_ignore_file.excludes_path(
+                        dir_to_check, pre_excluded=is_excluded
+                    )
+                #
+                if is_excluded:
+                    raise IgnoredDirectoryError(
+                        f"gitignore config excludes directory {dir_to_check},"
+                        " cannot continue"
+                    )
+                #
+            #
+        #
+    #
+    return git_ignore_files
+
+
+def walk_files(
+    start_directory: Path,
+    working_directory: Path,
+    ignore_files: list[IgnoreFile],
+    use_ignore_files: tuple[str, ...] = DEFAULT_IGNORE_FILES,
+) -> Iterator[Path]:
+    """Walk through all contained files, respecting the ignore rules.
+
+    Yield paths relative to the start directory if the start directory
+    is the current working directory.
+    """
+    assert start_directory.is_absolute()
+    use_relative_paths = False
+    cwd = Path.cwd()
+    anchor_directory = cwd
+    if start_directory.is_relative_to(Path.cwd()):
+        use_relative_paths = True
+    #
+    absolute_workdir = working_directory.resolve()
+    effective_ignore_files = list(ignore_files)
+    for ignore_file_candidate in use_ignore_files:
+        try:
+            effective_ignore_files.append(
+                load_gitignore_file(
+                    absolute_workdir / ignore_file_candidate,
+                    absolute_workdir,
+                    "Directory level",
+                )
+            )
+        except (OSError, ValueError) as error:
+            debug(str(error))
+        #
+    #
+    for contained_path in sorted(absolute_workdir.glob("*"), key=Path.as_posix):
+        # name = contained_path.name
+        if not (contained_path.is_dir() or contained_path.is_file()):
+            debug("Skipping %s, not a directory or regular file", contained_path)
+            continue
+        #
+        is_excluded = False
+        for current_ignore_file in effective_ignore_files:
+            is_excluded = current_ignore_file.excludes_path(
+                contained_path, pre_excluded=is_excluded
+            )
+        #
+        if is_excluded:
+            continue
+        #
+        if contained_path.is_file():
+            if use_relative_paths:
+                yield contained_path.relative_to(anchor_directory)
+            else:
+                yield contained_path
+            #
+        #
+        if contained_path.is_dir():
+            debug("Descending into directory %s", contained_path.name)
+            yield from walk_files(
+                start_directory,
+                contained_path,
+                effective_ignore_files,
+                use_ignore_files=use_ignore_files,
+            )
+        #
+    #

offgrep-0.1.0/src/offgrep/git.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+
+"""
+Git related functionality
+"""
+
+from configparser import ConfigParser, NoOptionError, NoSectionError
+from os import getenv
+from pathlib import Path
+# from subprocess import PIPE, run as sp_run
+
+
+GIT_COMMAND = "git"
+"""The git command"""
+
+GIT_DIR = ".git"
+"""The git directory in workspaces"""
+
+USER_HOME_PATH = Path.home()
+"""The user’s home directory"""
+
+
+def get_configured_global_gitignore_path() -> Path:
+    """The user’s configured global gitignore path,
+    falling back to the default if there is no special configuration
+
+    Returns:
+        the configured (**.gitconfig** option `core.excludesFile`) or default
+            (`${XDG_CONFIG_HOME:-$HOME/.config}/git/ignore`)
+            global gitignore file path of the user
+    """
+    try:
+        return Path(get_git_config_value("core.excludesFile"))
+    except (NoSectionError, NoOptionError):
+        return get_user_default_global_gitignore_path()
+    #
+
+
+def get_git_config_value(compound_key: str) -> str:
+    """Value of a Git config item from the user’s `~/.gitconfig` file
+
+    Args:
+        compound_key: the compound config key, eg. user.name
+
+    Returns:
+        the value of the option
+
+    Raises:
+        NoSectionError: if the `~/.gitconfig` file does not exist or
+            dos not contain the required section
+        NoOptionError: if the required option does not exist
+            in the config file section
+    """
+    user_gitconfig_path = USER_HOME_PATH / ".gitconfig"
+    config = ConfigParser()
+    config.read([str(user_gitconfig_path)])
+    return config.get(*compound_key.split("."))
+
+
+def get_user_default_global_gitignore_path() -> Path:
+    """The user’s default global gitignore path:
+    `${XDG_CONFIG_HOME:-$HOME/.config}/git/ignore`
+
+    Returns:
+        the absolute path of the user’s global gitignore file
+    """
+    git_ignore_subpath = Path("git/ignore")
+    xdg_config_home = getenv("XDG_CONFIG_HOME")
+    if isinstance(xdg_config_home, str):
+        return Path(xdg_config_home) / git_ignore_subpath
+    #
+    return USER_HOME_PATH / ".config" / git_ignore_subpath

offgrep-0.1.0/src/offgrep/ignore.py

@@ -0,0 +1,506 @@
+# -*- coding: utf-8 -*-
+
+"""
+Ignore (gitignore, tba: hgignore) implementation
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from functools import lru_cache
+from logging import debug, warning
+from os.path import normcase
+from pathlib import Path
+from re import compile as re_compile, escape
+from typing import Self
+
+from .commons import (
+    ASTERISK,
+    BACKSLASH,
+    CARET,
+    CLOSING_BRACKET,
+    CRLF,
+    DASH,
+    EMPTY,
+    EXCLAMATION_MARK,
+    OPENING_BRACKET,
+    QUESTION_MARK,
+    SLASH,
+    UTF_8,
+)
+
+
+CRE_SETOPS = re_compile(r"([&~|])")
+"""Precompiled regular expression matching a single
+ampersand, tilde or pipe character
+"""
+
+RE_ESCAPE = lru_cache(maxsize=512)(escape)
+"""LRU cached version of the
+[re.escape()](https://docs.python.org/3/library/re.html#re.escape)
+function
+´"""
+
+RX_NO_SLASH = "[^/]"
+"""Regular expression pattern excluding a slash"""
+
+RX_END_DELIMITED_PATH_SEGMENT = f"(?:{RX_NO_SLASH}+/)"
+"""Regular expression pattern matching one or more non-slash characters,
+followed by a slash.
+Suitable for matching relative path segments.
+"""
+
+
+class Style(StrEnum):
+    """Ignore style"""
+
+    GITIGNORE = "gitignore"
+    """Git style ignore entry"""
+
+    GLOB = "glob"
+    """Mercurial ignore entry, non-anchored glob style"""
+
+    ROOTGLOB = "rootglob"
+    """Mercurial ignore entry, anchored glob style"""
+
+    REGEX = "regex"
+    """Mercurial ignore entry, regex style"""
+
+
+class CompiledPattern:
+    """Pattern to match relative file paths"""
+
+    def __init__(
+        self, regex_pattern: str, negated: bool = False, use_normcase: bool = True
+    ) -> None:
+        """compile the RE pattern
+
+        Args:
+            regex_pattern: the regular expression pattern
+            negated: Flag indicating whether the pattern excludes (`False`)
+                or re-includes a previously excluded path (`True`)
+            use_normcase: Flag indicating whether to normalize the pattern
+                and the relative paths according to the operating system
+                defaults (`True`), or to always match case sensitive (`False`)
+        """
+        self.negated = negated
+        self.regex_pattern = normcase(regex_pattern) if use_normcase else regex_pattern
+        self.use_normcase = use_normcase
+        self._cre = re_compile(regex_pattern)
+
+    def matches(self, relative_path: str) -> bool:
+        """Indicate if the pattern matches the relative path
+
+        Args:
+            relative_path: the relative path to match
+
+        Returns:
+            `True` if the path matches the pattern, `False` if not
+        """
+        if self.use_normcase:
+            relative_path = normcase(relative_path)
+        #
+        return self._cre.match(relative_path) is not None
+
+    @classmethod
+    def from_gitignore_line(
+        cls, gitignore_line: str, use_normcase: bool = True
+    ) -> Self:
+        """Factory method: compiled pattern from a `.gitignore` entry
+
+        Args:
+            gitignore_line: a line from a `.gitignore` file
+                (or `$GIT_DIR/info/exclude`, or the file specified by the
+                `core.excludesFile` configuration directive)
+            use_normcase: Flag indicating whether to normalize the pattern
+                and the relative paths according to the operating system
+                defaults (`True`), or to always match case sensitive (`False`)
+
+        Returns:
+            a new instance
+
+        Raises:
+            ValueError: if the line ends in a single backslash
+        """
+        gitignore_line = gitignore_line.rstrip(CRLF)
+        if gitignore_line.endswith(BACKSLASH) and not gitignore_line[:-1].endswith(
+            BACKSLASH
+        ):
+            raise ValueError("Lines ending in a single backslash are not allowed")
+        #
+        _negated = False
+        if gitignore_line.startswith("!"):
+            _negated = True
+            gitignore_line = gitignore_line[1:]
+        #
+        return cls(
+            gitignore_pattern_to_full_regex(gitignore_line),
+            negated=_negated,
+            use_normcase=use_normcase,
+        )
+
+
+@dataclass(frozen=True)
+class IgnoreFile:
+    """Ignorefile data class"""
+
+    handles_directory: Path
+    """The handled directory"""
+
+    rules: tuple[CompiledPattern, ...]
+    """The ignore rules set"""
+
+    @classmethod
+    def from_gitignore(cls, source: Path, handles: Path) -> Self:
+        """Create an ignore file from the gitignore file"""
+        rules_collector: list[CompiledPattern] = []
+        debug("Reading gitignore file %s …", source)
+        with open(source, mode="rt", encoding=UTF_8) as gitignore_file:
+            for line in gitignore_file:
+                if line.startswith("#") or not line.strip():
+                    continue
+                #
+                try:
+                    rules_collector.append(CompiledPattern.from_gitignore_line(line))
+                except ValueError as value_error:
+                    warning(str(value_error))
+                #
+            #
+        #
+        n_rules = len(rules_collector)
+        debug("Read %s rules from %s", n_rules, source)
+        return cls(handles_directory=handles, rules=tuple(rules_collector))
+
+    def excludes_path(self, file_or_dir: Path, pre_excluded: bool = False) -> bool:
+        """Return True if the named f file or di is excluded"""
+        is_excluded = pre_excluded
+        relative_path = file_or_dir.relative_to(self.handles_directory)
+        comparable = relative_path.as_posix()
+        if relative_path.is_dir():
+            comparable = f"{comparable}/"
+        #
+        for single_rule in self.rules:
+            if single_rule.matches(comparable):
+                if is_excluded and single_rule.negated:
+                    debug(
+                        "Re-including %s because of negated %s",
+                        file_or_dir,
+                        single_rule.regex_pattern,
+                    )
+                    is_excluded = False
+                else:
+                    debug(
+                        "Excluding %s because of %s",
+                        file_or_dir,
+                        single_rule.regex_pattern,
+                    )
+                    is_excluded = True
+                #
+            #
+        #
+        return is_excluded
+
+
+def translate(pattern: str, style: Style = Style.GITIGNORE) -> str:
+    """Dispatch pattern to the appropriate translation function,
+    according to the style argument
+
+    Args:
+        pattern: the ignore pattern to translate
+        style: the ignore pattern style
+
+    Returns:
+        the translation function result, ie. the resulting regex pattern
+
+    Raises:
+        NotImplementedError: if the style is not supported
+            (… yet; currently, only GITIGNORE and REGEX are supported)
+    """
+    match style:
+        case Style.GITIGNORE:
+            return gitignore_pattern_to_full_regex(pattern)
+        case Style.REGEX:
+            return pattern
+        case _:
+            raise NotImplementedError
+        #
+    #
+
+
+def gitignore_pattern_to_full_regex(pattern: str) -> str:
+    """Translate a .gitignore pattern to a regular expression pattern
+
+    Args:
+        pattern: the gitignore pattern line (excluding a leading exclamation mark)
+
+    Returns:
+        the full regex pattern to match a file path relative to the .gitignore
+            file location
+
+    Raises:
+        ValueError: if the pattern includes consecutive slashes
+    """
+    if "//" in pattern:
+        raise ValueError(f"invalid pattern {pattern!r}")
+    #
+    if pattern == "**/**":
+        # Any file or directory, no leading slash
+        return "^[^/].*$"
+    #
+    if pattern == "**/**/":
+        return f"^{RX_END_DELIMITED_PATH_SEGMENT}+$"
+    #
+    collector = [
+        # Default Regex start: match any number of directories deep
+        f"{RX_END_DELIMITED_PATH_SEGMENT}*",
+    ]
+    if pattern.startswith("**/"):
+        pattern = pattern[3:]
+    elif SLASH in pattern[:-1]:
+        collector.clear()
+        if pattern.startswith(SLASH):
+            pattern = pattern[1:]
+        #
+    #
+    post_patterns = []
+    if pattern.endswith("/**"):
+        post_patterns.append(f"/(?:{RX_NO_SLASH}.*)?")
+        pattern = pattern[:-3]
+    elif not pattern.endswith(SLASH):
+        post_patterns.append("/?")
+    #
+    collector.append(
+        f"/{RX_END_DELIMITED_PATH_SEGMENT}*".join(
+            SLASH.join(
+                glob_segment_to_regex_segment(segment)
+                for segment in subpattern.split(SLASH)
+            )
+            for subpattern in pattern.split("/**/")
+        )
+    )
+    return f"^{EMPTY.join(collector + post_patterns)}$"
+
+
+def glob_segment_to_regex_segment(glob_segment: str) -> str:
+    """Translate a single path glob segment to a regular expression pattern part
+
+    [fnmatch]: https://docs.python.org/3/library/fnmatch.html
+    !!! note
+        * Adapted from the standard library’s [fnmatch] module source
+        * function name was `_join_translated_parts`
+        * see <https://github.com/python/cpython/blob/v3.14.6/Lib/fnmatch.py#L186>
+
+    Patterns are Unix shell style:
+
+    *   `*`      matches everything
+    *   `?`      matches any single character
+    *   `[seq]`  matches any character in seq
+    *   `[!seq]` matches any char not in seq
+
+    Args:
+        glob_segment: one segment of a path which may neither contain a
+            forward slash nor end in a single backslash
+
+    Returns:
+        a partial regular expression pattern matching a single path segment
+            in the same way as the glob segment
+
+    Raises:
+        ValueError: if the glob segment includes a slash,
+            or if it ends in a single backslash
+    """
+    if SLASH in glob_segment:
+        raise ValueError(
+            f"Path glob segments may not contain slashes: {glob_segment!r}"
+        )
+    #
+    if glob_segment.endswith(BACKSLASH) and not glob_segment[:-1].endswith(BACKSLASH):
+        raise ValueError(
+            f"Path glob segments may not end in a single backslash: {glob_segment!r}"
+        )
+    #
+    parts, star_indices = dissect_glob_segment(glob_segment)
+    if not star_indices:
+        return EMPTY.join(parts)
+    #
+    iter_star_indices = iter(star_indices)
+    star_index = next(iter_star_indices)
+    buffer = parts[:star_index]  # fixed pieces at the start
+    chunk_index = star_index + 1
+    for star_index in iter_star_indices:
+        # Now deal with STAR fixed STAR fixed ...
+        # For an interior `STAR fixed` pairing, we want to do a minimal
+        # .*? match followed by `fixed`, with no possibility of backtracking.
+        # Atomic groups ("(?>...)") allow us to spell that directly.
+        # Note: people rely on the undocumented ability to join multiple
+        # translate() results together via "|" to build large regexps matching
+        # "one of many" shell patterns.
+        buffer.extend((f"(?>{RX_NO_SLASH}*?", *parts[chunk_index:star_index], ")"))
+        chunk_index = star_index + 1
+    #
+    buffer.extend((f"{RX_NO_SLASH}*", *parts[chunk_index:]))
+    return EMPTY.join(buffer)
+
+
+def dissect_glob_segment(
+    glob_segment: str,
+    /,
+    *,
+    star_placeholder: str = ASTERISK,
+    question_mark_regex_replacement: str = RX_NO_SLASH,
+) -> tuple[list[str], list[int]]:
+    """Dissect a glob segment to chunks of regular expression parts
+    and a sequence of star positions
+
+    !!! note
+        * Adapted from the standard library’s [fnmatch] module source
+        * function name was `_translate`
+        * see <https://github.com/python/cpython/blob/v3.14.6/Lib/fnmatch.py#L109>
+
+    Args:
+        glob_segment: the glob segment to dissect
+        star_placeholder: the placeholder for a glob star wildcard
+        question_mark_regex_replacement: the regex replacement for a glob
+            question mark wildcard
+
+    Returns:
+        the sequence of regex chunks and the sequence of star positions
+            in the chunks sequence.
+            This result is post-processed in the
+            [glob_segment_to_regex_segment][offgrep.ignore.glob_segment_to_regex_segment]
+            function which calls `dissect_glob_segment()` internally.
+    """
+    re_chunks: list[str] = []
+    star_indices: list[int] = []
+    pos = 0
+    segment_length = len(glob_segment)
+    while pos < segment_length:
+        current_character = glob_segment[pos]
+        pos += 1
+        if current_character == ASTERISK:
+            # Multi-character wildcard,
+            # with positions stored extra to mitigate backtracking
+            # denial of service risks in the regular expression
+            # that is built in the calling function
+            star_indices.append(len(re_chunks))
+            re_chunks.append(star_placeholder)
+            # compress consecutive star wildcards into one
+            while pos < segment_length and glob_segment[pos] == ASTERISK:
+                pos += 1
+            #
+        elif current_character == QUESTION_MARK:
+            # Single character wildcard
+            re_chunks.append(question_mark_regex_replacement)
+        elif current_character == OPENING_BRACKET:
+            # Characters group in brackets
+            fwdpos = pos
+            for bracket_special_character in (EXCLAMATION_MARK, CLOSING_BRACKET):
+                if (
+                    fwdpos < segment_length
+                    and glob_segment[fwdpos] == bracket_special_character
+                ):
+                    fwdpos += 1
+                #
+            #
+            while fwdpos < segment_length and glob_segment[fwdpos] != CLOSING_BRACKET:
+                fwdpos += 1
+            #
+            if fwdpos >= segment_length:
+                # unclosed bracket, interpret as literal [
+                re_chunks.append(RE_ESCAPE(OPENING_BRACKET))
+            else:
+                # add appropriate bracket replacement
+                brackets_content, pos = bracketed_glob_pattern_part_to_partial_regex(
+                    glob_segment, pos, fwdpos
+                )
+                re_chunks.append(brackets_content)
+            #
+        else:
+            # Characters that are not special to globbing
+            re_chunks.append(RE_ESCAPE(current_character))
+        #
+    #
+    assert pos == segment_length
+    return re_chunks, star_indices
+
+
+def bracketed_glob_pattern_part_to_partial_regex(
+    full_glob_segment: str, start: int, end: int
+) -> tuple[str, int]:
+    """Translate a file name glob pattern part inside square brackets
+    into a regular expression pattern part
+
+    !!! note
+        Factored out from the
+        [dissect_glob_segment()][offgrep.ignore.dissect_glob_segment]
+        function
+
+    Args:
+        full_glob_segment: the full glob segment
+        start: index of the first character of the bracket content
+        end: index of the last character of the bracket content
+
+    Returns:
+        the regular expression equivalent to the glob bracket expression
+    """
+    assert start > 0
+    assert start - 1 < end < len(full_glob_segment)
+    content = full_glob_segment[start:end]
+    assert f"[{content}]" == full_glob_segment[start - 1 : end + 1]
+    pos = start
+    if DASH in content:
+        chunks = []
+        fwdpos = pos + 2 if full_glob_segment[pos] == EXCLAMATION_MARK else pos + 1
+        while True:
+            fwdpos = full_glob_segment.find(DASH, fwdpos, end)
+            if fwdpos < 0:
+                break
+            #
+            chunks.append(full_glob_segment[pos:fwdpos])
+            pos = fwdpos + 1
+            fwdpos = fwdpos + 3
+        #
+        current_chunk = full_glob_segment[pos:end]
+        if current_chunk:
+            chunks.append(current_chunk)
+        else:
+            chunks[-1] += DASH
+        #
+        # Remove empty ranges from end to start
+        # because these are invalid in regular exoressions
+        for ccpos in range(len(chunks) - 1, 0, -1):
+            if chunks[ccpos - 1][-1] > chunks[ccpos][0]:
+                chunks[ccpos - 1] = chunks[ccpos - 1][:-1] + chunks[ccpos][1:]
+                del chunks[ccpos]
+            #
+        #
+        # Escape backslashes and hyphens for set difference (--).
+        # Hyphens that create ranges shouldn't be escaped.
+        content = DASH.join(
+            single_chunk.replace(BACKSLASH, RE_ESCAPE(BACKSLASH)).replace(
+                DASH, RE_ESCAPE(DASH)
+            )
+            for single_chunk in chunks
+        )
+    else:
+        content = content.replace(BACKSLASH, RE_ESCAPE(BACKSLASH))
+    #
+    pos = end + 1
+    if not content:
+        # [] (empty range): never match.
+        return "(?!)", pos
+    #
+    if content == EXCLAMATION_MARK:
+        # [!] (negated empty range): match any character except /
+        return RX_NO_SLASH, pos
+    #
+    # Escape set operations (&&, ~~ and ||).
+    content = CRE_SETOPS.sub(r"\\\1", content)
+    #
+    if content[0] == EXCLAMATION_MARK:
+        # Translate [!…] to [^…]
+        content = f"{CARET}{content[1:]}"
+    elif content[0] in (CARET, OPENING_BRACKET):
+        # Backslash escape
+        content = f"{RE_ESCAPE(content[0])}{content[1:]}"
+    #
+    return f"[{content}]", pos

offgrep-0.0.2/src/offgrep/__main__.py

@@ -1,107 +0,0 @@
-# -*- coding: utf-8 -*-
-
-"""
-Call as script
-"""
-
-import sys
-
-from argparse import ArgumentParser, Namespace
-from importlib.metadata import PackageNotFoundError, version as metadata_version
-from logging import WARNING
-from pathlib import Path
-from tomllib import loads as tomli_loads
-
-
-PACKAGE_NAME = "offgrep"
-"""The package name for metadata inspection"""
-
-
-def get_file_contents(file_name: str, up_dirs: int = 0) -> str:
-    """get contents of a file in an ancestor directory
-    of the current file
-
-    ...
-    """
-    file_dir_path = Path(__file__).resolve()
-    for _ in range(up_dirs):
-        file_dir_path = file_dir_path.parent
-    #
-    file_path = file_dir_path / file_name
-    return file_path.read_text(encoding="utf-8")
-
-
-def get_metadata_version(
-    metadata_file_name: str = "pyproject.toml", up_dirs: int = 3
-) -> str:
-    """get version information from _metadata_file_name_ in an ancestor directory
-
-    ...
-    """
-    try:
-        metadata_file_contents = get_file_contents(metadata_file_name, up_dirs=up_dirs)
-    except IOError as error:
-        return str(error)
-    #
-    metadata = tomli_loads(metadata_file_contents)
-    try:
-        # logging.warning(str(metadata.items()))
-        version = metadata["project"]["version"]
-    except KeyError:
-        return f"Error: no version information in metadata from {metadata_file_name}"
-    #
-    return f"{version} (read directly from {metadata_file_name})"
-
-
-# pylint: disable=unused-argument ; functions not implemented yet
-
-
-def grep_files(arguments: Namespace) -> int:
-    """Search for text in files"""
-    return 0
-
-
-def list_files(arguments: Namespace) -> int:
-    """List files that would be searched"""
-    return 0
-
-
-# pylint: enable=unused-argument
-
-
-def main() -> int:
-    """Main script interface
-
-    Returns:
-        the script rteurncode
-    """
-    try:
-        version = metadata_version(PACKAGE_NAME)
-    except PackageNotFoundError:
-        version = get_metadata_version()
-    #
-    main_parser = ArgumentParser(
-        prog="offgrep", description="searches text in (text) files recursively"
-    )
-    main_parser.set_defaults(loglevel=WARNING, extra_ignore=".git/")
-    main_parser.add_argument("-V", "--version", action="version", version=version)
-    main_parser.add_argument(
-        "--extra-ignore",
-        help="extra ignore rules separated by comma (default: %(default)s)",
-    )
-    main_parser.add_argument(
-        "--files",
-        action="store_true",
-        help="list the files that would be searched",
-    )
-    arguments = main_parser.parse_args()
-    if arguments.files:
-        return list_files(arguments)
-    #
-    return grep_files(arguments)
-
-
-if __name__ == "__main__":
-    sys.exit(main())  # pragma: no cover
-
-# vim: fileencoding=utf-8 ts=4 sts=4 sw=4 autoindent expandtab syntax=python: