osiris-lang 0.2.4__py3-none-win_amd64.whl

osiris/__init__.py

@@ -0,0 +1,12 @@
+from importlib.metadata import PackageNotFoundError, version as distribution_version
+
+__all__ = ["version"]
+
+try:
+    __version__ = distribution_version("osiris-lang")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+
+def version() -> str:
+    return __version__

osiris/prelude/__init__.py

@@ -0,0 +1,8 @@
+"""Runtime ABI imported by Python emitted from Osiris programs."""
+
+from . import control as _control
+from . import sequences as _sequences
+from .control import *
+from .sequences import *
+
+__all__ = [*_control.__all__, *_sequences.__all__]

osiris/prelude/_sequence_consumers.py

@@ -0,0 +1,77 @@
+"""Sequence realization and predicate consumers."""
+
+from __future__ import annotations
+
+import builtins as _builtins
+from collections.abc import Callable
+
+from ._sequence_core import _MISSING, _iter_or_empty
+from .control import truthy
+
+def run_bang(function: Callable[[object], object], collection: object) -> None:
+    """Invoke ``function`` for each item and discard all results."""
+
+    for value in _iter_or_empty(collection):
+        function(value)
+    return None
+
+
+def _realize_prefix(arguments: tuple[object, ...]) -> object:
+    if len(arguments) == 1:
+        limit = None
+        collection = arguments[0]
+    elif len(arguments) == 2:
+        limit = arguments[0]
+        collection = arguments[1]
+        if not isinstance(limit, int) or isinstance(limit, bool):
+            raise TypeError("realization count must be an integer")
+    else:
+        raise TypeError("expected collection or count and collection")
+    iterator = _iter_or_empty(collection)
+    if limit is None:
+        for _ in iterator:
+            pass
+    else:
+        for _ in range(max(0, limit)):
+            if _builtins.next(iterator, _MISSING) is _MISSING:
+                break
+    return collection
+
+
+def doall(*arguments: object) -> object:
+    """Realize all, or a bounded prefix of, an iterable and return it."""
+
+    return _realize_prefix(arguments)
+
+
+def dorun(*arguments: object) -> None:
+    """Realize all, or a bounded prefix of, an iterable and return nil."""
+
+    _realize_prefix(arguments)
+    return None
+
+
+def some(predicate: Callable[[object], object], collection: object) -> object:
+    """Return the first Clojure-truthy predicate result, or nil."""
+
+    for value in _iter_or_empty(collection):
+        result = predicate(value)
+        if truthy(result):
+            return result
+    return None
+
+
+def every_q(predicate: Callable[[object], object], collection: object) -> bool:
+    """Clojure-truthy all predicate check."""
+
+    return all(truthy(predicate(value)) for value in _iter_or_empty(collection))
+
+
+def not_every_q(predicate: Callable[[object], object], collection: object) -> bool:
+    return not every_q(predicate, collection)
+
+
+def not_any_q(predicate: Callable[[object], object], collection: object) -> bool:
+    # ``some`` returns the predicate's value, and Python's ``not`` would
+    # incorrectly treat Clojure-truthy values such as ``0``/``""`` as false.
+    return not truthy(some(predicate, collection))

osiris/prelude/_sequence_core.py

