libtexpr 0.1.0__py3-none-any.whl

libtexpr/__init__.py

@@ -0,0 +1,59 @@
+"""Placeholder expressions for templates written in Latin or Cyrillic.
+
+``Placeholder.parse`` turns ``ПОЛЕ * 2 | функция: арг`` into a :class:`Placeholder`; an
+:class:`Engine` holding your registered functions validates and evaluates it.
+"""
+
+from libtexpr.engine import (
+    Engine,
+    FieldType,
+    Function,
+    Issue,
+    IssueKind,
+    Param,
+)
+from libtexpr.errors import (
+    ArgumentError,
+    DivisionByZeroError,
+    DuplicateFunctionError,
+    EvalError,
+    FunctionError,
+    InvalidNumberError,
+    InvalidSignatureError,
+    LimitExceededError,
+    NotDateError,
+    NotNumericError,
+    ParseError,
+    RegistryError,
+    TexprError,
+    UnexpectedCharacterError,
+    UnexpectedTokenError,
+    UnknownFunctionError,
+)
+from libtexpr.syntax import Placeholder
+
+__all__ = [
+    "ArgumentError",
+    "DivisionByZeroError",
+    "DuplicateFunctionError",
+    "Engine",
+    "EvalError",
+    "FieldType",
+    "Function",
+    "FunctionError",
+    "InvalidNumberError",
+    "InvalidSignatureError",
+    "Issue",
+    "IssueKind",
+    "LimitExceededError",
+    "NotDateError",
+    "NotNumericError",
+    "Param",
+    "ParseError",
+    "Placeholder",
+    "RegistryError",
+    "TexprError",
+    "UnexpectedCharacterError",
+    "UnexpectedTokenError",
+    "UnknownFunctionError",
+]

libtexpr/engine.py

