reglem 0.1.0__py3-none-any.whl

reglem/__init__.py

@@ -0,0 +1,40 @@
+"""reglem: build anchored regex alternations over word lemmas.
+
+Turns a list of lemmas into one anchored regex alternation
+(`^(lemma1|lemma2|...)([terminators]|$)`, split into one bracketed group per
+terminator set when a language excludes a terminator for specific lemmas --
+see `build.py`), with optional per-language spelling-variant expansion
+(currently: Greek macron/long-vowel forms), and an Anki `field:re:...`
+search-string wrapper. See `docs/greek.md` and the README for the motivating
+detail.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from reglem.anki import build_anki_search
+from reglem.build import build_pattern
+from reglem.errors import EmptyLemmaSetError, ReglemError, UnknownLanguageError
+from reglem.languages import available_languages, get_language
+from reglem.normalize import normalize_lemma, prepare_lemmas
+from reglem.options import SearchOptions
+
+try:
+    __version__ = version("reglem")
+except PackageNotFoundError:  # pragma: no cover -- only hit for an uninstalled checkout
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "EmptyLemmaSetError",
+    "ReglemError",
+    "SearchOptions",
+    "UnknownLanguageError",
+    "__version__",
+    "available_languages",
+    "build_anki_search",
+    "build_pattern",
+    "get_language",
+    "normalize_lemma",
+    "prepare_lemmas",
+]

reglem/anki.py

@@ -0,0 +1,23 @@
+"""Wrap a lemma pattern as a quoted Anki `field:re:...` search string.
+
+Anki field regexes are unanchored by default (`front:re:[a-c]1` matches
+anywhere in the field, not just at its start), which is why `build_pattern`
+anchors with `^` explicitly rather than relying on Anki to do it.
+"""
+
+from __future__ import annotations
+
+from reglem.build import build_pattern
+from reglem.options import SearchOptions
+
+
+def build_anki_search(lemmas: list[str], options: SearchOptions | None = None) -> str:
+    """Build a quoted `"field:re:pattern"` Anki search matching any of `lemmas`.
+
+    Raises `EmptyLemmaSetError` (from `build_pattern`) if `lemmas` is empty.
+    """
+    options = options or SearchOptions()
+    pattern = build_pattern(lemmas, options)
+    escaped_field = options.field.replace('"', '\\"')
+    escaped_pattern = pattern.replace('"', '\\"')
+    return f'"{escaped_field}:re:{escaped_pattern}"'

reglem/build.py

@@ -0,0 +1,103 @@
+"""Build an anchored regex alternation matching a set of lemmas.
+
+The pattern shape is `^(alt1|alt2|...)([terminator-chars]|$)`: anchored to
+the start of the field/line, so a lemma that's a prefix of another word
+(`ὁ` vs `ὁδός`) doesn't false-match, and terminated by an explicit character
+class or end-of-string rather than a lookahead assertion.
+
+That terminator design isn't cosmetic: this is meant to also work as an Anki
+`re:` search, and Anki's `re:` matching uses the Rust `regex` crate (see
+https://docs.rs/regex, referenced from docs.ankiweb.net/searching.html),
+which does NOT support lookaround. A pattern like `^word(?=[ ,])` is valid
+Python/PCRE but invalid there -- the terminator has to be an ordinary
+alternation group instead.
+
+One anchored alternation over all lemmas, rather than one OR'd term per
+lemma, keeps the pattern shorter and the match a single regex pass instead
+of N.
+
+A language may also declare, per lemma, terminator characters that must be
+*excluded* for that lemma specifically (`Language.excluded_terminators` --
+see `languages/greek.py`'s `ARTICLE_FORMS` for why). When no lemma triggers
+an exclusion, the whole set shares one terminator group exactly as above.
+When one does, the alternatives are split into groups by their effective
+terminator set and each group gets its own trailing group instead:
+`^((?:lemma-a|lemma-b)(?:[terminators]|$)|(?:lemma-c)(?:[fewer-terminators]|$))`.
+A branch whose lemma matches but whose terminator doesn't still falls
+through to try the next branch, under ordinary leftmost-first alternation
+(true for both Python's `re` and the Rust `regex` crate) -- so this still
+needs no lookaround, same as the single-group form.
+"""
+
+from __future__ import annotations
+
+import re
+
+from reglem.errors import EmptyLemmaSetError
+from reglem.languages import get_language
+from reglem.normalize import prepare_lemmas
+from reglem.options import SearchOptions
+from reglem.variants import VariantTable, expand_variants
+
+
+def _expand(text: str, table: VariantTable | None) -> str:
+    """Escape `text` literally, or with per-character variants from `table`."""
+    if table is None:
+        return re.escape(text)
+    return expand_variants(text, table)
+
+
+def _terminator_group(terminators: str) -> str:
+    """Regex fragment matching one allowed terminator, or end-of-string.
+
+    `terminators` may be empty (every character excluded for this lemma) --
+    `[]` is not a valid regex character class, so that case falls back to
+    requiring end-of-string outright.
+    """
+    if not terminators:
+        return "$"
+    return f"[{re.escape(terminators)}]|$"
+
+
+def build_pattern(lemmas: list[str], options: SearchOptions | None = None) -> str:
+    """Build a bare (unquoted, un-field-prefixed) regex pattern matching `lemmas`.
+
+    Raises `EmptyLemmaSetError` if `lemmas` is empty or normalizes down to
+    nothing (e.g. all blank strings).
+    """
+    options = options or SearchOptions()
+    alternatives = prepare_lemmas(lemmas, strip_trailing_digits=options.strip_trailing_digits)
+    if not alternatives:
+        raise EmptyLemmaSetError
+
+    language = get_language(options.language)  # already validated by SearchOptions
+    table: VariantTable | None = None
+    if options.with_macrons:
+        table = language.variant_tables.get("macrons")
+    excluded_terminators = language.excluded_terminators
+
+    # Group alternatives by their effective (post-exclusion) terminator
+    # string, preserving prepare_lemmas' longest-first order within a group.
+    groups: dict[str, list[str]] = {}
+    for alt in alternatives:
+        excluded = excluded_terminators.get(alt, "")
+        effective = "".join(char for char in options.terminators if char not in excluded)
+        groups.setdefault(effective, []).append(alt)
+
+    if len(groups) == 1:
+        (effective,) = groups
+        alternation = "|".join(_expand(alt, table) for alt in alternatives)
+        pattern = f"^({alternation})({_terminator_group(effective)})"
+    else:
+        # Unrestricted group (if any) first, then the rest sorted for a
+        # deterministic, reviewable pattern.
+        ordered = sorted(groups, key=lambda t: (t != options.terminators, t))
+        branches = [
+            f"(?:{'|'.join(_expand(alt, table) for alt in groups[effective])})"
+            f"(?:{_terminator_group(effective)})"
+            for effective in ordered
+        ]
+        pattern = f"^({'|'.join(branches)})"
+
+    re.compile(pattern)  # self-check: fail here, not at the point of use
+    return pattern

reglem/cli.py

@@ -0,0 +1,146 @@
+"""Command-line entry point for reglem.
+
+Usage
+-----
+    reglem lemmas.txt
+    cat lemmas.txt | reglem -
+    reglem -w lemma-one -w "lemma two" --macrons
+    reglem lemmas.txt --raw --terminators ",;"
+    reglem --list-languages
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from reglem import __version__
+from reglem.anki import build_anki_search
+from reglem.build import build_pattern
+from reglem.errors import ReglemError
+from reglem.languages import available_languages
+from reglem.options import DEFAULT_FIELD, DEFAULT_TERMINATORS, SearchOptions
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the `reglem` argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="reglem",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+        help="file of lemmas, one per line ('#' comments and blank lines skipped); "
+        "'-' or omitted reads stdin",
+    )
+    parser.add_argument(
+        "-w",
+        "--word",
+        action="append",
+        dest="words",
+        metavar="LEMMA",
+        help="a lemma to include; repeatable. Overrides path/stdin when given.",
+    )
+    parser.add_argument(
+        "-f",
+        "--field",
+        default=DEFAULT_FIELD,
+        help=f"Anki field to match against (default: {DEFAULT_FIELD!r})",
+    )
+    parser.add_argument(
+        "--language",
+        default="greek",
+        help="language whose spelling-variant tables to use (default: greek)",
+    )
+    parser.add_argument(
+        "--macrons",
+        action="store_true",
+        help="expand ambiguous-length vowels into macron alternatives (language-dependent)",
+    )
+    parser.add_argument(
+        "--strip-trailing-digits",
+        action="store_true",
+        help="strip a trailing homograph digit (e.g. 'lead2') from each lemma before matching",
+    )
+    parser.add_argument(
+        "--terminators",
+        default=DEFAULT_TERMINATORS,
+        help=f"characters (besides end-of-field) that may follow a matched lemma "
+        f"(default: {DEFAULT_TERMINATORS!r})",
+    )
+    parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="print the bare regex pattern instead of a quoted Anki search string",
+    )
+    parser.add_argument(
+        "--list-languages",
+        action="store_true",
+        help="print known language names and exit",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"reglem {__version__}",
+    )
+    return parser
+
+
+def _read_lemmas(path: str | None, words: list[str] | None) -> list[str]:
+    """Resolve lemmas from `-w` words, a file path, or stdin, in that precedence order."""
+    if words:
+        return list(words)
+
+    if path is None or path == "-":
+        lines = sys.stdin.readlines()
+    else:
+        lines = Path(path).read_text(encoding="utf-8").splitlines()
+
+    lemmas: list[str] = []
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        lemmas.append(line)
+    return lemmas
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the `reglem` CLI. Returns the process exit code."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.list_languages:
+        for name in available_languages():
+            print(name)
+        return 0
+
+    try:
+        lemmas = _read_lemmas(args.path, args.words)
+        options = SearchOptions(
+            language=args.language,
+            with_macrons=args.macrons,
+            strip_trailing_digits=args.strip_trailing_digits,
+            terminators=args.terminators,
+            field=args.field,
+        )
+        result = (
+            build_pattern(lemmas, options) if args.raw else build_anki_search(lemmas, options)
+        )
+    except (ReglemError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reglem/errors.py

@@ -0,0 +1,23 @@
+"""Error types raised by reglem."""
+
+from __future__ import annotations
+
+
+class ReglemError(Exception):
+    """Base class for every error reglem raises on purpose."""
+
+
+class EmptyLemmaSetError(ReglemError):
+    """Raised when a pattern is requested for zero lemmas."""
+
+    def __init__(self) -> None:
+        """Build the fixed error message for this error."""
+        super().__init__("no lemmas given -- need at least one to build a pattern")
+
+
+class UnknownLanguageError(ReglemError):
+    """Raised when a language name isn't in the registry."""
+
+    def __init__(self, name: str, known: tuple[str, ...]) -> None:
+        """Build an error message naming the bad `name` and the `known` alternatives."""
+        super().__init__(f"unknown language {name!r}; known languages: {', '.join(known)}")

reglem/languages/__init__.py

@@ -0,0 +1,29 @@
+"""Registry of known languages.
+
+A plain dict, not a plugin system -- with one language, entry-point discovery
+would be pure ceremony. Revisit once a second language actually shows up.
+"""
+
+from __future__ import annotations
+
+from reglem.errors import UnknownLanguageError
+from reglem.languages._base import Language
+from reglem.languages.greek import GREEK
+
+_REGISTRY: dict[str, Language] = {GREEK.name: GREEK}
+
+
+def get_language(name: str) -> Language:
+    """Look up a `Language` by name, raising `UnknownLanguageError` if unknown."""
+    try:
+        return _REGISTRY[name]
+    except KeyError:
+        raise UnknownLanguageError(name, available_languages()) from None
+
+
+def available_languages() -> tuple[str, ...]:
+    """Return the names of every registered language, sorted."""
+    return tuple(sorted(_REGISTRY))
+
+
+__all__ = ["Language", "available_languages", "get_language"]

reglem/languages/_base.py

@@ -0,0 +1,34 @@
+"""The `Language` model shared by every language module and the registry.
+
+Split out from `languages/__init__.py` to avoid a circular import: each
+language module (e.g. `greek.py`) builds a `Language` instance at import
+time, and the registry in `__init__.py` imports those modules -- so the
+`Language` type itself can't live in `__init__.py` too.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+# Needed at runtime, not just for type-checking: pydantic resolves the
+# `dict[str, VariantTable]` annotation below when building the model, which
+# requires `VariantTable` to actually be in this module's namespace.
+from reglem.variants import VariantTable  # noqa: TC001
+
+
+class Language(BaseModel):
+    """A named set of per-character spelling-variant tables for one language."""
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    name: str
+    variant_tables: dict[str, VariantTable]
+    excluded_terminators: dict[str, str] = {}
+    """Lemma -> terminator characters that may NOT follow that exact lemma.
+
+    Empty by default, so languages without any such exception need not set
+    it. See `greek.py`'s `ARTICLE_FORMS` for the motivating case: a lemma
+    whose normal dictionary citation is never followed by a plain space, so
+    space needs to be excluded from its terminator set specifically rather
+    than for every lemma.
+    """

reglem/languages/greek.py

@@ -0,0 +1,144 @@
+"""Greek variant tables: macron (long-vowel) alternatives for α, ι, υ.
+
+Many Greek word lists (e.g. lemma dictionaries, vocabulary tools) mark accent
+and breathing but never vowel *length* -- α, ι, and υ are ambiguous between
+short and long in that spelling. Pedagogical texts, by contrast, often mark
+long instances of these three vowels with a macron layered on top of
+whatever accent/breathing the vowel already carries, e.g. a long alpha with
+smooth breathing appears as ᾱ̓ rather than ἀ.
+
+Unicode has a precomposed macron-vowel character (ᾱ ῑ ῡ) but NOT a
+precomposed macron+breathing or macron+accent character -- those are the
+macron-vowel codepoint followed by ordinary *combining* breathing/accent
+marks (U+0313 smooth, U+0314 rough, U+0301 acute, U+0300 grave), breathing
+before accent. Verified against Python's `unicodedata` (both directions):
+
+    >>> import unicodedata
+    >>> unicodedata.normalize("NFC", "ᾱ" + "̓" + "́") == "ᾱ" + "̓" + "́"
+    True  # already canonical -- NFC does not reorder or recompose it further
+
+Also verified: NFC always resolves the alpha/iota/upsilon + acute ambiguity
+(there are two Unicode encodings of e.g. "alpha with acute", the polytonic
+U+1F71 and the monotonic U+03AC "tonos" form) down to the single tonos
+codepoint -- most Greek lemma sources use NFC text, so there's no
+dual-encoding to account for on that side.
+
+Circumflex forms (ᾶ, ἆ, ἇ, and the ι/υ equivalents) are deliberately absent
+from MACRON_MAP: a circumflex accent can only fall on a long vowel, so a
+circumflexed α/ι/υ is already unambiguously long and has no separate macron
+form to search for.
+
+Known simplification: this maps every occurrence of a bare/accented/breathed
+α, ι, or υ, including ones that are actually the first or second vowel of a
+diphthong (αι, αυ, ει, ευ, οι, ου, υι), where a macron would never actually
+be written. This only makes a generated pattern larger (extra alternation
+branches that can never match anything real), not incorrect -- reliably
+detecting diphthongs is much more machinery than the false-positive cost
+justifies here.
+
+Separately, `ARTICLE_FORMS` lists the 19 forms of the Greek definite article.
+A lemma pattern normally allows a plain space right after a matched lemma
+(see `DEFAULT_TERMINATORS` in `options.py`), but the article is special: it
+is never the last thing before running Greek text in a dictionary/word-list
+entry the way an ordinary headword is. Instead it's cited on its own, joined
+to its other forms by punctuation -- `ὁ, ἡ, τό` or `ὁ/ἡ/τό` -- while in
+running text it is immediately followed by the word it modifies (`ὁ σοφός`,
+`ἡ ἀρίστη`). Without an exception, an article lemma matches the start of
+every one of those unrelated entries. So `GREEK.excluded_terminators` denies
+a plain space, and a non-breaking space (U+00A0), right after any article
+form -- comma, period, slash, and end-of-field are still allowed.
+
+NBSP is excluded for the same reason it's a default terminator at all
+(`options.py`'s `DEFAULT_TERMINATORS` docstring): it renders as an invisible
+space in the Anki editor while still separating words in field HTML, so it
+needs the same treatment as a literal space here.
+
+Grave-accented forms (τὸν, τὴν, τοὺς, τὰς -- the article as it actually
+appears in running text, where an acute shifts to a grave before another
+word) are deliberately not in `ARTICLE_FORMS`: a lemma list cites the acute
+citation form, not the running-text accentuation, so there is nothing to
+exclude a terminator from for those spellings. Adding them would be a
+one-line extension if a source ever needs it.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from typing import TYPE_CHECKING
+
+from reglem.languages._base import Language
+
+if TYPE_CHECKING:
+    from reglem.variants import VariantTable
+
+_SMOOTH = "̓"  # combining comma above (psili)
+_ROUGH = "̔"  # combining reversed comma above (dasia)
+_ACUTE = "́"  # combining acute accent (oxia)
+_GRAVE = "̀"  # combining grave accent (varia)
+
+
+def _macron_table(bare: str, macron_base: str, breathing_accent_block: str) -> dict[str, str]:
+    """Build the 9-entry {surface_form: macron_form} table for one vowel.
+
+    `breathing_accent_block` holds the eight precomposed Greek Extended
+    characters for this vowel, in the fixed order: smooth, rough,
+    smooth+grave, rough+grave, smooth+acute, rough+acute, grave, acute.
+    """
+    smooth, rough, smooth_grave, rough_grave, smooth_acute, rough_acute, grave, acute = (
+        breathing_accent_block
+    )
+    return {
+        bare: macron_base,
+        acute: macron_base + _ACUTE,
+        grave: macron_base + _GRAVE,
+        smooth: macron_base + _SMOOTH,
+        rough: macron_base + _ROUGH,
+        smooth_acute: macron_base + _SMOOTH + _ACUTE,
+        rough_acute: macron_base + _ROUGH + _ACUTE,
+        smooth_grave: macron_base + _SMOOTH + _GRAVE,
+        rough_grave: macron_base + _ROUGH + _GRAVE,
+    }
+
+
+# fmt: off
+MACRON_MAP: VariantTable = {
+    **_macron_table("α", "ᾱ", "ἀἁἂἃἄἅὰά"),
+    **_macron_table("ι", "ῑ", "ἰἱἲἳἴἵὶί"),
+    **_macron_table("υ", "ῡ", "ὐὑὒὓὔὕὺύ"),
+}
+# fmt: on
+
+_EXPECTED_MACRON_MAP_SIZE = 27  # 9 each for α/ι/υ
+assert len(MACRON_MAP) == _EXPECTED_MACRON_MAP_SIZE, (  # noqa: S101
+    f"expected {_EXPECTED_MACRON_MAP_SIZE} entries, got {len(MACRON_MAP)}"
+)
+
+# fmt: off
+ARTICLE_FORMS: tuple[str, ...] = tuple(
+    unicodedata.normalize("NFC", form)
+    for form in (
+        "ὁ", "ἡ", "τό",
+        "τοῦ", "τῆς", "τῷ", "τῇ", "τόν", "τήν",
+        "τώ", "τοῖν",
+        "οἱ", "αἱ", "τά", "τῶν", "τοῖς", "ταῖς", "τούς", "τάς",
+    )
+)
+# fmt: on
+"""The 19 forms of the Greek definite article (masc./fem./neut., all cases,
+all numbers), NFC-normalized to match how `prepare_lemmas` compares lemmas.
+See the module docstring for why these specifically need a terminator
+exception.
+"""
+
+_EXPECTED_ARTICLE_FORM_COUNT = 19
+assert len(ARTICLE_FORMS) == _EXPECTED_ARTICLE_FORM_COUNT, (  # noqa: S101
+    f"expected {_EXPECTED_ARTICLE_FORM_COUNT} article forms, got {len(ARTICLE_FORMS)}"
+)
+
+_SPACE_TERMINATORS = " \xa0"  # plain space, non-breaking space
+
+GREEK = Language(
+    name="greek",
+    variant_tables={"macrons": MACRON_MAP},
+    excluded_terminators=dict.fromkeys(ARTICLE_FORMS, _SPACE_TERMINATORS),
+)

reglem/normalize.py

@@ -0,0 +1,48 @@
+"""Normalize raw lemma text before it goes into a pattern.
+
+Two independent cleanups live here:
+
+- Unicode NFC normalization, so visually-identical lemmas that happen to use
+  different combining-mark orders or precomposed-vs-decomposed forms compare
+  equal.
+- Optional trailing-digit stripping, for word lists that disambiguate
+  homographs with a suffix digit (e.g. ``lead2`` for the metal vs. ``lead``
+  the verb). Off by default -- not every source uses this convention, and
+  guessing wrong silently merges two different words.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+_TRAILING_DIGITS_RE = re.compile(r"\d+$")
+
+
+def normalize_lemma(text: str, *, strip_trailing_digits: bool = False) -> str:
+    """Return `text` NFC-normalized, optionally with trailing digits removed."""
+    if strip_trailing_digits:
+        text = _TRAILING_DIGITS_RE.sub("", text)
+    return unicodedata.normalize("NFC", text)
+
+
+def prepare_lemmas(
+    lemmas: list[str],
+    *,
+    strip_trailing_digits: bool = False,
+) -> list[str]:
+    """Normalize, drop blanks, dedupe, and order a list of raw lemmas.
+
+    Order is longest-first (ties broken alphabetically) rather than
+    insertion order or plain sort: it's deterministic, and it guarantees a
+    longer alternative is tried before a shorter one that happens to be its
+    prefix, which matters under leftmost-first regex alternation (the
+    engines targeted here, including the Rust `regex` crate Anki embeds,
+    pick the first alternative that matches rather than the longest).
+    """
+    normalized = (
+        normalize_lemma(lemma, strip_trailing_digits=strip_trailing_digits).strip()
+        for lemma in lemmas
+    )
+    deduped = {lemma for lemma in normalized if lemma}
+    return sorted(deduped, key=lambda lemma: (-len(lemma), lemma))

reglem/options.py

@@ -0,0 +1,71 @@
+"""Options controlling how a lemma pattern is built."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from reglem.errors import UnknownLanguageError
+from reglem.languages import available_languages, get_language
+
+DEFAULT_TERMINATORS = " ,.\xa0/"
+"""Space, comma, full stop, non-breaking space (U+00A0), slash.
+
+The non-breaking space matters for Anki fields specifically: it shows up in
+field HTML (e.g. entity-derived) but is invisible in the Anki editor, so
+omitting it here would cause silent, hard-to-diagnose match misses. It's
+harmless to keep as a default for other targets too.
+
+The slash covers dictionary entries that cite alternative spellings inline,
+e.g. a slash-separated Greek article (`ὁ/ἡ/τό`) or adjective principal parts
+(`ἀγαθός/ή/όν`).
+"""
+
+DEFAULT_FIELD = "Greek"
+
+
+class SearchOptions(BaseModel):
+    """Immutable, validated configuration for `build_pattern` / `build_anki_search`."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    language: str = "greek"
+    with_macrons: bool = False
+    strip_trailing_digits: bool = False
+    terminators: str = DEFAULT_TERMINATORS
+    field: str = DEFAULT_FIELD
+
+    @field_validator("language")
+    @classmethod
+    def _known_language(cls, value: str) -> str:
+        # pydantic only auto-wraps ValueError/TypeError/AssertionError raised
+        # from a validator into its own ValidationError, so translate here
+        # rather than let UnknownLanguageError escape raw.
+        try:
+            get_language(value)
+        except UnknownLanguageError as exc:
+            raise ValueError(str(exc)) from exc
+        return value
+
+    @field_validator("terminators")
+    @classmethod
+    def _terminators_not_empty(cls, value: str) -> str:
+        if not value:
+            msg = "terminators must not be empty"
+            raise ValueError(msg)
+        return value
+
+    @field_validator("field")
+    @classmethod
+    def _field_not_blank(cls, value: str) -> str:
+        if not value.strip():
+            msg = "field must not be blank"
+            raise ValueError(msg)
+        if "\n" in value or "\r" in value:
+            msg = "field must not contain a newline"
+            raise ValueError(msg)
+        return value
+
+    @property
+    def known_languages(self) -> tuple[str, ...]:
+        """Convenience passthrough for callers building error/help text."""
+        return available_languages()

reglem/variants.py

@@ -0,0 +1,32 @@
+"""Expand a literal string into a regex fragment with per-character spelling variants.
+
+A variant table maps one surface character to one alternative spelling of
+that character (e.g. a plain vowel to its long-marked form). `expand_variants`
+walks the input character by character, escaping every character literally
+except the ones with a table entry, which become a non-capturing
+`(?:plain|variant)` group.
+
+This never emits lookaround (`(?=...)`, `(?!...)`), on purpose: some target
+engines this feeds into -- notably the Rust `regex` crate Anki embeds -- don't
+support it.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+VariantTable = Mapping[str, str]
+"""Surface character -> alternative spelling of that character."""
+
+
+def expand_variants(text: str, table: VariantTable) -> str:
+    """Return a regex source fragment matching `text` or its per-character variants."""
+    parts: list[str] = []
+    for char in text:
+        variant = table.get(char)
+        if variant is None:
+            parts.append(re.escape(char))
+        else:
+            parts.append(f"(?:{re.escape(char)}|{re.escape(variant)})")
+    return "".join(parts)

reglem-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: reglem
+Version: 0.1.0
+Summary: Build anchored regex alternations over word lemmas, with optional per-language spelling variants.
+Project-URL: Homepage, https://github.com/jaycrick/reglem
+Project-URL: Issues, https://github.com/jaycrick/reglem/issues
+Project-URL: Changelog, https://github.com/jaycrick/reglem/blob/main/CHANGELOG.md
+Author-email: jaycrick <114450568+jaycrick@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anki,greek,lemma,linguistics,regex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# reglem
+
+Turn list of word lemmas into one anchored regex alternation.
+Optional per-language spelling variants (Greek macrons, for now).
+Optional Anki `field:re:...` search-string wrapper.
+
+Greek only today.
+Language layer built so more languages drop in later without touching core.
+
+## Why
+
+Building `re:` search for Anki (or any regex-search tool) by hand from a word list is fiddly:
+prefix leaks (`ox` matching `oxen`),
+Rust `regex` crate has no lookahead so `(?=...)` breaks in Anki,
+spelling variants (accents, long-vowel marks) multiply the work.
+This package does that once, correctly, tested.
+
+## Install
+
+```bash
+uv add reglem
+# or
+pip install reglem
+```
+
+## Quickstart — library
+
+```python
+from reglem import build_anki_search, build_pattern, SearchOptions
+
+# bare regex
+build_pattern(["cat", "dog"])
+# '^(dog|cat)([ ,. ]|$)'
+
+# Anki search string
+build_anki_search(["ὁ", "καί", "ἀγαθός"], SearchOptions(field="Greek", with_macrons=True))
+# '"Greek:re:^(...)([ ,. ]|$)"'
+```
+
+Paste that string into Anki's Browse search bar.
+It matches notes whose field *starts* with one of the given lemmas,
+followed by space, comma, period, or end of field.
+
+## Quickstart — CLI
+
+```bash
+reglem lemmas.txt                     # Anki search string, one lemma per line in file
+cat lemmas.txt | reglem -             # same, from stdin
+reglem -w ὁ -w καί -w ἀγαθός --macrons
+reglem lemmas.txt --raw               # bare regex, no Anki wrapper
+reglem --list-languages
+```
+
+`lemmas.txt`: one lemma per line, blank lines and `#` comments skipped.
+
+## Flags
+
+| flag | default | does |
+|---|---|---|
+| `-w/--word LEMMA` | — | add one lemma; repeatable; overrides file/stdin |
+| `-f/--field NAME` | `Greek` | Anki field name in output search string |
+| `--macrons` | off | expand ambiguous-length vowels into macron alternatives |
+| `--strip-trailing-digits` | off | strip trailing homograph digit (`lead2` → `lead`) before matching |
+| `--terminators CHARS` | `" ,. /"` (space, comma, period, NBSP, slash) | chars allowed right after a matched lemma |
+| `--raw` | off | print bare regex, skip the `"field:re:..."` wrapper |
+| `--language NAME` | `greek` | which variant tables to use for `--macrons` |
+| `--list-languages` | — | print known language names, exit |
+
+## Why prefix-anchored, no lookahead
+
+Anki's `re:` search uses the Rust `regex` crate (no lookaround support),
+and field regexes are unanchored by default.
+So a naive `word(?=[ ,])` breaks two ways:
+it's invalid syntax in Anki,
+and without `^` it'd match `word` inside `password` too.
+reglem builds `^(alt1|alt2|...)([terminators]|$)` instead —
+one alternation, explicit anchor, ordinary terminator class.
+When a language excludes a terminator for a specific lemma (see Greek article,
+below), that lemma gets its own terminator group in a separate branch instead —
+still no lookahead.
+
+## Greek macrons
+
+See `docs/greek.md` for the full story —
+why unmarked Greek text is vowel-length-ambiguous,
+and how the macron expansion table is built.
+
+## Greek article
+
+A plain space isn't allowed right after any of the 19 forms of the Greek
+definite article (`ὁ`, `ἡ`, `τό`, `τῶν`, `τούς`, ...): unlike an ordinary
+headword, the article is never immediately followed by running Greek text in
+its own dictionary entry — it's cited with punctuation instead, `ὁ, ἡ, τό` or
+`ὁ/ἡ/τό`. Without the exception, `ὁ` as a lemma would match the start of
+every entry that *begins* with the article, like `ὁ σοφός, -ή, -όν  wise` or
+`ἡ ἀρίστη`, which are entries for other words entirely.
+
+```python
+build_pattern(["ὁ"])
+# matches:      "ὁ, ἡ, τό  the"   "ὁ/ἡ/τό"   "ὁ" (end of field)
+# doesn't match: "ὁ σοφός, -ή, -όν  wise"   "ἡ ἀρίστη"
+```
+
+This is why `/` is in `DEFAULT_TERMINATORS`: it's how a slash-separated
+article citation (`ὁ/ἡ/τό`) still matches. See `docs/greek.md` for the full
+list of forms and why grave-accented running-text forms (`τὸν`, `τὰς`, ...)
+are intentionally excluded.
+
+## Development
+
+```bash
+uv sync
+uv run pytest              # coverage gate: 95%
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright
+uv run pre-commit run --all-files
+```
+
+## Publish
+
+Tag `vX.Y.Z`, push tag.
+CI builds, checks with `twine`, publishes via PyPI Trusted Publishing (OIDC) —
+no stored token.
+
+## License
+
+MIT.

reglem-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+reglem/__init__.py,sha256=g2CeOWuHFrD3Jy0FH5rGgvXZNluEI6kPMwFmOei04ng,1363
+reglem/anki.py,sha256=dkT22d3n2yk4CQAk02EyrBl9dTD6SDcxdji6CMrV2Hs,906
+reglem/build.py,sha256=atfZ5APMUeiC0g7e1MSIi7ciIuau9h6euoHniFbhb78,4525
+reglem/cli.py,sha256=26w-a5KqO0rcVWW6LoTUUuTghW4JKl1Dg0FXBX9Fqgw,4211
+reglem/errors.py,sha256=UBmvL546v-TqNKwdV9GiD4Ief_y8CIwH0-OnqvhNzSs,800
+reglem/normalize.py,sha256=WLJyQz9keS8vvkB5QBcCB8b4v3tD3gSHm4_852CpY5Q,1814
+reglem/options.py,sha256=ZgSI-CRna17vOsVrSQwP-CpR0RRKvAWLnHZ__J9E3_g,2452
+reglem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reglem/variants.py,sha256=U_Ab4NgAWe9D5uVqLFTj9QtLm1Nw2wRMl1o7XA0KiCM,1178
+reglem/languages/__init__.py,sha256=uCeZMS5kywGEWYR_y-ZN150EapV_q6WwqOlrFGrGkYg,886
+reglem/languages/_base.py,sha256=1mwckLbbnvBoTjhcMduPGqaaQ67xlgUaFpZQtBPUSKc,1405
+reglem/languages/greek.py,sha256=TiZ9RAmdx6hc9Gog_GgGQ6hZm6Uf281cIewzHPhJqp4,6451
+reglem-0.1.0.dist-info/METADATA,sha256=uAS19ceQsNJD_5wVSyZ5xzLCSQjp4JUFtQTJgZLiiFk,5540
+reglem-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+reglem-0.1.0.dist-info/entry_points.txt,sha256=rxps2uXLydkzf8naa3CyRTVjl_PmJNLvsG4SJesVuJg,43
+reglem-0.1.0.dist-info/licenses/LICENSE,sha256=24vkaUM_k3XV1XLdmlOXCKxnmR-0sItHGixvySd_4GE,1065
+reglem-0.1.0.dist-info/RECORD,,

reglem-0.1.0.dist-info/WHEEL

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

reglem-0.1.0.dist-info/entry_points.txt

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

reglem-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jaycrick
+
+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.