@@ -0,0 +1,259 @@
+"""Memoized lazy-sequence representation and core sequence operations."""
+
+from __future__ import annotations
+
+import builtins as _builtins
+import threading as _threading
+from collections.abc import Callable, Iterable
+from typing import Iterator, Optional
+
+_MISSING = object()
+
+class _LazySeq:
+    """Memoized lazy sequence that realizes elements one at a time.
+
+    The source iterator and already produced values are retained so a lazy
+    sequence can be traversed repeatedly without re-running its thunk or
+    losing values from a one-shot generator.
+    """
+
+    __slots__ = ("_thunk", "_source", "_cache", "_done", "_error", "_lock")
+
+    def __init__(self, thunk: Callable[[], Iterable[object]]) -> None:
+        self._thunk = thunk
+        self._source: Optional[Iterator[object]] = None
+        self._cache: list[object] = []
+        self._done = False
+        self._error: Optional[BaseException] = None
+        self._lock = _threading.RLock()
+
+    def _ensure_source_locked(self) -> Iterator[object]:
+        """Initialize the source while ``_lock`` is held."""
+
+        if self._error is not None:
+            raise self._error
+        if self._source is None:
+            try:
+                value = self._thunk()
+                self._source = iter(()) if value is None else iter(value)
+            except BaseException as error:
+                # A lazy source is a memoized computation.  Cache failures so
+                # a second consumer cannot rerun an effectful or partial thunk.
+                self._error = error
+                self._done = True
+                raise
+        return self._source
+
+    def _iter_from(self, index: int) -> Iterator[object]:
+        """Iterate from a cached position without replaying earlier values."""
+
+        while True:
+            with self._lock:
+                if self._error is not None:
+                    raise self._error
+                if index < len(self._cache):
+                    value = self._cache[index]
+                    index += 1
+                elif self._done:
+                    return
+                else:
+                    try:
+                        value = _builtins.next(self._ensure_source_locked())
+                    except StopIteration:
+                        self._done = True
+                        return
+                    except BaseException as error:
+                        self._error = error
+                        self._done = True
+                        raise
+                    self._cache.append(value)
+                    index += 1
+            yield value
+
+    def __iter__(self) -> Iterator[object]:
+        return self._iter_from(0)
+
+    def __bool__(self) -> bool:
+        """Match sequence truthiness without realizing more than one item."""
+
+        try:
+            _builtins.next(iter(self))
+        except StopIteration:
+            return False
+        return True
+
+
+def lazy_seq(thunk: Callable[[], Iterable[object]]) -> _LazySeq:
+    """Construct a memoized, iterable lazy sequence from ``thunk``."""
+
+    return _LazySeq(thunk)
+
+
+def _iter_or_empty(collection: object) -> Iterator[object]:
+    """Treat Clojure nil as an empty sequence at sequence boundaries."""
+
+    if collection is None:
+        return iter(())
+    return iter(collection)  # type: ignore[arg-type]
+
+
+def cons(value: object, collection: object) -> _LazySeq:
+    """Return a lazy sequence with ``value`` before ``collection``."""
+
+    def produce() -> Iterator[object]:
+        yield value
+        yield from _iter_or_empty(collection)
+
+    return lazy_seq(produce)
+
+
+def concat(*collections: object) -> _LazySeq:
+    """Concatenate sequences lazily, skipping nil collections."""
+
+    def produce() -> Iterator[object]:
+        for collection in collections:
+            yield from _iter_or_empty(collection)
+
+    return lazy_seq(produce)
+
+
+def count(collection: object) -> int:
+    """Count a collection without applying Python truthiness to it."""
+
+    if collection is None:
+        return 0
+    try:
+        return len(collection)  # type: ignore[arg-type]
+    except TypeError:
+        return sum(1 for _ in collection)  # type: ignore[operator]
+
+
+_EMPTY_PROBE = object()
+
+
+def empty_q(collection: object) -> bool:
+    """Return whether ``collection`` has no values.
+
+    Sized containers are checked without iteration.  For a one-shot iterable
+    the probe necessarily advances its iterator by at most one item; Osiris
+    lazy sequences memoize that item, so repeated checks remain non-destructive
+    at the public sequence boundary.  ``None`` follows Clojure's empty-seq
+    convention, while scalar non-collections raise ``TypeError``.
+    """
+
+    if collection is None:
+        return True
+    try:
+        return len(collection) == 0  # type: ignore[arg-type]
+    except TypeError:
+        try:
+            iterator = iter(collection)  # type: ignore[arg-type]
+        except TypeError as error:
+            raise TypeError("empty? expects a collection") from error
+        return _builtins.next(iterator, _EMPTY_PROBE) is _EMPTY_PROBE
+
+
+def seq_q(value: object) -> bool:
+    """Return whether ``value`` is an Osiris seq/list value.
+
+    Raw Python iterators are deliberately not treated as seqs; callers can
+    opt into the replayable seq protocol with :func:`sequence`.
+    """
+
+    return isinstance(value, (list, _LazySeq))
+
+
+def coll_q(value: object) -> bool:
+    """Return whether ``value`` is an Osiris collection value."""
+
+    return isinstance(value, (list, tuple, dict, set, _LazySeq))
+
+
+def sequential_q(value: object) -> bool:
+    """Return whether ``value`` is an ordered sequential collection."""
+
+    return isinstance(value, (list, tuple, _LazySeq))
+
+
+def first(collection: object) -> object:
+    """Return the first item or nil for an empty sequence."""
+
+    return _builtins.next(_iter_or_empty(collection), None)
+
+
+def rest(collection: object) -> list[object]:
+    """Return all but the first item as a materialized list."""
+
+    iterator = _iter_or_empty(collection)
+    _builtins.next(iterator, None)
+    return list(iterator)
+
+
+def next(collection: object) -> Optional[_LazySeq]:
+    """Return the lazy tail, or nil when no tail exists."""
+
+    iterator = _iter_or_empty(collection)
+    try:
+        _builtins.next(iterator)
+    except StopIteration:
+        return None
+    try:
+        first_tail = _builtins.next(iterator)
+    except StopIteration:
+        return None
+
+    def produce() -> Iterator[object]:
+        yield first_tail
+        yield from iterator
+
+    return lazy_seq(produce)
+
+
+def nth(collection: object, index: int, not_found: object = _MISSING) -> object:
+    """Return an indexed item, or use the explicitly supplied fallback.
+
+    Clojure distinguishes ``(nth coll index)`` from
+    ``(nth coll index not-found)`` even when ``not-found`` is nil.  Keep that
+    distinction at the Python boundary instead of silently turning an invalid
+    two-argument lookup into ``None``.
+    """
+
+    if not isinstance(index, int) or isinstance(index, bool):
+        raise TypeError("nth index must be an integer")
+    if index < 0:
+        if not_found is _MISSING:
+            raise IndexError("nth index is out of range")
+        return not_found
+    for position, value in enumerate(_iter_or_empty(collection)):
+        if position == index:
+            return value
+    if not_found is _MISSING:
+        raise IndexError("nth index is out of range")
+    return not_found
+
+
+def seq(collection: object) -> Optional[object]:
+    """Return a non-empty sequence or nil."""
+
+    iterator = _iter_or_empty(collection)
+    try:
+        first_value = _builtins.next(iterator)
+    except StopIteration:
+        return None
+    return cons(first_value, iterator)
+
+
+def empty(collection: object) -> object:
+    """Return an empty value with the broad shape of ``collection``."""
+
+    if isinstance(collection, tuple):
+        return ()
+    if isinstance(collection, set):
+        return set()
+    if isinstance(collection, dict):
+        return {}
+    if isinstance(collection, str):
+        return ""
+    if isinstance(collection, bytes):
+        return b""
+    return []