@@ -0,0 +1,349 @@
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+from enum import Enum, auto
+from typing import Any
+
+from libtexpr.errors import (
+    ArgumentError,
+    DuplicateFunctionError,
+    FunctionError,
+    InvalidSignatureError,
+    NotDateError,
+    NotNumericError,
+    TexprError,
+    UnknownFunctionError,
+)
+from libtexpr.syntax import (
+    BinOp,
+    Call,
+    Node,
+    Placeholder,
+    is_field,
+    is_function_name,
+)
+
+# --- Constants ---
+
+
+_SEPARATORS = str.maketrans({" ": None, " ": None, " ": None, ",": "."})
+_NUMBER_RE = re.compile(r"[+-]?([0-9]+\.?[0-9]*|\.[0-9]+)")
+_DATE_RE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")
+
+
+# --- Types ---
+
+
+type Value = str | Decimal | date
+"""The value a pipeline carries: ``str`` for TEXT, ``Decimal`` for NUMBER, ``date`` for DATE."""
+
+
+class FieldType(Enum):
+    """Type of a field value or of a function's input/output.
+
+    The value of each member is the Python class a pipeline carries for that type.
+    """
+
+    TEXT = str
+    NUMBER = Decimal
+    DATE = date
+
+    def _coerce(self, value: Value) -> Value:
+        match self:
+            case FieldType.TEXT:
+                if isinstance(value, Decimal):
+                    result: Value = _format_number(value)
+                elif isinstance(value, date):
+                    result = value.isoformat()
+                else:
+                    result = value
+            case FieldType.NUMBER:
+                result = _to_number(value)
+            case FieldType.DATE:
+                try:
+                    result = (
+                        date.fromisoformat(value.strip())
+                        if isinstance(value, str) and _DATE_RE.fullmatch(value.strip())
+                        else value
+                    )
+                except ValueError:
+                    result = ""
+                if not isinstance(result, date):
+                    raise NotDateError(f"expected a date as YYYY-MM-DD, got {value!r}")
+        return result
+
+
+@dataclass(frozen=True, slots=True)
+class Param:
+    """One positional argument of a registered function.
+
+    ``choices`` lists the allowed literal values; empty means any word, number or field
+    reference. ``default`` is passed when the argument is omitted; ``None`` makes the
+    argument required.
+    """
+
+    choices: frozenset[str] = frozenset()
+    default: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Function:
+    """A function callable in a pipeline (``| name: arg, arg``), with its whole signature.
+
+    ``run(value, args)`` is the code. ``value`` has the Python type of ``input_type``
+    (TEXT ``str``, NUMBER ``Decimal``, DATE ``datetime.date``) and the result must have the
+    type of ``output_type``. ``args`` holds exactly one string per declared :class:`Param`:
+    field references already replaced by their data value, omitted arguments filled with
+    their default. An exception raised by ``run``, or a result of the wrong type, becomes
+    a :class:`FunctionError`.
+
+    ``validate`` type-checks pipelines with ``input_type`` and ``output_type``; ``evaluate``
+    converts the value to ``input_type`` before every call. Pass the function to
+    :meth:`Engine.register`.
+
+    Raises :class:`InvalidSignatureError` when built with a ``name`` that is not a
+    lowercase Latin or Cyrillic word, a required parameter after an optional one, or a default
+    outside its choices.
+    """
+
+    name: str
+    run: Callable[[Any, tuple[str, ...]], Any]
+    input_type: FieldType
+    output_type: FieldType
+    params: tuple[Param, ...] = ()
+
+    def __post_init__(self) -> None:
+        problems: list[str] = []
+        optional_seen = False
+
+        if not is_function_name(self.name):
+            problems.append(f"{self.name!r} is not a lowercase Latin or Cyrillic function name")
+        for index, param in enumerate(self.params, start=1):
+            if param.default is None and optional_seen:
+                problems.append(f"required parameter {index} follows an optional one")
+            if param.choices and param.default is not None and param.default not in param.choices:
+                problems.append(
+                    f"default {param.default!r} of parameter {index} is not among its choices"
+                )
+            optional_seen = optional_seen or param.default is not None
+        if problems:
+            raise InvalidSignatureError("; ".join(problems))
+
+
+class IssueKind(Enum):
+    UNKNOWN_FIELD = auto()
+    UNKNOWN_FUNCTION = auto()
+    TYPE_MISMATCH = auto()
+    BAD_ARGUMENT = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Issue:
+    """One problem found by :meth:`Engine.validate`."""
+
+    kind: IssueKind
+    message: str
+
+
+# --- Value helpers ---
+
+
+def _to_number(value: Value) -> Decimal:
+    """Read a number written the way field values are stored.
+
+    Accepts an optional sign, a comma or dot decimal separator and spaces / NBSP as
+    thousands separators (``"1 000,50"``). Raises :class:`NotNumericError` for anything
+    else; exponents, ``inf`` and ``nan`` are rejected.
+    """
+    cleaned = value.strip().translate(_SEPARATORS) if isinstance(value, str) else ""
+    parsed = Decimal(cleaned) if _NUMBER_RE.fullmatch(cleaned) else value
+    if not isinstance(parsed, Decimal):
+        raise NotNumericError(f"expected a number, got {value!r}")
+    return parsed
+
+
+def _format_number(value: Decimal) -> str:
+    """Plain decimal notation without exponent or trailing zeros: ``2001``, ``15000.5``."""
+    text = format(value, "f")
+    if "." in text:
+        text = text.rstrip("0").rstrip(".")
+    return "0" if text == "-0" else text
+
+
+# --- Argument checks ---
+
+
+def _argument_problems(call: Call, fn: Function) -> list[str]:
+    problems: list[str] = []
+
+    if len(call.args) > len(fn.params):
+        problems.append(
+            f"{call.name!r} takes at most {len(fn.params)} arguments, got {len(call.args)}"
+        )
+    for index, param in enumerate(fn.params):
+        given = call.args[index] if index < len(call.args) else None
+        if given is None and param.default is None:
+            problems.append(f"{call.name!r} misses required argument {index + 1}")
+        elif (
+            given is not None and param.choices and (is_field(given) or given not in param.choices)
+        ):
+            problems.append(
+                f"argument {index + 1} of {call.name!r} must be one of "
+                f"{', '.join(sorted(param.choices))}; got {given!r}"
+            )
+    return problems
+
+
+# --- Validation ---
+
+
+def _check(node: Node, schema: Mapping[str, FieldType], issues: list[Issue]) -> FieldType:
+    result = FieldType.NUMBER
+
+    match node:
+        case str() if is_field(node):
+            result = schema.get(node, FieldType.TEXT)
+            if node not in schema:
+                issues.append(Issue(IssueKind.UNKNOWN_FIELD, f"unknown field {node}"))
+        case str():
+            result = FieldType.TEXT
+        case BinOp():
+            for side, operand in (("left", node.left), ("right", node.right)):
+                if _check(operand, schema, issues) is not FieldType.NUMBER:
+                    issues.append(
+                        Issue(
+                            IssueKind.TYPE_MISMATCH,
+                            f"{side} operand of {node.op.value!r} is not NUMBER",
+                        )
+                    )
+    return result
+
+
+# --- Evaluation ---
+
+
+def _numeric(node: Node, data: Mapping[str, str]) -> Decimal:
+    match node:
+        case Decimal():
+            result = node
+        case BinOp():
+            result = node.op.apply(_numeric(node.left, data), _numeric(node.right, data))
+        case str():
+            result = _to_number(_value(node, data))
+    return result
+
+
+def _value(node: Node, data: Mapping[str, str]) -> Value:
+    match node:
+        case str() if is_field(node):
+            result = data.get(node, "")
+        case str():
+            result = node
+        case Decimal() | BinOp():
+            result = _numeric(node, data)
+    return result
+
+
+# --- Engine ---
+
+
+class Engine:
+    """Registered functions plus the operations that use them.
+
+    Register every function once at startup; ``validate``, ``evaluate`` and
+    ``render_text`` never change the engine and are safe to call from several threads.
+    """
+
+    def __init__(self) -> None:
+        self._functions: dict[str, Function] = {}
+
+    def register(self, function: Function) -> None:
+        """Make ``function`` callable in a pipeline under ``function.name``.
+
+        Raises :class:`DuplicateFunctionError` if the name is already taken.
+        """
+        if function.name in self._functions:
+            raise DuplicateFunctionError(f"function {function.name!r} is already registered")
+        self._functions[function.name] = function
+
+    def validate(self, placeholder: Placeholder, schema: Mapping[str, FieldType]) -> list[Issue]:
+        """Check ``placeholder`` against ``schema`` and the registered functions.
+
+        ``schema`` maps a field name (``"ПОЛЕ"``, ``"ДОЛГ.СУММА"``) to its type.
+
+        Returns every issue found, not only the first; an empty list means it can be
+        evaluated. After an unknown function the type flowing through the pipeline is
+        left unchanged, so later steps are still checked.
+        """
+        issues: list[Issue] = []
+        current = _check(placeholder.expr, schema, issues)
+
+        for call in placeholder.pipeline:
+            fn = self._functions.get(call.name)
+            if fn is None:
+                issues.append(Issue(IssueKind.UNKNOWN_FUNCTION, f"unknown function {call.name!r}"))
+            else:
+                if current is not fn.input_type:
+                    issues.append(
+                        Issue(
+                            IssueKind.TYPE_MISMATCH,
+                            f"{call.name!r} expects {fn.input_type.name}, got {current.name}",
+                        )
+                    )
+                issues.extend(
+                    Issue(IssueKind.BAD_ARGUMENT, p) for p in _argument_problems(call, fn)
+                )
+                current = fn.output_type
+            for arg in call.args:
+                _check(arg, schema, issues)
+        return issues
+
+    def evaluate(self, placeholder: Placeholder, data: Mapping[str, str]) -> str:
+        """Compute ``placeholder`` for one row of ``data`` (same keys → raw value).
+
+        The result is always text: a number is written without exponent, a date as
+        ``YYYY-MM-DD``. A missing field is ``""``; where a number or date is needed it raises an :class:`EvalError`. Math runs on
+        :class:`~decimal.Decimal`. Raises an :class:`EvalError` subclass.
+        """
+        value = _value(placeholder.expr, data)
+        for call in placeholder.pipeline:
+            value = self._call(call, value, data)
+        return str(FieldType.TEXT._coerce(value))
+
+    def render_text(self, text: str, data: Mapping[str, str]) -> str:
+        """Replace every ``[...]`` in ``text`` with its value for ``data``.
+
+        A placeholder that fails to parse or evaluate is left exactly as written.
+        """
+
+        def replace(match: re.Match[str]) -> str:
+            try:
+                result = self.evaluate(Placeholder.parse(match.group(1)), data)
+            except TexprError:
+                result = match.group(0)
+            return result
+
+        return Placeholder.PATTERN.sub(replace, text)
+
+    def _call(self, call: Call, value: Value, data: Mapping[str, str]) -> Value:
+        fn = self._functions.get(call.name)
+        if fn is None:
+            raise UnknownFunctionError(f"unknown function {call.name!r}")
+        problems = _argument_problems(call, fn)
+        if problems:
+            raise ArgumentError("; ".join(problems))
+
+        given = tuple(data.get(a, "") if is_field(a) else a for a in call.args)
+        defaults = tuple(p.default for p in fn.params[len(given) :] if p.default is not None)
+        typed = fn.input_type._coerce(value)
+        try:
+            result = fn.run(typed, given + defaults)
+        except Exception as e:
+            raise FunctionError(f"{call.name!r} failed: {e}") from e
+        if not isinstance(result, fn.output_type.value):
+            raise FunctionError(
+                f"{call.name!r} returned {type(result).__name__}, declared {fn.output_type.name}"
+            )
+        return result

