openprocess 0.7.0__py3-none-any.whl

openprocess/ml/lexer.py

@@ -0,0 +1,277 @@
+"""Tokeniser for the CPN ML subset.
+
+CPN ML is a dialect of Standard ML, so the lexical rules are ML's rules.  The
+three that trip people up, and that this lexer gets right, are:
+
+1. **Negation is written ``~``, not ``-``.**  ``~3`` is negative three;
+   ``3 - 1`` is subtraction.  This removes the usual unary/binary minus
+   ambiguity entirely, so we can tokenise ``~`` as its own operator.
+
+2. **Comments are ``(* ... *)`` and they nest.**  ``(* a (* b *) c *)`` is one
+   comment.  A non-nesting scanner would stop at the first ``*)`` and then
+   choke on ``c *)``.
+
+3. **Several operators share a prefix.**  ``+`` / ``++``, ``-`` / ``--`` /
+   ``->``, ``@`` / ``@+``, ``<`` / ``<=`` / ``<>``, ``=`` / ``=>``, ``^`` /
+   ``^^``.  We therefore try the longest spellings first.
+
+CPN-specific additions to plain SML:
+
+* ``` ` ``` (backquote) is the multiset coefficient operator: ``3`x`` means
+  three copies of ``x``.
+* ``++`` and ``--`` are multiset union and difference.
+* ``@+`` introduces a time delay on an arc inscription (``e @+ 5``).
+* ``empty`` is the empty multiset literal.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterator
+
+from .errors import LexError
+
+
+# Words that are reserved and therefore never parsed as identifiers.
+KEYWORDS = frozenset(
+    {
+        "if", "then", "else",
+        "let", "in", "end",
+        "val", "fun", "fn",
+        "case", "of",
+        "andalso", "orelse", "not",
+        "div", "mod",
+        "true", "false", "nil", "empty",
+        "as", "op", "raise", "handle",
+    }
+)
+
+# Multi-character operators, longest first.  Order matters: the scanner takes
+# the first entry that matches, so ``++`` must precede ``+``.
+_MULTI_CHAR_OPERATORS = (
+    "@+",   # time delay (CPN extension)
+    "+++",  # timed multiset union
+    "---",  # timed multiset difference
+    "++",   # multiset union
+    "--",   # multiset difference
+    "^^",   # list append (CPN Tools spelling)
+    "::",   # list cons
+    "<=", ">=", "<>",
+    "=>",   # match arrow (fn / case)
+    "->",   # type arrow
+    "..",   # range, used in `int with 1..10`
+)
+
+_SINGLE_CHAR_OPERATORS = frozenset("+-*/=<>^@`~(),;:|[]{}#_.")
+
+# Characters that may appear inside an identifier after the first character,
+# in addition to letters and digits. A frozenset (not a string) on purpose:
+# `"" in "_'"` is True in Python, which would make the scan loops run forever
+# at end of input.
+_IDENT_EXTRA_CHARS = frozenset("_'")
+
+
+@dataclass(frozen=True)
+class Token:
+    """One lexical unit.
+
+    ``kind`` is one of ``ID``, ``KEYWORD``, ``INT``, ``REAL``, ``STRING``,
+    ``CHAR``, ``OP`` or ``EOF``.  ``value`` carries the already-decoded payload
+    for literals (a Python ``int``/``float``/``str``) and the raw text for
+    everything else.  ``position`` is the character offset of the token's first
+    character, used to point at the right place in error messages.
+    """
+
+    kind: str
+    value: object
+    position: int
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"{self.kind}({self.value!r})@{self.position}"
+
+
+class Lexer:
+    """Turns an inscription string into a list of :class:`Token`."""
+
+    def __init__(self, source: str) -> None:
+        self.source = source
+        self.index = 0
+
+    # -- low-level cursor helpers -------------------------------------------
+    def _peek(self, offset: int = 0) -> str:
+        position = self.index + offset
+        return self.source[position] if position < len(self.source) else ""
+
+    def _at_end(self) -> bool:
+        return self.index >= len(self.source)
+
+    # -- skipping ------------------------------------------------------------
+    def _skip_whitespace_and_comments(self) -> None:
+        """Advance past any run of whitespace and (nesting) comments."""
+        while not self._at_end():
+            char = self._peek()
+            if char.isspace():
+                self.index += 1
+                continue
+            if char == "(" and self._peek(1) == "*":
+                self._skip_comment()
+                continue
+            break
+
+    def _skip_comment(self) -> None:
+        start = self.index
+        depth = 0
+        while not self._at_end():
+            if self._peek() == "(" and self._peek(1) == "*":
+                depth += 1
+                self.index += 2
+            elif self._peek() == "*" and self._peek(1) == ")":
+                depth -= 1
+                self.index += 2
+                if depth == 0:
+                    return
+            else:
+                self.index += 1
+        raise LexError("unterminated comment: '(*' without a matching '*)'", start)
+
+    # -- literal scanners ----------------------------------------------------
+    def _scan_number(self) -> Token:
+        """Scan an integer or real literal, honouring ML's ``~`` for negation.
+
+        ``~`` is only treated as part of the literal when it is immediately
+        followed by a digit; otherwise it is a standalone negation operator
+        applied to an expression, and the parser deals with it.
+        """
+        start = self.index
+        if self._peek() == "~":
+            self.index += 1
+        while self._peek().isdigit():
+            self.index += 1
+
+        is_real = False
+        # A '.' only starts a fractional part if a digit follows it, so that
+        # `#1.x` style selections are not mis-scanned.
+        if self._peek() == "." and self._peek(1).isdigit():
+            is_real = True
+            self.index += 1
+            while self._peek().isdigit():
+                self.index += 1
+        # Exponent, e.g. 1.5E~3
+        if self._peek() in ("e", "E") and (
+            self._peek(1).isdigit() or (self._peek(1) == "~" and self._peek(2).isdigit())
+        ):
+            is_real = True
+            self.index += 1
+            if self._peek() == "~":
+                self.index += 1
+            while self._peek().isdigit():
+                self.index += 1
+
+        text = self.source[start:self.index]
+        # ML writes negation as '~'; Python needs '-'.
+        python_text = text.replace("~", "-")
+        if is_real:
+            return Token("REAL", float(python_text), start)
+        return Token("INT", int(python_text), start)
+
+    def _scan_string(self) -> Token:
+        """Scan a double-quoted string with the ML escape sequences."""
+        start = self.index
+        self.index += 1  # consume the opening quote
+        pieces: list[str] = []
+        while True:
+            if self._at_end():
+                raise LexError("unterminated string literal", start)
+            char = self._peek()
+            if char == '"':
+                self.index += 1
+                return Token("STRING", "".join(pieces), start)
+            if char == "\\":
+                self.index += 1
+                escape = self._peek()
+                self.index += 1
+                pieces.append(
+                    {"n": "\n", "t": "\t", "r": "\r", "\\": "\\", '"': '"'}.get(escape, escape)
+                )
+                continue
+            pieces.append(char)
+            self.index += 1
+
+    def _scan_identifier(self) -> Token:
+        """Scan an alphanumeric identifier or keyword.
+
+        ML identifiers may contain letters, digits, underscores and primes
+        (``x'``), and may be qualified with a structure name (``Int.toString``),
+        which we keep as one dotted identifier so the evaluator can look it up
+        in the builtin table.
+        """
+        start = self.index
+        while self._peek().isalnum() or self._peek() in _IDENT_EXTRA_CHARS:
+            self.index += 1
+        # Qualified name: swallow `.name` runs, but only when a letter follows,
+        # so that `1.` or a record selector cannot be absorbed by accident.
+        while self._peek() == "." and (self._peek(1).isalpha() or self._peek(1) == "_"):
+            self.index += 1
+            while self._peek().isalnum() or self._peek() in _IDENT_EXTRA_CHARS:
+                self.index += 1
+        text = self.source[start:self.index]
+        if text in KEYWORDS:
+            return Token("KEYWORD", text, start)
+        return Token("ID", text, start)
+
+    # -- the main loop -------------------------------------------------------
+    def tokens(self) -> list[Token]:
+        """Scan the whole input and return the token list, ending with EOF."""
+        result: list[Token] = []
+        while True:
+            self._skip_whitespace_and_comments()
+            if self._at_end():
+                result.append(Token("EOF", None, self.index))
+                return result
+
+            start = self.index
+            char = self._peek()
+
+            # Character literal: #"a"
+            if char == "#" and self._peek(1) == '"':
+                self.index += 1
+                string_token = self._scan_string()
+                text = str(string_token.value)
+                if len(text) != 1:
+                    raise LexError("character literal must contain exactly one character", start)
+                result.append(Token("CHAR", text, start))
+                continue
+
+            if char.isdigit() or (char == "~" and self._peek(1).isdigit()):
+                result.append(self._scan_number())
+                continue
+
+            if char == '"':
+                result.append(self._scan_string())
+                continue
+
+            if char.isalpha() or char == "_" and (self._peek(1).isalnum() or self._peek(1) == "_"):
+                result.append(self._scan_identifier())
+                continue
+
+            matched = False
+            for operator in _MULTI_CHAR_OPERATORS:
+                if self.source.startswith(operator, self.index):
+                    self.index += len(operator)
+                    result.append(Token("OP", operator, start))
+                    matched = True
+                    break
+            if matched:
+                continue
+
+            if char in _SINGLE_CHAR_OPERATORS:
+                self.index += 1
+                result.append(Token("OP", char, start))
+                continue
+
+            raise LexError(f"unexpected character {char!r}", start)
+
+
+def tokenise(source: str) -> list[Token]:
+    """Convenience wrapper: ``tokenise("1 ++ 2")``."""
+    return Lexer(source).tokens()

openprocess/ml/multiset.py

@@ -0,0 +1,417 @@
+"""Multiset (bag) algebra -- the arithmetic that CPN markings are made of.
+
+Why multisets are the central data structure
+--------------------------------------------
+In a Coloured Petri Net a place does not hold "3 tokens"; it holds a *multiset
+of coloured tokens*, for example ``2`"a" ++ 1`"b"``.  Arc expressions evaluate
+to multisets, and the firing rule is stated entirely in multiset terms:
+
+    a transition ``t`` is enabled in marking ``M`` under binding ``b`` iff
+    for every input place ``p``:   E(p,t)<b>  <=  M(p)
+
+    firing produces               M'(p) = (M(p) -- E(p,t)<b>) ++ E(t,p)<b>
+
+So if the multiset operations ``<=``, ``--`` and ``++`` are right, the
+simulator is a very short piece of code.  That is the whole reason this module
+is separate and heavily tested.
+
+Two classes live here:
+
+* :class:`Multiset` -- untimed.  A map from value to a strictly positive count.
+* :class:`TimedMultiset` -- timed.  A map from ``(value, timestamp)`` to a
+  count.  Used only for places whose colour set is declared ``timed``.
+
+Both are treated as **immutable**: every operator returns a new object.  This
+matters for state space analysis, where markings are used as dictionary keys
+and must never mutate after being stored.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Iterator
+
+from .errors import EvalError
+from .values import format_value, sort_key
+
+
+class Multiset:
+    """An immutable multiset of CPN values.
+
+    Internally a ``dict`` from value to count.  We maintain one invariant that
+    the rest of the code relies on:
+
+        **no key ever maps to a count of zero.**
+
+    Keeping zero entries out means equality is just dict equality, the support
+    is just ``keys()``, and hashing is straightforward.
+    """
+
+    __slots__ = ("_counts", "_hash")
+
+    def __init__(self, counts: dict[Any, int] | Iterable[tuple[Any, int]] | None = None) -> None:
+        cleaned: dict[Any, int] = {}
+        if counts is not None:
+            items = counts.items() if isinstance(counts, dict) else counts
+            for value, count in items:
+                if count < 0:
+                    raise EvalError(
+                        f"multiset coefficient must not be negative, got {count} "
+                        f"for {format_value(value)}"
+                    )
+                if count:
+                    cleaned[value] = cleaned.get(value, 0) + count
+        self._counts = cleaned
+        self._hash: int | None = None
+
+    # -- constructors --------------------------------------------------------
+    @classmethod
+    def _clean(cls, counts: dict[Any, int]) -> "Multiset":
+        """Wrap a dict already known to hold only positive counts.
+
+        Skips the validation loop of ``__init__``: the algebra below builds
+        clean dicts itself, and multiset arithmetic is the simulator's (and
+        the state space tool's) hottest code.
+        """
+        result = cls.__new__(cls)
+        result._counts = counts
+        result._hash = None
+        return result
+
+    @staticmethod
+    def empty() -> "Multiset":
+        """The empty multiset, written ``empty`` in CPN ML."""
+        return Multiset()
+
+    @staticmethod
+    def singleton(value: Any, count: int = 1) -> "Multiset":
+        """``count`value`` -- ``count`` copies of one value."""
+        return Multiset({value: count})
+
+    @staticmethod
+    def from_values(values: Iterable[Any]) -> "Multiset":
+        """Build from a plain iterable, summing duplicates."""
+        counts: dict[Any, int] = {}
+        for value in values:
+            counts[value] = counts.get(value, 0) + 1
+        return Multiset(counts)
+
+    # -- inspection ----------------------------------------------------------
+    def count(self, value: Any) -> int:
+        """Coefficient of ``value``; zero if absent."""
+        return self._counts.get(value, 0)
+
+    def support(self) -> list[Any]:
+        """Distinct values present, in canonical (sorted) order."""
+        return sorted(self._counts, key=sort_key)
+
+    def size(self) -> int:
+        """Total number of tokens, counting multiplicity."""
+        return sum(self._counts.values())
+
+    def is_empty(self) -> bool:
+        return not self._counts
+
+    def __bool__(self) -> bool:
+        return bool(self._counts)
+
+    def __len__(self) -> int:
+        return self.size()
+
+    def __contains__(self, value: Any) -> bool:
+        return value in self._counts
+
+    def items(self) -> Iterator[tuple[Any, int]]:
+        """Iterate ``(value, count)`` pairs in canonical order."""
+        for value in self.support():
+            yield value, self._counts[value]
+
+    def expand(self) -> Iterator[Any]:
+        """Iterate individual tokens, repeating values by multiplicity.
+
+        Used by the binder, which needs to pick concrete tokens out of a place.
+        """
+        for value, count in self.items():
+            for _ in range(count):
+                yield value
+
+    # -- algebra -------------------------------------------------------------
+    def __add__(self, other: "Multiset") -> "Multiset":
+        """``++`` -- multiset union (pointwise sum of coefficients)."""
+        if not isinstance(other, Multiset):
+            return NotImplemented
+        result = dict(self._counts)
+        for value, count in other._counts.items():
+            result[value] = result.get(value, 0) + count
+        return Multiset._clean(result)
+
+    def __sub__(self, other: "Multiset") -> "Multiset":
+        """``--`` -- multiset difference, truncated at zero.
+
+        CPN Tools defines ``(m1 -- m2)(c) = max(0, m1(c) - m2(c))``.  The
+        simulator never relies on the truncation, because it checks
+        ``other <= self`` first, but user inscriptions may.
+        """
+        if not isinstance(other, Multiset):
+            return NotImplemented
+        result = dict(self._counts)
+        for value, count in other._counts.items():
+            remaining = result.get(value, 0) - count
+            if remaining > 0:
+                result[value] = remaining
+            else:
+                result.pop(value, None)
+        return Multiset._clean(result)
+
+    def __mul__(self, factor: int) -> "Multiset":
+        """Scalar multiplication: every coefficient times ``factor``."""
+        if not isinstance(factor, int):
+            return NotImplemented
+        if factor < 0:
+            raise EvalError("cannot multiply a multiset by a negative number")
+        if factor == 0:
+            return Multiset()
+        return Multiset._clean({v: c * factor for v, c in self._counts.items()})
+
+    __rmul__ = __mul__
+
+    def __le__(self, other: "Multiset") -> bool:
+        """Multiset inclusion -- **this is the enabling test**.
+
+        ``self <= other`` iff every value occurs at least as often in ``other``
+        as it does in ``self``.  Note this is a *partial* order: two multisets
+        can be incomparable, so ``not (a <= b)`` does not imply ``b <= a``.
+        """
+        if not isinstance(other, Multiset):
+            return NotImplemented
+        return all(count <= other._counts.get(value, 0) for value, count in self._counts.items())
+
+    def __ge__(self, other: "Multiset") -> bool:
+        if not isinstance(other, Multiset):
+            return NotImplemented
+        return other <= self
+
+    def __lt__(self, other: "Multiset") -> bool:
+        return self <= other and self != other
+
+    def __gt__(self, other: "Multiset") -> bool:
+        return other < self
+
+    # -- identity ------------------------------------------------------------
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Multiset) and self._counts == other._counts
+
+    def __hash__(self) -> int:
+        # Cached because markings are hashed once per state space node visit.
+        if self._hash is None:
+            self._hash = hash(frozenset(self._counts.items()))
+        return self._hash
+
+    # -- printing ------------------------------------------------------------
+    def __repr__(self) -> str:
+        """CPN Tools syntax: ``2`"a"++1`"b"``; the empty multiset is ``empty``."""
+        if not self._counts:
+            return "empty"
+        return "++".join(f"{count}`{format_value(value)}" for value, count in self.items())
+
+    __str__ = __repr__
+
+
+class TimedMultiset:
+    """A multiset of *timestamped* tokens, for places with a timed colour set.
+
+    In a timed CPN each token carries a time stamp saying when it becomes
+    available.  A transition may only consume tokens whose stamp is less than
+    or equal to the current model time.  We therefore key the underlying dict
+    on ``(value, timestamp)`` pairs and expose two extra operations that the
+    untimed class does not need:
+
+    * :meth:`available_at` -- project down to the untimed multiset of tokens
+      that are ready at a given clock value;
+    * :meth:`earliest_time` -- the smallest timestamp present, which the
+      simulator uses to decide how far to advance the clock when no transition
+      is enabled now.
+    """
+
+    __slots__ = ("_counts", "_hash")
+
+    def __init__(self, counts: dict[tuple[Any, int], int] | Iterable[tuple[tuple[Any, int], int]] | None = None) -> None:
+        cleaned: dict[tuple[Any, int], int] = {}
+        if counts is not None:
+            items = counts.items() if isinstance(counts, dict) else counts
+            for key, count in items:
+                if count < 0:
+                    raise EvalError("timed multiset coefficient must not be negative")
+                if count:
+                    cleaned[key] = cleaned.get(key, 0) + count
+        self._counts = cleaned
+        self._hash: int | None = None
+
+    @staticmethod
+    def empty() -> "TimedMultiset":
+        return TimedMultiset()
+
+    @staticmethod
+    def from_multiset(multiset: Multiset, timestamp: int) -> "TimedMultiset":
+        """Stamp every token of an untimed multiset with the same time.
+
+        This is how an output arc result becomes tokens in a timed place: the
+        arc yields a plain multiset, and the arc's ``@+`` delay expression
+        (plus the current clock) supplies the stamp.
+        """
+        return TimedMultiset({(value, timestamp): count for value, count in multiset.items()})
+
+    # -- inspection ----------------------------------------------------------
+    def size(self) -> int:
+        return sum(self._counts.values())
+
+    def is_empty(self) -> bool:
+        return not self._counts
+
+    def __bool__(self) -> bool:
+        return bool(self._counts)
+
+    def items(self) -> Iterator[tuple[Any, int, int]]:
+        """Iterate ``(value, timestamp, count)`` in canonical order."""
+        for value, timestamp in sorted(self._counts, key=lambda k: (sort_key(k[0]), k[1])):
+            yield value, timestamp, self._counts[(value, timestamp)]
+
+    def available_at(self, clock: int) -> Multiset:
+        """Untimed multiset of the tokens whose stamp has been reached."""
+        ready: dict[Any, int] = {}
+        for (value, timestamp), count in self._counts.items():
+            if timestamp <= clock:
+                ready[value] = ready.get(value, 0) + count
+        return Multiset(ready)
+
+    def earliest_time(self) -> int | None:
+        """Smallest timestamp in the place, or ``None`` if the place is empty."""
+        if not self._counts:
+            return None
+        return min(timestamp for _, timestamp in self._counts)
+
+    def next_time_after(self, clock: int) -> int | None:
+        """Smallest timestamp strictly greater than ``clock``.
+
+        The simulator asks every place this question to compute the next
+        interesting model time when nothing is enabled at the current one.
+        """
+        future = [t for _, t in self._counts if t > clock]
+        return min(future) if future else None
+
+    # -- algebra -------------------------------------------------------------
+    def add(self, other: "TimedMultiset") -> "TimedMultiset":
+        result = dict(self._counts)
+        for key, count in other._counts.items():
+            result[key] = result.get(key, 0) + count
+        return TimedMultiset(result)
+
+    def remove_available(self, wanted: Multiset, clock: int) -> "TimedMultiset":
+        """Consume ``wanted`` tokens, taking the *oldest* available ones first.
+
+        CPN Tools removes tokens with the smallest timestamp first.  This is
+        not merely a convention: it keeps timed simulation deterministic with
+        respect to which stamps remain in the place, which matters when a
+        later transition's enabling depends on those stamps.  Raises
+        :class:`EvalError` if not enough tokens are available at ``clock`` --
+        the caller is expected to have checked enabling first.
+        """
+        result = dict(self._counts)
+        for value, needed in wanted.items():
+            # Candidate stamps for this value that have already been reached,
+            # oldest first.
+            stamps = sorted(t for (v, t) in result if v == value and t <= clock)
+            for timestamp in stamps:
+                if needed == 0:
+                    break
+                key = (value, timestamp)
+                take = min(needed, result[key])
+                result[key] -= take
+                if result[key] == 0:
+                    del result[key]
+                needed -= take
+            if needed:
+                raise EvalError(
+                    f"cannot remove {wanted.count(value)}`{format_value(value)} at time "
+                    f"{clock}: only {wanted.count(value) - needed} available"
+                )
+        return TimedMultiset(result)
+
+    # -- identity ------------------------------------------------------------
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, TimedMultiset) and self._counts == other._counts
+
+    def __hash__(self) -> int:
+        if self._hash is None:
+            self._hash = hash(frozenset(self._counts.items()))
+        return self._hash
+
+    def __repr__(self) -> str:
+        """CPN Tools syntax: ``2`"a"@[0,5]``.
+
+        We print one term per (value, timestamp) pair, which is unambiguous and
+        matches what CPN Tools shows in the marking tooltip for simple cases.
+        """
+        if not self._counts:
+            return "empty"
+        return "++".join(
+            f"{count}`{format_value(value)}@[{timestamp}]" for value, timestamp, count in self.items()
+        )
+
+    __str__ = __repr__
+
+
+class TimedTokens:
+    """Tokens with a time attached: the value of ``x@+5``, ``x@5`` or ``+++``.
+
+    CPN Tools writes timed multisets as terms joined by ``+++``, each term
+    carrying either a *delay* (``1`x@+5``: available 5 time units after the
+    transition fires) or an absolute *time stamp* (``1`x@5``, mostly in
+    initial markings).  ``groups`` keeps one ``(tokens, time, absolute)``
+    entry per term; :meth:`stamped` turns them into concrete time stamps once
+    the clock is known.
+    """
+
+    __slots__ = ("groups",)
+
+    def __init__(self, groups: Iterable[tuple[Multiset, Any, bool]]) -> None:
+        self.groups: tuple[tuple[Multiset, Any, bool], ...] = tuple(groups)
+
+    def __add__(self, other: "TimedTokens") -> "TimedTokens":
+        """``+++``: the terms of both."""
+        if not isinstance(other, TimedTokens):
+            return NotImplemented
+        return TimedTokens(self.groups + other.groups)
+
+    def untimed(self) -> Multiset:
+        """All the tokens, without their times."""
+        result = Multiset.empty()
+        for tokens, _time, _absolute in self.groups:
+            result = result + tokens
+        return result
+
+    def delayed(self, delay: Any) -> "TimedTokens":
+        """``(...)@+d`` around tokens that already have a delay: add ``d``."""
+        return TimedTokens((tokens, time if absolute else time + delay, absolute)
+                           for tokens, time, absolute in self.groups)
+
+    def scaled(self, factor: int) -> "TimedTokens":
+        return TimedTokens((tokens * factor, time, absolute)
+                           for tokens, time, absolute in self.groups)
+
+    def stamped(self, clock: Any) -> list[tuple[Multiset, Any]]:
+        """``(tokens, time stamp)`` per term, delays counted from ``clock``."""
+        return [(tokens, time if absolute else clock + time)
+                for tokens, time, absolute in self.groups]
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, TimedTokens) and self.groups == other.groups
+
+    def __hash__(self) -> int:
+        return hash(self.groups)
+
+    def __repr__(self) -> str:
+        terms = [f"{tokens}@{'' if absolute else '+'}{time}"
+                 for tokens, time, absolute in self.groups]
+        return "+++".join(terms) if terms else "empty"
+
+    __str__ = __repr__