sel-lang 0.3.0__py3-none-any.whl

sel/__init__.py

@@ -0,0 +1,132 @@
+"""SEL — a small expression language for validation rules.
+
+One rule file evaluates identically on JavaScript, PHP, C++23, Common Lisp and
+Python. Exact decimal arithmetic, no floating point, no truthiness.
+
+    from sel import compile, evaluate, Value, SelError
+
+    program = compile('TOTAL > CREDIT_LIMIT')
+    program.dependencies()                      # ['CREDIT_LIMIT', 'TOTAL']
+    evaluate('1 + 2').as_text()                 # '3'
+
+Public host interface. See spec/SPEC.md §8.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import builtins as _builtins   # noqa: F401  registers the function table
+from .errors import Pos, SelError
+from .eval import Context, eval_node
+from .parser import Node, parse
+from .registry import names as _names
+from .value import BIN, BOOL, NONE, TEXT, Value
+
+__all__ = [
+    'compile', 'evaluate', 'Program', 'Value', 'SelError', 'Context', 'Pos',
+    'function_names', 'NONE', 'TEXT', 'BIN', 'BOOL', '__version__',
+]
+
+__version__ = '0.3.0'
+
+
+class Program:
+    __slots__ = ('source', 'ast')
+
+    def __init__(self, source: str, ast: Node) -> None:
+        self.source = source
+        self.ast = ast
+
+    def run(self, context: Any = None) -> Value:
+        """`context` may be a Value, a plain dict, or omitted. Returns a Value;
+        the context is mutated in place by any assignments the program performs.
+        """
+        root = context if isinstance(context, Value) else Value.from_native(context or {})
+        return eval_node(self.ast, Context(root))
+
+    def dependencies(self) -> list[str]:
+        """Every variable the program reads without having assigned it first,
+        found statically. Only possible because SEL has no dynamic symbol
+        operator; this is what tells a frontend which inputs should re-trigger
+        which rule.
+        """
+        reads: set[str] = set()
+        assigned: set[str] = set()
+        _collect(self.ast, frozenset(), reads, assigned)
+        return sorted(n for n in reads if n not in assigned)
+
+
+def _collect(node: Node | None, bound: frozenset, reads: set, assigned: set) -> None:
+    if node is None:
+        return
+    t = node.t
+
+    if t == 'var':
+        if node.name not in bound:
+            reads.add(node.name)
+        return
+
+    if t == 'assign':
+        target = node.target
+        while target.t == 'index':
+            _collect(target.idx, bound, reads, assigned)
+            target = target.obj
+        # `A = x` defines A; `A[k] = x` and `A += x` also read it.
+        if node.target.t != 'var' or node.op != '=':
+            if target.name not in bound:
+                reads.add(target.name)
+        assigned.add(target.name)
+        _collect(node.value, bound, reads, assigned)
+        return
+
+    if t == 'call':
+        # An aggregate's three-argument form binds its second argument as a name
+        # for the duration of the third.
+        if node.spec and node.spec.binds and len(node.args) == 3 and node.args[1].t == 'var':
+            _collect(node.args[0], bound, reads, assigned)
+            inner = bound | {node.args[1].name, '_K'}
+            _collect(node.args[2], inner, reads, assigned)
+            return
+        if node.spec and node.spec.binds and len(node.args) == 2:
+            _collect(node.args[0], bound, reads, assigned)
+            inner = bound | {'_', '_K'}
+            _collect(node.args[1], inner, reads, assigned)
+            return
+        for a in node.args:
+            _collect(a, bound, reads, assigned)
+        return
+
+    if t in ('seq', 'list'):
+        for item in node.items:
+            _collect(item, bound, reads, assigned)
+        return
+
+    if t == 'index':
+        _collect(node.obj, bound, reads, assigned)
+        _collect(node.idx, bound, reads, assigned)
+        return
+
+    if t == 'bin':
+        _collect(node.l, bound, reads, assigned)
+        _collect(node.r, bound, reads, assigned)
+        return
+
+    if t == 'un':
+        _collect(node.x, bound, reads, assigned)
+        return
+
+
+def compile(source: str) -> Program:   # noqa: A001 - mirrors compile() in every host
+    """Parse and check `source`. Raises SelError on a syntax error, an unknown
+    function name or a wrong argument count — all three are compile time.
+    """
+    return Program(source, parse(source))
+
+
+def evaluate(source: str, context: Any = None) -> Value:
+    return compile(source).run(context)
+
+
+def function_names() -> list[str]:
+    return _names()

sel/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from ._cli import main
+
+if __name__ == '__main__':
+    sys.exit(main())

sel/_cli.py

@@ -0,0 +1,85 @@
+"""SEL command line: evaluate an expression, a file, or start a REPL.
+
+    sel -e 'EXPR'          evaluate and print
+    sel file.sel           evaluate a file
+    sel --deps -e 'EXPR'   print the variables the expression reads
+    sel --functions        list the function table
+    sel                    REPL, keeping one context across lines
+
+Also reachable as `python -m sel`, which is the spelling to prefer when the
+`sel` console script collides with another package's — the JS package installs
+a `sel` command too.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import SelError, Value, compile as sel_compile, function_names
+
+
+def show(v: Value) -> str:
+    if v.size() == 0:
+        if v.kind == 'TEXT':
+            return v.scalar
+        if v.kind == 'BOOL':
+            return 'TRUE' if v.scalar else 'FALSE'
+        if v.kind == 'BIN':
+            return f'bin:{v.dump()[1:]}'
+    return v.dump()
+
+
+def _report(e: SelError) -> None:
+    sys.stderr.write(f'{e.code} at line {e.line} column {e.col}: {e.message}\n')
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    want_deps = '--deps' in argv
+    args = [a for a in argv if a != '--deps']
+
+    if args and args[0] == '--functions':
+        print('\n'.join(function_names()))
+        return 0
+
+    source = None
+    if args and args[0] == '-e':
+        if len(args) < 2:
+            sys.stderr.write('sel: -e needs an expression\n')
+            return 2
+        source = args[1]
+    elif args:
+        try:
+            with open(args[0], encoding='utf-8') as fh:
+                source = fh.read()
+        except OSError as e:
+            sys.stderr.write(f'sel: {e}\n')
+            return 2
+
+    if source is not None:
+        try:
+            program = sel_compile(source)
+            if want_deps:
+                print('\n'.join(program.dependencies()))
+            else:
+                print(show(program.run(Value.none())))
+        except SelError as e:
+            _report(e)
+            return 1
+        return 0
+
+    # REPL: one context for the whole session, so assignments persist.
+    root = Value.none()
+    while True:
+        try:
+            line = input('sel> ')
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 0
+        if not line.strip():
+            continue
+        try:
+            print(show(sel_compile(line).run(root)))
+        except SelError as e:
+            _report(e)
+    return 0