osiris/prelude/_sequence_eager.py

@@ -0,0 +1,255 @@
+"""Eager collection, reduction, loop, and trampoline operations."""
+
+from __future__ import annotations
+
+import builtins as _builtins
+from collections.abc import Callable, Iterable
+from typing import Generic, Iterator, TypeVar, Union
+
+from ._sequence_core import _LazySeq, _iter_or_empty, empty_q, lazy_seq
+from .control import truthy
+
+_Result = TypeVar("_Result")
+
+def nonempty(collection: object) -> bool:
+    """Test a collection without consuming memoized lazy values."""
+
+    return not empty_q(collection)
+
+
+class _ForStop:
+    """Private nearest-collection stop token used by ``for :while``."""
+
+    __slots__ = ()
+
+
+_FOR_STOP = _ForStop()
+
+
+def for_stop() -> _ForStop:
+    """Return the private stop token consumed by collection control helpers."""
+
+    return _FOR_STOP
+
+
+def doseq(
+    function: Callable[[object], object], collection: Iterable[object]
+) -> None:
+    """Invoke ``function`` in order without materializing callback results."""
+
+    for value in _iter_or_empty(collection):
+        if function(value) is _FOR_STOP:
+            break
+
+
+def _map_values(
+    function: Callable[..., _Result], collections: tuple[Iterable[object], ...]
+) -> Iterator[_Result]:
+    return _builtins.map(
+        function, *(_iter_or_empty(collection) for collection in collections)
+    )
+
+
+def mapv(
+    function: Callable[..., _Result], *collections: Iterable[object]
+) -> tuple[_Result, ...]:
+    """Apply ``function`` lazily through ``map`` and materialize a vector."""
+
+    return tuple(_map_values(function, collections))
+
+
+def map(
+    function: Callable[..., _Result], *collections: Iterable[object]
+) -> list[_Result]:
+    """Apply ``function`` in order and materialize a Lisp list.
+
+    ``mapv`` is the explicit tuple/vector variant.  Keeping this helper
+    materialized gives the typed core a deterministic ``List`` result while
+    ``lazy_seq`` remains available when a caller needs deferred production.
+    """
+
+    return list(_map_values(function, collections))
+
+
+def mapcatv(
+    function: Callable[..., Iterable[object]], *collections: Iterable[object]
+) -> tuple[object, ...]:
+    """Map one or more collections and concatenate each returned sequence.
+
+    Like Clojure's ``mapcat``, traversal stops at the shortest input and the
+    callback receives one value from each collection.
+    """
+
+    result: list[object] = []
+    iterators = tuple(_iter_or_empty(collection) for collection in collections)
+    for values in zip(*iterators):
+        mapped = function(*values)
+        if mapped is _FOR_STOP:
+            break
+        result.extend(_iter_or_empty(mapped))
+    return tuple(result)
+
+
+def mapcat(
+    function: Callable[..., Iterable[object]], *collections: Iterable[object]
+) -> list[object]:
+    """List variant of :func:`mapcatv`."""
+
+    return list(mapcatv(function, *collections))
+
+
+def _filter_values(
+    predicate: Callable[[object], object], collection: Iterable[object]
+) -> Iterator[object]:
+    return (
+        value
+        for value in _iter_or_empty(collection)
+        if truthy(predicate(value))
+    )
+
+
+def filterv(
+    predicate: Callable[[object], bool], collection: Iterable[object]
+) -> tuple[object, ...]:
+    """Return the values satisfying ``predicate`` as a vector."""
+
+    return tuple(_filter_values(predicate, collection))
+
+
+def filter(
+    predicate: Callable[[object], bool], collection: Iterable[object]
+) -> list[object]:
+    """Return the values satisfying ``predicate`` as a Lisp list."""
+
+    return list(_filter_values(predicate, collection))
+
+
+def removev(
+    predicate: Callable[[object], object], collection: object
+) -> tuple[object, ...]:
+    """Vector form of ``remove`` using Clojure truthiness."""
+
+    return tuple(value for value in _iter_or_empty(collection) if not truthy(predicate(value)))
+
+
+def remove(
+    predicate: Callable[[object], object], collection: object
+) -> _LazySeq:
+    """Lazily retain values for which ``predicate`` is false/nil."""
+
+    def produce() -> Iterator[object]:
+        for value in _iter_or_empty(collection):
+            if not truthy(predicate(value)):
+                yield value
+
+    return lazy_seq(produce)
+
+
+class Reduced(Generic[_Result]):
+    """Value marker returned by a reducing callback to stop traversal."""
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: _Result) -> None:
+        self.value = value
+
+
+def reduced(value: _Result) -> Reduced[_Result]:
+    """Wrap ``value`` as an early result for ``reduce`` or ``fold``."""
+
+    return Reduced(value)
+
+
+def reduced_p(value: object) -> bool:
+    """Return whether ``value`` carries the reduction stop marker."""
+
+    return isinstance(value, Reduced)
+
+
+def unreduced(value: Union[_Result, Reduced[_Result]]) -> _Result:
+    """Remove one reduction marker, leaving ordinary values unchanged."""
+
+    if isinstance(value, Reduced):
+        return value.value
+    return value
+
+
+def _reduce_with_initial(
+    function: Callable[[object, object], object],
+    initial: object,
+    collection: Iterable[object],
+) -> object:
+    accumulator = initial
+    for item in collection:
+        accumulator = function(accumulator, item)
+        if isinstance(accumulator, Reduced):
+            return accumulator.value
+    return accumulator
+
+
+def reduce(function: Callable[[object, object], object], *arguments: object) -> object:
+    """Reduce ``collection`` with an optional initial accumulator."""
+
+    if len(arguments) == 1:
+        iterator = _iter_or_empty(arguments[0])
+        try:
+            initial = _builtins.next(iterator)
+        except StopIteration:
+            raise TypeError("reduce() of empty iterable with no initial value") from None
+        return _reduce_with_initial(function, initial, iterator)
+    if len(arguments) == 2:
+        return _reduce_with_initial(
+            function,
+            arguments[0],
+            _iter_or_empty(arguments[1]),
+        )
+    raise TypeError("reduce expects a function, collection, and optional initial value")
+
+
+def fold(
+    function: Callable[[object, object], object],
+    initial: object,
+    collection: Iterable[object],
+) -> object:
+    """Named initial-value form of ``reduce``."""
+
+    return _reduce_with_initial(function, initial, collection)
+
+
+class _RecurSignal:
+    """Private value used by ``loop`` to carry the next state tuple."""
+
+    __slots__ = ("values",)
+
+    def __init__(self, values: tuple[object, ...]) -> None:
+        self.values = values
+
+
+def recur(*values: object) -> _RecurSignal:
+    """Return a control token consumed by :func:`loop`."""
+
+    return _RecurSignal(tuple(values))
+
+
+def loop(function: Callable[..., _Result], *initial: object) -> _Result:
+    """Run a Clojure-style state loop without growing the Python stack."""
+
+    state = tuple(initial)
+    while True:
+        result = function(*state)
+        if not isinstance(result, _RecurSignal):
+            return result
+        if len(result.values) != len(state):
+            raise TypeError(
+                "recur must supply the same number of values as loop bindings"
+            )
+        state = result.values
+
+
+def trampoline(function: Callable[..., object], *arguments: object) -> object:
+    """Invoke a function, then bounce through zero-argument callables."""
+
+    result = function(*arguments)
+    while callable(result):
+        result = result()
+    return result