libtexpr/errors.py

@@ -0,0 +1,81 @@
+# --- Base ---
+
+
+class TexprError(Exception):
+    """Base class of every error raised by libtexpr."""
+
+
+# --- Parse errors ---
+
+
+class ParseError(TexprError):
+    """The placeholder text does not match the grammar.
+
+    ``position`` is the 0-based character offset where parsing failed.
+    """
+
+    def __init__(self, message: str, position: int) -> None:
+        super().__init__(f"{message} at position {position}")
+        self.position = position
+
+
+class UnexpectedCharacterError(ParseError):
+    """A character no token can start with, e.g. ``$`` or a letter outside Latin and Cyrillic."""
+
+
+class UnexpectedTokenError(ParseError):
+    """A valid token where the grammar does not allow it, e.g. an unclosed ``(``."""
+
+
+class LimitExceededError(ParseError):
+    """The placeholder is longer than 500 characters or nests parentheses / unary minus deeper than 20 levels."""
+
+
+class InvalidNumberError(ParseError):
+    """A digit sequence that is not a number, e.g. ``1.2.3``."""
+
+
+# --- Eval errors ---
+
+
+class EvalError(TexprError):
+    """A parsed placeholder could not be evaluated against the given data."""
+
+
+class UnknownFunctionError(EvalError):
+    """The pipeline calls a function that is not registered."""
+
+
+class ArgumentError(EvalError):
+    """A function got too many arguments, misses a required one, or got a value outside its choices."""
+
+
+class NotNumericError(EvalError):
+    """A math operand did not resolve to a number."""
+
+
+class NotDateError(EvalError):
+    """A value that must be a date is not written as ``YYYY-MM-DD``."""
+
+
+class DivisionByZeroError(EvalError):
+    """The right operand of ``/`` is zero."""
+
+
+class FunctionError(EvalError):
+    """A registered function raised; the original exception is in ``__cause__``."""
+
+
+# --- Registry errors ---
+
+
+class RegistryError(TexprError):
+    """A function registration was rejected."""
+
+
+class DuplicateFunctionError(RegistryError):
+    """A function with the same name is already registered."""
+
+
+class InvalidSignatureError(RegistryError):
+    """The function name cannot be written in a placeholder, or its parameters are inconsistent."""