sel/builtins/__init__.py

@@ -0,0 +1,15 @@
+"""Every built-in module is imported here for its side effect: each registers
+its functions in the table in sel/registry.py.
+
+The table must be complete before any source is parsed, because an unknown
+function name is a compile-time error. sel/__init__.py imports this module
+first, for exactly that reason.
+"""
+
+from . import control      # noqa: F401
+from . import structure    # noqa: F401
+from . import aggregate    # noqa: F401
+from . import text         # noqa: F401
+from . import number       # noqa: F401
+from . import binary       # noqa: F401
+from . import regex        # noqa: F401

sel/builtins/aggregate.py

@@ -0,0 +1,110 @@
+"""Aggregates. These are why SEL needs no loop: each evaluates one argument node
+once per element, which is the same move IF makes, repeated.
+"""
+
+from .. import decimal as D
+from ..registry import define
+from ..value import NONE, Value
+
+
+def shape(args):
+    """Two-argument form binds `_`; three-argument form takes a bare identifier
+    as the binder, checked by inspecting the AST node the caller handed us.
+    """
+    if args.count() == 3:
+        return args.symbol(1), args.node(2)
+    return '_', args.node(1)
+
+
+def elements(value):
+    """A scalar with no children behaves as a one-element list containing itself,
+    consistent with scalar context (§3.2). A NONE with no children is genuinely
+    empty — that is what FILTER returns when nothing matched, and ALL over it
+    must be TRUE rather than a scalar-context failure.
+    """
+    if value.size() > 0:
+        return value.entries()
+    return [] if value.kind == NONE else [('1', value)]
+
+
+def walk(args, ctx, visit):
+    """Runs `visit` per element with the binder and _K in scope. Returning a
+    value from `visit` stops the walk and becomes the result.
+
+    The frame is popped in a finally, so a body that raises does not leave the
+    binder in scope for whatever runs next.
+    """
+    binder, body = shape(args)
+    for key, item in elements(args.val(0)):
+        ctx.push_frame({binder: item, '_K': Value.text(key)})
+        try:
+            result = visit(args.eval_node(body), key, item, body)
+        finally:
+            ctx.pop_frame()
+        if result is not None:
+            return result
+    return None
+
+
+def _all(args, ctx):
+    short = walk(args, ctx,
+                 lambda r, k, i, body: None if r.as_bool(body.pos) else Value.bool(False))
+    return short if short is not None else Value.bool(True)
+
+
+def _any(args, ctx):
+    short = walk(args, ctx,
+                 lambda r, k, i, body: Value.bool(True) if r.as_bool(body.pos) else None)
+    return short if short is not None else Value.bool(False)
+
+
+def _map(args, ctx):
+    out = []
+
+    def visit(r, k, i, body):
+        out.append(r.clone())
+        return None
+
+    walk(args, ctx, visit)
+    return Value.list(out)
+
+
+def _filter(args, ctx):
+    """The one aggregate that preserves keys — a filtered list should still be
+    addressable the way the original was.
+    """
+    out = Value.none()
+
+    def visit(r, key, item, body):
+        if r.as_bool(body.pos):
+            out.set(key, item.clone())
+        return None
+
+    walk(args, ctx, visit)
+    return out
+
+
+def _sum(args, ctx):
+    total = [D.ZERO]
+
+    def visit(r, k, i, body):
+        total[0] = D.add(total[0], r.as_decimal(body.pos))
+        return None
+
+    walk(args, ctx, visit)
+    return Value.num(total[0])
+
+
+def _join(args, ctx):
+    """Strict, not an aggregate: its second argument is a separator, not a body."""
+    sep = args.text(1)
+    parts = [item.as_text(args.pos_of(0)) for _, item in elements(args.val(0))]
+    return Value.text(sep.join(parts))
+
+
+define('ALL', 2, 3, lazy=True, binds=True, fn=_all)
+define('ANY', 2, 3, lazy=True, binds=True, fn=_any)
+define('MAP', 2, 3, lazy=True, binds=True, fn=_map)
+define('FILTER', 2, 3, lazy=True, binds=True, fn=_filter)
+define('SUM', 2, 3, lazy=True, binds=True, fn=_sum)
+define('JOIN', 2, 2, fn=_join)