libtexpr/syntax.py

@@ -0,0 +1,334 @@
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from enum import Enum, auto
+from functools import lru_cache
+from typing import ClassVar, Self
+
+from libtexpr.errors import (
+    DivisionByZeroError,
+    InvalidNumberError,
+    LimitExceededError,
+    NotNumericError,
+    UnexpectedCharacterError,
+    UnexpectedTokenError,
+)
+
+# --- AST ---
+
+
+class Op(Enum):
+    ADD = "+"
+    SUB = "-"
+    MUL = "*"
+    DIV = "/"
+
+    def apply(self, left: Decimal, right: Decimal) -> Decimal:
+        try:
+            match self:
+                case Op.ADD:
+                    result = left + right
+                case Op.SUB:
+                    result = left - right
+                case Op.MUL:
+                    result = left * right
+                case Op.DIV:
+                    if right == 0:
+                        raise DivisionByZeroError("division by zero")
+                    result = left / right
+        except ArithmeticError as e:
+            raise NotNumericError(f"result of {self.value!r} is out of range") from e
+        return result
+
+
+# What the parser puts in the tree, by what was written in the placeholder:
+#   ДОЛГ.СУММА  -> "ДОЛГ.СУММА"          field (told from a word by its uppercase first letter)
+#   краткий     -> "краткий"             literal word
+#   2.5         -> Decimal("2.5")        number
+#   ПОЛЕ * 2    -> BinOp(...)            arithmetic
+type Node = Decimal | str | BinOp
+
+
+@dataclass(frozen=True, slots=True)
+class BinOp:
+    op: Op
+    left: Node
+    right: Node
+
+
+@dataclass(frozen=True, slots=True)
+class Call:
+    name: str
+    args: tuple[str, ...]
+
+
+# --- Placeholder ---
+
+
+@dataclass(frozen=True, slots=True)
+class Placeholder:
+    """A parsed placeholder. Build it with :meth:`parse`, never directly.
+
+    ``MAX_LENGTH`` and ``MAX_NESTING`` are the limits :meth:`parse` enforces, and ``PATTERN``
+    matches one bracketed placeholder in a text (group 1 is the text inside the brackets).
+    """
+
+    # Parentheses nest at most MAX_NESTING deep and a flat chain of operators fits in MAX_LENGTH,
+    # so the recursive parser and evaluator stay far below Python's recursion limit.
+    MAX_LENGTH: ClassVar[int] = 500
+    MAX_NESTING: ClassVar[int] = 20
+
+    PATTERN: ClassVar[re.Pattern[str]] = re.compile(r"\[([^\[\]]+)\]")
+
+    expr: Node
+    pipeline: tuple[Call, ...]
+
+    # Cached because a template is parsed again for every row it is rendered with.
+    @classmethod
+    @lru_cache(maxsize=2048)
+    def parse(cls, src: str) -> Self:
+        """Parse the text inside one ``[...]``, without the brackets.
+
+        Field names are UPPERCASE and may contain dots (``ПОЛЕ``, ``DEBT.AMOUNT``); function
+        names and bare words are lowercase. Letters are Latin or Cyrillic. Raises a :class:`ParseError`
+        subclass carrying the failing position. A text longer than ``MAX_LENGTH``, or
+        parentheses and unary minus nested deeper than ``MAX_NESTING``, raises
+        :class:`LimitExceededError`.
+        """
+        if len(src) > cls.MAX_LENGTH:
+            raise LimitExceededError(
+                f"placeholder longer than {cls.MAX_LENGTH} characters", cls.MAX_LENGTH
+            )
+        expr, pipeline = _Parser(_Token.tokenize(src)).placeholder()
+        return cls(expr, pipeline)
+
+    @staticmethod
+    def extract(text: str) -> list[str]:
+        """Return the inner text of every ``[...]`` in ``text``, in order, without parsing it.
+
+        Nested brackets are not supported: the innermost pair is taken. Feed each result to
+        :meth:`parse`; extracting first lets you report a syntax error per placeholder.
+        """
+        return Placeholder.PATTERN.findall(text)
+
+
+# --- Characters ---
+
+
+# Latin (with its accented letters) and Cyrillic: the alphabets names may be written in.
+_LETTER = re.compile(r"[A-Za-z\u00C0-\u024F\u0400-\u052F]")
+
+
+def _is_upper(ch: str) -> bool:
+    return ch.isupper() and _LETTER.match(ch) is not None
+
+
+def _is_lower(ch: str) -> bool:
+    return ch.islower() and _LETTER.match(ch) is not None
+
+
+def _is_digit(ch: str) -> bool:
+    return "0" <= ch <= "9"
+
+
+def is_field(text: str) -> bool:
+    return _is_upper(text[0])
+
+
+def is_function_name(text: str) -> bool:
+    return text != "" and _is_lower(text[0]) and all(_is_lower(c) or c == "_" for c in text)
+
+
+# --- Tokens ---
+
+
+class _Kind(Enum):
+    EOF = auto()
+    UPPER = auto()
+    LOWER = auto()
+    NUMBER = auto()
+    PIPE = auto()
+    COLON = auto()
+    COMMA = auto()
+    PLUS = auto()
+    MINUS = auto()
+    STAR = auto()
+    SLASH = auto()
+    LPAREN = auto()
+    RPAREN = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class _Token:
+    PUNCTUATION: ClassVar[dict[str, _Kind]] = {
+        "|": _Kind.PIPE,
+        ":": _Kind.COLON,
+        ",": _Kind.COMMA,
+        "+": _Kind.PLUS,
+        "-": _Kind.MINUS,
+        "*": _Kind.STAR,
+        "/": _Kind.SLASH,
+        "(": _Kind.LPAREN,
+        ")": _Kind.RPAREN,
+    }
+
+    kind: _Kind
+    text: str
+    position: int
+
+    @classmethod
+    def tokenize(cls, src: str) -> list[Self]:
+        tokens: list[_Token] = []
+        i = 0
+
+        while i < len(src):
+            ch = src[i]
+            end = i + 1
+            if ch.isspace():
+                pass
+            elif ch in cls.PUNCTUATION:
+                tokens.append(cls(cls.PUNCTUATION[ch], ch, i))
+            elif _is_digit(ch):
+                end = cls._scan(src, i, lambda c: _is_digit(c) or c == ".")
+                tokens.append(cls(_Kind.NUMBER, src[i:end], i))
+            elif _is_upper(ch):
+                end = cls._scan(src, i, lambda c: _is_upper(c) or _is_digit(c) or c in "_.")
+                tokens.append(cls(_Kind.UPPER, src[i:end], i))
+            elif _is_lower(ch):
+                end = cls._scan(src, i, lambda c: _is_lower(c) or c == "_")
+                tokens.append(cls(_Kind.LOWER, src[i:end], i))
+            else:
+                raise UnexpectedCharacterError(f"unexpected character {ch!r}", i)
+            i = end
+
+        tokens.append(cls(_Kind.EOF, "", len(src)))
+        return tokens
+
+    def number(self) -> Decimal:
+        try:
+            return Decimal(self.text)
+        except InvalidOperation as e:
+            raise InvalidNumberError(f"invalid number {self.text!r}", self.position) from e
+
+    def expected(self, what: str) -> UnexpectedTokenError:
+        got = repr(self.text) if self.kind is not _Kind.EOF else "end of placeholder"
+        return UnexpectedTokenError(f"expected {what}, got {got}", self.position)
+
+    @staticmethod
+    def _scan(src: str, start: int, accept: Callable[[str], bool]) -> int:
+        end = start
+        while end < len(src) and accept(src[end]):
+            end += 1
+        return end
+
+
+# --- Parser ---
+
+
+class _Parser:
+    _ADDITIVE: ClassVar[dict[_Kind, Op]] = {_Kind.PLUS: Op.ADD, _Kind.MINUS: Op.SUB}
+    _MULTIPLICATIVE: ClassVar[dict[_Kind, Op]] = {_Kind.STAR: Op.MUL, _Kind.SLASH: Op.DIV}
+
+    def __init__(self, tokens: list[_Token]) -> None:
+        self._tokens = tokens
+        self._pos = 0
+        self._depth = 0
+
+    def placeholder(self) -> tuple[Node, tuple[Call, ...]]:
+        pipeline: list[Call] = []
+        expr = self._expr()
+        while self._take(_Kind.PIPE):
+            pipeline.append(self._call())
+        self._expect(_Kind.EOF, "'|' or end of placeholder")
+        return expr, tuple(pipeline)
+
+    @property
+    def _peek(self) -> _Token:
+        return self._tokens[self._pos]
+
+    def _advance(self) -> _Token:
+        token = self._peek
+        self._pos = min(self._pos + 1, len(self._tokens) - 1)
+        return token
+
+    def _take(self, kind: _Kind) -> bool:
+        taken = self._peek.kind is kind
+        if taken:
+            self._advance()
+        return taken
+
+    def _expect(self, kind: _Kind, what: str) -> _Token:
+        token = self._peek
+        if token.kind is not kind:
+            raise token.expected(what)
+        return self._advance()
+
+    def _expr(self) -> Node:
+        node = self._term()
+        while self._peek.kind in self._ADDITIVE:
+            node = BinOp(self._ADDITIVE[self._advance().kind], node, self._term())
+        return node
+
+    def _term(self) -> Node:
+        node = self._factor()
+        while self._peek.kind in self._MULTIPLICATIVE:
+            node = BinOp(self._MULTIPLICATIVE[self._advance().kind], node, self._factor())
+        return node
+
+    def _enter(self, token: _Token) -> None:
+        self._depth += 1
+        if self._depth > Placeholder.MAX_NESTING:
+            raise LimitExceededError(
+                f"nesting deeper than {Placeholder.MAX_NESTING} levels", token.position
+            )
+
+    def _factor(self) -> Node:
+        node: Node
+        token = self._advance()
+
+        match token.kind:
+            case _Kind.MINUS:
+                self._enter(token)
+                node = BinOp(Op.SUB, Decimal(0), self._factor())
+                self._depth -= 1
+            case _Kind.LPAREN:
+                self._enter(token)
+                node = self._expr()
+                self._expect(_Kind.RPAREN, "')'")
+                self._depth -= 1
+            case _Kind.NUMBER:
+                node = token.number()
+            case _Kind.UPPER:
+                node = token.text
+            case _Kind.LOWER:
+                node = token.text
+            case _:
+                raise token.expected("a value")
+        return node
+
+    def _call(self) -> Call:
+        args: list[str] = []
+        name = self._expect(_Kind.LOWER, "function name").text
+
+        if self._take(_Kind.COLON):
+            args.append(self._arg())
+            while self._take(_Kind.COMMA):
+                args.append(self._arg())
+        return Call(name, tuple(args))
+
+    def _arg(self) -> str:
+        arg: str
+        token = self._advance()
+
+        match token.kind:
+            case _Kind.UPPER:
+                arg = token.text
+            case _Kind.LOWER:
+                arg = token.text
+            case _Kind.NUMBER:
+                token.number()
+                arg = token.text
+            case _:
+                raise token.expected("an argument")
+        return arg