sel/builtins/binary.py

@@ -0,0 +1,149 @@
+"""Binary built-ins.
+
+base64 and CRC32 are hand-written rather than taken from `base64` and `zlib`.
+The stdlib versions are lenient in ways the spec is not — `base64.b64decode`
+ignores characters outside the alphabet unless validate=True, and even then
+accepts some padding the other hosts reject — and agreeing with three other
+implementations on exactly which inputs are E_BAD_ARG matters more here than
+saving twenty lines. `zlib.crc32` would in fact agree, but is left alone so that
+the four cores can be read against each other.
+"""
+
+import re
+
+from ..errors import fail
+from ..registry import define
+from ..utf8 import bytes_to_hex, decode_utf8
+from ..value import Value
+
+define('BLEN', 1, 1, fn=lambda a, ctx: Value.int(len(a.bytes(0))))
+define('TO_UTF8', 1, 1, fn=lambda a, ctx: Value.bin(a.bytes(0)))
+define('FROM_UTF8', 1, 1,
+       fn=lambda a, ctx: Value.text(decode_utf8(a.bytes(0), a.pos_of(0))))
+define('TO_HEX', 1, 1, fn=lambda a, ctx: Value.text(bytes_to_hex(a.bytes(0))))
+
+# .fullmatch() for the reason in sel/decimal.py. This one happens to be safe
+# with .match() because the slice is always exactly two characters, but the
+# safety is accidental and the next edit would lose it.
+_HEX_PAIR = re.compile(r'^[0-9a-fA-F]{2}$')
+
+
+def _from_hex(a, ctx):
+    s = a.text(0)
+    if len(s) % 2 != 0:
+        fail('E_BAD_ARG', 'FROM_HEX needs an even number of digits', a.pos_of(0))
+    out = bytearray(len(s) // 2)
+    for i in range(len(out)):
+        pair = s[i * 2:i * 2 + 2]
+        # Checked against an explicit ASCII class, not int(pair, 16): int()
+        # accepts Unicode digits, so "٣٣" would decode rather than fail.
+        if not _HEX_PAIR.fullmatch(pair):
+            fail('E_BAD_ARG', f'FROM_HEX: "{pair}" is not hex', a.pos_of(0))
+        out[i] = int(pair, 16)
+    return Value.bin(bytes(out))
+
+
+define('FROM_HEX', 1, 1, fn=_from_hex)
+
+_B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+_B64_INDEX = {ch: i for i, ch in enumerate(_B64)}
+
+
+def _encode_base64(a, ctx):
+    b = a.bytes(0)
+    out = []
+    for i in range(0, len(b), 3):
+        n = (b[i] << 16) \
+            | ((b[i + 1] if i + 1 < len(b) else 0) << 8) \
+            | (b[i + 2] if i + 2 < len(b) else 0)
+        out.append(_B64[(n >> 18) & 63])
+        out.append(_B64[(n >> 12) & 63])
+        out.append(_B64[(n >> 6) & 63] if i + 1 < len(b) else '=')
+        out.append(_B64[n & 63] if i + 2 < len(b) else '=')
+    return Value.text(''.join(out))
+
+
+define('ENCODE_BASE64', 1, 1, fn=_encode_base64)
+
+
+def _decode_base64(a, ctx):
+    """Strict: padding is required and any character outside the alphabet fails."""
+    s = a.text(0)
+    pos = a.pos_of(0)
+    if len(s) % 4 != 0:
+        fail('E_BAD_ARG', 'DECODE_BASE64 needs a length that is a multiple of 4', pos)
+    out = bytearray()
+    for i in range(0, len(s), 4):
+        quad = []
+        padding = 0
+        for k in range(4):
+            ch = s[i + k]
+            if ch == '=':
+                if i + 4 < len(s) or k < 2:
+                    fail('E_BAD_ARG', 'misplaced base64 padding', pos)
+                padding += 1
+                quad.append(0)
+                continue
+            if padding > 0:
+                fail('E_BAD_ARG', 'misplaced base64 padding', pos)
+            v = _B64_INDEX.get(ch)
+            if v is None:
+                fail('E_BAD_ARG', f'invalid base64 character "{ch}"', pos)
+            quad.append(v)
+        n = (quad[0] << 18) | (quad[1] << 12) | (quad[2] << 6) | quad[3]
+        out.append((n >> 16) & 255)
+        if padding < 2:
+            out.append((n >> 8) & 255)
+        if padding < 1:
+            out.append(n & 255)
+    return Value.bin(bytes(out))
+
+
+define('DECODE_BASE64', 1, 1, fn=_decode_base64)
+
+# CRC-32/ISO-HDLC: reflected, polynomial 0xEDB88320, init and final xor all ones.
+_CRC_TABLE = None
+
+
+def _crc_table():
+    global _CRC_TABLE
+    if _CRC_TABLE is None:
+        table = []
+        for i in range(256):
+            c = i
+            for _ in range(8):
+                c = (0xEDB88320 ^ (c >> 1)) if (c & 1) else (c >> 1)
+            table.append(c)
+        _CRC_TABLE = table
+    return _CRC_TABLE
+
+
+def _crc32(a, ctx):
+    t = _crc_table()
+    b = a.bytes(0)
+    crc = 0xFFFFFFFF
+    for byte in b:
+        crc = t[(crc ^ byte) & 255] ^ (crc >> 8)
+    return Value.text(f'{crc ^ 0xFFFFFFFF:08x}')
+
+
+define('CRC32', 1, 1, fn=_crc32)
+
+define('BTL', 1, 1,
+       fn=lambda a, ctx: Value.list([Value.int(b) for b in a.bytes(0)]))
+
+
+def _ltb(a, ctx):
+    v = a.val(0)
+    items = v.values() if v.size() > 0 else [v]
+    out = bytearray(len(items))
+    for i, item in enumerate(items):
+        d = item.as_decimal(a.pos_of(0))
+        n = -d.digits if d.neg else d.digits
+        if d.scale != 0 or n < 0 or n > 255:
+            fail('E_RANGE', f'LTB element {i + 1} is not a byte value', a.pos_of(0))
+        out[i] = n
+    return Value.bin(bytes(out))
+
+
+define('LTB', 1, 1, fn=_ltb)

sel/builtins/control.py

@@ -0,0 +1,43 @@
+from ..errors import fail
+from ..registry import INF, define
+from ..value import Value
+
+
+# The whole of SEL's control flow. Lazy, so only the taken branch is evaluated —
+# exactly the property the AST calling convention exists to provide.
+def _if(args, ctx):
+    if args.bool(0):
+        return args.val(1)
+    if args.count() == 3:
+        return args.val(2)
+    return Value.text('')
+
+
+define('IF', 2, 3, lazy=True, fn=_if)
+
+
+# Flat multi-branch selection — sugar for a nested IF ladder, with exactly the
+# same laziness: conditions are evaluated in order, and only the result that
+# matches is evaluated at all.
+#
+# The argument count must be odd: condition/result pairs plus a mandatory
+# default. IF can safely let its two-argument form default to "" because there
+# is one branch and nothing to mis-pair, but with an even count here a single
+# miscounted comma would shift every pair by one and still compile. Requiring
+# the default turns that into a compile-time E_ARITY instead of a wrong answer.
+def _cond(args, ctx):
+    last = args.count() - 1
+    for i in range(0, last, 2):
+        if args.bool(i):
+            return args.val(i + 1)
+    return args.val(last)
+
+
+define('COND', 3, INF, lazy=True, fn=_cond,
+       arity_error=lambda n: (
+           f'COND takes condition/result pairs and a final default '
+           f'(an odd number of arguments), got {n}') if n % 2 == 0 else None)
+
+
+# The one error a rule author raises deliberately.
+define('ABORT', 1, 1, fn=lambda args, ctx: fail('E_ABORT', args.text(0), args.pos_of(0)))

sel/builtins/number.py

@@ -0,0 +1,52 @@
+from .. import decimal as D
+from ..errors import fail
+from ..registry import INF, define
+from ..value import Value
+
+# spec/SPEC.md §6.4. Without these, a size argument nobody meant to write takes
+# down the host instead of failing as a rule error.
+MAX_SCALE = 1000000
+MAX_POWER = 100000
+
+
+def _sized(args, i, limit, what):
+    n = args.non_neg_int(i)
+    if n > limit:
+        fail('E_RANGE', f'{what} {n} exceeds the maximum of {limit}', args.pos_of(i))
+    return n
+
+
+define('ABS', 1, 1, fn=lambda a, ctx: Value.num(D.abs_(a.dec(0))))
+define('SIGN', 1, 1, fn=lambda a, ctx: Value.int(D.sign(a.dec(0))))
+define('CEIL', 1, 1, fn=lambda a, ctx: Value.num(D.ceil(a.dec(0))))
+define('FLOOR', 1, 1, fn=lambda a, ctx: Value.num(D.floor(a.dec(0))))
+define('TRUNC', 1, 1, fn=lambda a, ctx: Value.num(D.trunc(a.dec(0))))
+
+define('ROUND', 2, 2,
+       fn=lambda a, ctx: Value.num(D.round(a.dec(0), _sized(a, 1, MAX_SCALE, 'ROUND scale'))))
+define('POWER', 2, 2,
+       fn=lambda a, ctx: Value.num(D.power(a.dec(0), _sized(a, 1, MAX_POWER, 'POWER exponent'))))
+
+
+def _min(a, ctx):
+    best = a.dec(0)
+    for i in range(1, a.count()):
+        d = a.dec(i)
+        if D.cmp(d, best) < 0:
+            best = d
+    return Value.num(best)
+
+
+def _max(a, ctx):
+    best = a.dec(0)
+    for i in range(1, a.count()):
+        d = a.dec(i)
+        if D.cmp(d, best) > 0:
+            best = d
+    return Value.num(best)
+
+
+define('MIN', 1, INF, fn=_min)
+define('MAX', 1, INF, fn=_max)
+
+define('ISNUM', 1, 1, fn=lambda a, ctx: Value.bool(a.val(0).looks_numeric()))