libtexpr-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: libtexpr
+Version: 0.1.0
+Summary: Placeholder expression engine for templates: [FIELD + 1 | function: arg] in Cyrillic or Latin
+Keywords: template,placeholder,expression,parser,cyrillic,latin
+Author: StafLoker
+Author-email: StafLoker <dev.stafloker@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/StafLoker/libtexpr
+Project-URL: Bug Tracker, https://github.com/StafLoker/libtexpr/issues
+Description-Content-Type: text/markdown
+
+<div align="center">
+   <h1><b>libtexpr</b></h1>
+   <p><i>~ Placeholder expressions for templates ~</i></p>
+</div>
+
+libtexpr is a Python library that parses and evaluates placeholders such as `[ДОЛГ.СУММА * 2 | деньги: кратко]` or `[DEBT.AMOUNT * 2 | money: short]`. It is for applications that fill data into document templates and let template authors write fields and functions in their own language: Cyrillic or Latin.
+
+The library reads and checks a placeholder, then evaluates it for the given data. The functions themselves (declension, amount in words, date format) are written by the application: the library only calls them in order.
+
+## Quick start
+
+```bash
+uv add libtexpr
+```
+
+The function `деньги` formats a number; the placeholder computes a sum and applies the function.
+
+```python
+from decimal import Decimal
+
+from libtexpr import Engine, FieldType, Function, Param, Placeholder
+
+
+def money(value: Decimal, args: tuple[str, ...]) -> str:
+    text = f"{value:,.2f}".replace(",", " ").replace(".", ",")
+    return text + (" руб." if args == ("кратко",) else " рублей")
+
+
+engine = Engine()
+engine.register(
+    Function(
+        "деньги",
+        money,
+        FieldType.NUMBER,
+        FieldType.TEXT,
+        (Param(frozenset({"кратко", "полно"}), default="кратко"),),
+    )
+)
+
+placeholder = Placeholder.parse("ДОЛГ.СУММА * 2 | деньги")
+schema = {"ДОЛГ.СУММА": FieldType.NUMBER}
+data = {"ДОЛГ.СУММА": "1 000,5"}
+
+print(engine.validate(placeholder, schema))
+print(engine.evaluate(placeholder, data))
+print(engine.render_text("Сумма: [ДОЛГ.СУММА | деньги: полно]", data))
+```
+
+Output:
+
+```
+[]
+2 001,00 руб.
+Сумма: 1 000,50 рублей
+```
+
+The empty list on the first line means there are no problems.
+
+## Syntax
+
+A placeholder is a **value** followed by a chain of functions separated by `|`:
+
+```
+[ value | function | function: argument, argument ]
+```
+
+| Placeholder                              | What it does                                       |
+| ---------------------------------------- | -------------------------------------------------- |
+| `[ПОЛЕ]`                                 | takes the value of a field                         |
+| `[ДОЛГ.СУММА]`, `[А.Б.В]`                | a field name may contain dots, e.g. as a hierarchy |
+| `[родился]`                              | a word as plain text                               |
+| `[100]`, `[-ПОЛЕ]`                       | a number                                           |
+| `[(ДОЛГ.СУММА + ПЕНИ.СУММА) * 0.01]`     | arithmetic: `+ - * /` and parentheses              |
+| `[ФИО.ПОЛНОЕ \| падеж: род]`             | a function with an argument                        |
+| `[ФИО.ПОЛНОЕ \| падеж: род \| инициалы]` | a chain: the result of one function feeds the next |
+| `[ЧИСЛО.ДЕЛ \| число: текст, женский]`   | several arguments separated by commas              |
+| `[родился \| согласуй: ФИО.ПОЛНОЕ]`      | a function argument can be a field                 |
+| `[DEBT.AMOUNT * 2 \| money: short]`      | the same syntax in Latin                           |
+
+Rules:
+
+- A name in UPPERCASE letters is a field (`ПОЛЕ`, `DEBT`, `ДОЛГ.СУММА`, `DEBT.AMOUNT`). Functions and words are lowercase. Only Cyrillic and Latin letters are allowed; a name starts with a letter.
+- An argument is a word, a number or a field. There is no arithmetic inside an argument.
+- Arithmetic (`+ - * /`) is allowed only in the value, before the first function: the result of a function cannot go back into arithmetic. Compute first, then apply functions: `[А.Б * 2 | округлить: 1]`.
+- In the template text the decimal part is written with a dot (`0.5`), because a comma separates arguments. In data a comma is accepted: `"1 000,5"`.
+- There are no quoted strings, conditions, loops or nested calls `f(g(x))`: use the chain `x | g | f` instead.
+
+A syntax error is a `ParseError` carrying the character position: `UnexpectedCharacterError` (for example `$` or a Greek letter), `UnexpectedTokenError` (for example an unclosed parenthesis), `InvalidNumberError`, `LimitExceededError`.
+
+## Functions and types
+
+A function is described by `Function(name, run, input_type, output_type, params)`:
+
+- `run(value, args)` is the code of the function. `args` holds exactly one string per `Param`: an omitted argument is replaced by its default, a field by its value from `data`.
+- `Param(choices, default)` is one argument: the allowed words (empty means any) and the default value (`None` makes the argument required).
+- A mistake in the description (a name that is not lowercase Latin or Cyrillic letters, a required parameter after an optional one) raises `InvalidSignatureError` as soon as the `Function` is created.
+
+The value keeps its type between functions:
+
+| `FieldType` | Python object     |
+| ----------- | ----------------- |
+| `TEXT`      | `str`             |
+| `NUMBER`    | `decimal.Decimal` |
+| `DATE`      | `datetime.date`   |
+
+A `NUMBER → NUMBER` function receives and returns a `Decimal`. Before each call `evaluate` converts the value to the input type: text to a number (`NotNumericError`) and to an ISO 8601 date (`NotDateError`). The result of `evaluate` is always text. An exception inside `run`, or a result of the wrong type, becomes a `FunctionError`.
+
+`validate` is stricter than `evaluate`: the type of the value must match the input type of the function. It returns **all** the problems it finds (`UNKNOWN_FIELD`, `UNKNOWN_FUNCTION`, `TYPE_MISMATCH`, `BAD_ARGUMENT`), so the template author learns about every mistake at once.
+
+## Limits
+
+- A placeholder is at most 500 characters (`Placeholder.MAX_LENGTH`), and parentheses and unary minus nest at most 20 levels (`Placeholder.MAX_NESTING`); beyond that, `LimitExceededError`.
+- Arithmetic runs in `Decimal`: `0.1 + 0.2` gives exactly `0.3`; division is exact to 28 significant digits.
+
+## Requirements
+
+Python 3.12 or newer. No dependencies.
+
+## Development
+
+```bash
+make test         # tests
+make lint         # style check
+make format       # auto-format
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[Apache License 2.0](LICENSE)

libtexpr-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+libtexpr/__init__.py,sha256=MzrJbjM_c_bEC0fvlJWmlDcsNdZVEQqQd_VCm0uGel4,1301
+libtexpr/engine.py,sha256=DFumk7xCkluxHqJwITYcvqyoc2z12pyRNpnTJLVtMx8,12439
+libtexpr/errors.py,sha256=SykjeNbAYlDDkKlgihAddeUi_RDZgtIwkmnnrWA_lm4,2124
+libtexpr/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+libtexpr/syntax.py,sha256=kks1FdToz2K7A_ngipCwZsT0XwcVylAV408r5p4PV3M,10165
+libtexpr-0.1.0.dist-info/licenses/LICENSE,sha256=tQ4z49YJlXFtzCyaaAAxxofwkPwiGGEmnmj5dFL8Wok,11340
+libtexpr-0.1.0.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
+libtexpr-0.1.0.dist-info/METADATA,sha256=tbH_dpJg_58jGc86UHkBG1GMuQmbqlefTW74ajy1UE8,7255
+libtexpr-0.1.0.dist-info/RECORD,,

libtexpr-0.1.0.dist-info/WHEEL

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

libtexpr-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 StafLoker
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.