spacetime-dsl 0.1.0__py3-none-any.whl

spacetime/__init__.py

@@ -0,0 +1,50 @@
+"""Space-Time DSL: compile a message history into a refined AST.
+
+The public surface is re-exported here; see ``__all__``. Typical use is
+:func:`compile_source` or :func:`compile_file`.
+"""
+
+from .ast import (
+    Ast,
+    History,
+    HistoryRefined,
+    Ident,
+    MessageDeclaration,
+    RecvEvent,
+    RecvEventRefined,
+    RefinedAst,
+    SendEvent,
+    SendEventRefined,
+    SourceLocation,
+)
+from .builder import AstBuilder, build_ast
+from .compiler import StageObserver, compile_file, compile_source
+from .errors import DslError, ParseError, SemanticError
+from .parser import parse
+from .semantics import create_refined_ast
+from .svg import render_svg
+
+__all__ = [
+    "Ast",
+    "AstBuilder",
+    "DslError",
+    "History",
+    "HistoryRefined",
+    "Ident",
+    "MessageDeclaration",
+    "ParseError",
+    "RecvEvent",
+    "RecvEventRefined",
+    "RefinedAst",
+    "SemanticError",
+    "SendEvent",
+    "SendEventRefined",
+    "SourceLocation",
+    "StageObserver",
+    "build_ast",
+    "compile_file",
+    "compile_source",
+    "create_refined_ast",
+    "parse",
+    "render_svg",
+]

spacetime/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point for ``python -m spacetime <file>``.
+
+Mirrors the ``spacetime`` console script declared in pyproject.toml; both
+delegate to :func:`spacetime.cli.main`, whose return value is the exit code.
+"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spacetime/ast.py

@@ -0,0 +1,243 @@
+"""Syntax tree data structures for the Space-Time DSL.
+
+The compiler works with two tree shapes:
+
+``Ast``
+    Raw output of :mod:`spacetime.builder`. Identifiers keep the
+    :class:`SourceLocation` needed to report errors, and message payloads
+    stay attached to their declarations.
+
+``RefinedAst``
+    Output of :mod:`spacetime.semantics`. Names are resolved to plain
+    strings, event names and message declarations are inlined into the
+    events that use them, and every event has a temporal position.
+
+All nodes are frozen dataclasses: building a tree never mutates an existing
+node, and callers may treat nodes as immutable values. Lists are still
+mutable by Python semantics; treat them as read-only after construction.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SourceLocation:
+    """A 1-based position in the DSL source.
+
+    Invariants:
+        ``line >= 1`` and ``column >= 1``. The builder falls back to
+        ``SourceLocation(1, 1)`` when Lark did not attach position metadata
+        to a rule, so a location may be approximate but is never absent.
+
+    Failure modes:
+        None: this is a passive value and performs no validation.
+    """
+
+    line: int
+    column: int
+
+
+@dataclass(frozen=True)
+class Ident:
+    """A source identifier together with the position where it appeared.
+
+    Used for process names, message names and values, event names, and
+    references between them.
+
+    Invariants:
+        ``name`` matches the grammar's ``IDENTIFIER`` token: it starts with
+        a lowercase ASCII letter and continues with letters, digits, or
+        underscores.
+
+    Failure modes:
+        None. Whether the name is declared is checked in semantics.
+    """
+
+    name: str
+    location: SourceLocation
+
+
+@dataclass(frozen=True)
+class MessageDeclaration:
+    """A ``name := "value"`` entry in a ``Messages`` block.
+
+    Invariants:
+        ``value`` is the payload text with the surrounding double quotes
+        removed. No escape processing is applied, so it may contain any
+        character the grammar allows between the quotes (no unescaped
+        double quote and no line terminator).
+
+    Failure modes:
+        Duplicate names are rejected while building the block, with a
+        :class:`spacetime.errors.SemanticError` at the second declaration.
+    """
+
+    name: Ident
+    value: str
+
+
+@dataclass(frozen=True)
+class SendEvent:
+    """A named send event from a ``History`` block.
+
+    ``name`` is the event identifier bound with ``:=`` (for example
+    ``m1``), not the message name. ``processes_to_ids`` may list several
+    recipients, which models a multicast as a single event.
+
+    Invariants:
+        - ``name`` is unique among send events; duplicates are rejected in
+          semantics.
+        - ``processes_to_ids`` is non-empty because the grammar requires at
+          least one recipient.
+        - Referenced message and process names may still be undeclared at
+          this stage.
+
+    Failure modes:
+        No validation here. :func:`spacetime.semantics.create_refined_ast`
+        raises :class:`spacetime.errors.SemanticError` for undeclared
+        messages or processes and for duplicate event names.
+    """
+
+    name: Ident
+    message_id: Ident
+    process_from_id: Ident
+    processes_to_ids: list[Ident]
+
+
+@dataclass(frozen=True)
+class RecvEvent:
+    """A ``Recv(event) :: p, q`` entry in a ``History`` block.
+
+    A multicast receive stays one event; every listed process is recorded
+    in ``process_ids``.
+
+    Invariants:
+        - ``send_event_ref`` names a send event that appears *earlier* in
+          the same history; forward references are rejected.
+        - ``process_ids`` is non-empty and every entry must be a recipient
+          of the referenced send event.
+
+    Failure modes:
+        Declaration order and recipient membership are validated in
+        :func:`spacetime.semantics.create_refined_ast`.
+    """
+
+    send_event_ref: Ident
+    process_ids: list[Ident]
+
+
+@dataclass(frozen=True)
+class History:
+    """The ordered event list of a ``History`` block.
+
+    Invariants:
+        - Order is source order, the only notion of time in the DSL; there
+          is no explicit timestamp.
+        - An empty list is valid and represents a program without events.
+
+    Failure modes:
+        None at this layer; cross-event rules live in semantics.
+    """
+
+    events: list[SendEvent | RecvEvent]
+
+
+@dataclass(frozen=True)
+class Ast:
+    """Raw syntax tree produced by :func:`spacetime.builder.build_ast`.
+
+    Invariants:
+        - ``process_declarations`` preserves source order and contains no
+          duplicate names.
+        - ``message_declarations`` preserves source order and contains no
+          duplicate names.
+        - Absent blocks become empty lists, so an empty program is a valid
+          ``Ast`` with no declarations and no history.
+
+    Failure modes:
+        Constructing an ``Ast`` directly performs no checks; violations are
+        only detected when semantics runs.
+    """
+
+    process_declarations: list[Ident]
+    message_declarations: list[MessageDeclaration]
+    history: History
+
+
+@dataclass(frozen=True)
+class SendEventRefined:
+    """A send event after name resolution.
+
+    ``message`` is the payload string from the matching declaration and
+    ``message_name`` is the declared message name itself (kept for the SVG
+    caption legend, which decodes arrow colors by message name). The
+    event's own name is intentionally dropped.
+
+    Invariants:
+        - ``temporal_pos`` is the 0-based index of the event in
+          ``HistoryRefined.events``.
+        - ``message_name`` names a declaration in the ``Messages`` block.
+        - ``message_type`` is the 0-based declaration index of the message
+          in the ``Messages`` block.
+        - ``process_from_id`` and every entry in ``processes_to_ids`` name
+          declared processes.
+        - ``processes_to_ids`` is non-empty and may repeat a process if the
+          source did.
+
+    Failure modes:
+        None; the instance only exists after semantic validation succeeded.
+    """
+
+    temporal_pos: int
+    message: str
+    message_name: str
+    message_type: int
+    process_from_id: str
+    processes_to_ids: list[str]
+
+
+@dataclass(frozen=True)
+class RecvEventRefined:
+    """A receive event after name resolution.
+
+    Invariants:
+        - ``related_send_event`` is the same ``SendEventRefined`` instance
+          stored earlier in the refined history.
+        - ``temporal_pos`` is greater than the related send's position.
+        - ``process_ids`` is a non-empty subset of
+          ``related_send_event.processes_to_ids``.
+
+    Failure modes:
+        None; the instance only exists after semantic validation succeeded.
+    """
+
+    temporal_pos: int
+    related_send_event: SendEventRefined
+    process_ids: list[str]
+
+
+@dataclass(frozen=True)
+class HistoryRefined:
+    """A resolved history whose events are ordered by ``temporal_pos``."""
+
+    events: list[SendEventRefined | RecvEventRefined]
+
+
+@dataclass(frozen=True)
+class RefinedAst:
+    """Fully resolved program returned by
+    :func:`spacetime.compiler.compile_source`.
+
+    Message declarations are not kept: payloads are inlined in
+    ``SendEventRefined.message``.
+
+    Invariants:
+        - ``process_declarations`` preserves source order as plain names.
+        - ``history.events`` is ordered by ``temporal_pos``.
+
+    Failure modes:
+        None; constructing one directly is not validated.
+    """
+
+    process_declarations: list[str]
+    history: HistoryRefined

spacetime/builder.py

@@ -0,0 +1,300 @@
+"""Lark parse tree to ``Ast`` translation (stage 2 of the pipeline).
+
+:class:`AstBuilder` is a Lark ``Interpreter`` whose method names match the
+rules in ``grammar.lark``. It drops purely syntactic nodes, attaches source
+locations to identifiers, and enforces structural rules that the grammar
+cannot express: no repeated block and no duplicate declaration inside a
+block.
+
+Failure modes:
+    Structural violations raise :class:`spacetime.errors.SemanticError` with
+    the location of the offending block or declaration. An unexpected tree
+    shape raises :class:`TypeError`, signalling that the grammar and this
+    builder have drifted apart.
+"""
+
+from dataclasses import dataclass
+
+from lark import Token, Tree
+from lark.visitors import Interpreter
+
+from .ast import (
+    Ast,
+    History,
+    Ident,
+    MessageDeclaration,
+    RecvEvent,
+    SendEvent,
+    SourceLocation,
+)
+from .errors import SemanticError
+
+
+@dataclass(frozen=True)
+class ProcessesBlock:
+    """Intermediate result for one ``Processes`` block.
+
+    ``location`` is the block's own position and is used only to report a
+    repeated block. ``declarations`` preserves source order.
+    """
+
+    declarations: list[Ident]
+    location: SourceLocation
+
+
+@dataclass(frozen=True)
+class MessagesBlock:
+    """Intermediate result for one ``Messages`` block.
+
+    ``location`` is the block's own position and is used only to report a
+    repeated block. ``declarations`` preserves source order.
+    """
+
+    declarations: list[MessageDeclaration]
+    location: SourceLocation
+
+
+@dataclass(frozen=True)
+class HistoryBlock:
+    """Intermediate result for one ``History`` block.
+
+    ``location`` is the block's own position and is used only to report a
+    repeated block. ``events`` preserves source order.
+    """
+
+    events: list[SendEvent | RecvEvent]
+    location: SourceLocation
+
+
+# Any block produced by ``AstBuilder`` before the blocks are merged into a
+# single ``Ast``.
+Block = ProcessesBlock | MessagesBlock | HistoryBlock
+
+
+def _location_from_tree(tree: Tree) -> SourceLocation:
+    """Return the best available source position for ``tree``.
+
+    Lark attaches ``line``/``column`` to rule nodes because the parser runs
+    with ``propagate_positions=True``. Some rules expose positions only on
+    their children, so this falls back to the first positioned child and
+    finally to ``SourceLocation(1, 1)``. The fallback keeps error reporting
+    total instead of raising while another diagnostic is being produced.
+    """
+    line = getattr(tree.meta, "line", None)
+    column = getattr(tree.meta, "column", None)
+    if line is not None and column is not None:
+        return SourceLocation(line, column)
+
+    for child in tree.children:
+        if isinstance(child, Tree) and child.children:
+            child = child.children[0]
+
+        line = getattr(child, "line", None)
+        column = getattr(child, "column", None)
+        if line is not None and column is not None:
+            return SourceLocation(line, column)
+
+    return SourceLocation(1, 1)
+
+
+def _ident_from_token(token: Token) -> Ident:
+    """Wrap a Lark identifier token as an ``Ident`` with its location.
+
+    Invariants:
+        ``token`` comes from one of the grammar's identifier rules, so it
+        has ``value``, ``line`` and ``column``.
+    """
+    return Ident(
+        name=token.value,
+        location=SourceLocation(token.line, token.column),
+    )
+
+
+class AstBuilder(Interpreter):
+    """Translate a parse tree into an :class:`Ast`.
+
+    Methods are named after grammar rules and return the node for that
+    rule. The visitor holds no state: create one instance per tree.
+
+    Failure modes:
+        See the module docstring: structural errors raise
+        :class:`SemanticError` and unexpected shapes raise ``TypeError``.
+    """
+
+    def start(self, tree: Tree) -> Ast:
+        """Merge the optional blocks into a single ``Ast``.
+
+        Blocks may appear in any order. Missing blocks default to empty
+        declarations and an empty history, so the empty source is valid.
+
+        Failure modes:
+            :class:`SemanticError` at the second occurrence of a block
+            kind; ``TypeError`` for an unknown block type.
+        """
+        blocks: list[Block] = [self.visit(child) for child in tree.children]
+
+        process_declarations: list[Ident] = []
+        message_declarations: list[MessageDeclaration] = []
+        history = History(events=[])
+        seen_blocks: set[str] = set()
+
+        for block in blocks:
+            match block:
+                case ProcessesBlock(declarations=declarations, location=location):
+                    if "processes" in seen_blocks:
+                        raise SemanticError(
+                            "duplicate Processes block", location=location
+                        )
+                    seen_blocks.add("processes")
+                    process_declarations = declarations
+                case MessagesBlock(declarations=declarations, location=location):
+                    if "messages" in seen_blocks:
+                        raise SemanticError(
+                            "duplicate Messages block", location=location
+                        )
+                    seen_blocks.add("messages")
+                    message_declarations = declarations
+                case HistoryBlock(events=events, location=location):
+                    if "history" in seen_blocks:
+                        raise SemanticError(
+                            "duplicate History block", location=location
+                        )
+                    seen_blocks.add("history")
+                    history = History(events=events)
+                case _:
+                    raise TypeError(f"unexpected block: {block!r}")
+
+        return Ast(
+            process_declarations=process_declarations,
+            message_declarations=message_declarations,
+            history=history,
+        )
+
+    def processes_block(self, tree: Tree) -> ProcessesBlock:
+        """Collect process declarations, rejecting duplicate names.
+
+        Invariants:
+            The returned declarations are in source order and have unique
+            names.
+
+        Failure modes:
+            :class:`SemanticError` at the second occurrence of a name.
+        """
+        declarations: list[Ident] = []
+        seen: set[str] = set()
+
+        for child in tree.children:
+            declaration = self.visit(child)
+            if declaration.name in seen:
+                raise SemanticError(
+                    f"duplicate process declaration: '{declaration.name}'",
+                    location=declaration.location,
+                )
+            seen.add(declaration.name)
+            declarations.append(declaration)
+
+        return ProcessesBlock(declarations, _location_from_tree(tree))
+
+    def messages_block(self, tree: Tree) -> MessagesBlock:
+        """Collect message declarations, rejecting duplicate names.
+
+        Invariants:
+            The returned declarations are in source order and have unique
+            names.
+
+        Failure modes:
+            :class:`SemanticError` at the second occurrence of a name.
+        """
+        declarations: list[MessageDeclaration] = []
+        seen: set[str] = set()
+
+        for child in tree.children:
+            declaration = self.visit(child)
+            name = declaration.name.name
+            if name in seen:
+                raise SemanticError(
+                    f"duplicate message declaration: '{name}'",
+                    location=declaration.name.location,
+                )
+            seen.add(name)
+            declarations.append(declaration)
+
+        return MessagesBlock(declarations, _location_from_tree(tree))
+
+    def history_block(self, tree: Tree) -> HistoryBlock:
+        """Collect history events in source order.
+
+        No cross-event validation happens here: receives may still refer to
+        unknown or later events until semantics runs.
+        """
+        events = [self.visit(child) for child in tree.children]
+        return HistoryBlock(events, _location_from_tree(tree))
+
+    def process_declaration(self, tree: Tree) -> Ident:
+        """Return a declared process name with its location."""
+        return _ident_from_token(tree.children[0])
+
+    def message_decl(self, tree: Tree) -> MessageDeclaration:
+        """Build a ``name := "value"`` declaration from its two children."""
+        name_node, value_node = tree.children
+        name = self.visit(name_node)
+        value = self.visit(value_node)
+        return MessageDeclaration(name=name, value=value)
+
+    def message_name(self, tree: Tree) -> Ident:
+        """Return the name identifier on the left of a message declaration."""
+        return _ident_from_token(tree.children[0])
+
+    def message_value(self, tree: Tree) -> str:
+        """Return the payload with the outer double quotes stripped.
+
+        No escape processing is performed; see
+        :class:`spacetime.ast.MessageDeclaration`.
+        """
+        return tree.children[0].value[1:-1]
+
+    def message_identifier(self, tree: Tree) -> Ident:
+        """Return the message reference inside ``Send(...)``."""
+        return _ident_from_token(tree.children[0])
+
+    def process_identifier(self, tree: Tree) -> Ident:
+        """Return a process used as sender, recipient, or receive target."""
+        return _ident_from_token(tree.children[0])
+
+    def event_identifier(self, tree: Tree) -> Ident:
+        """Return an event name bound by a send or referenced by ``Recv``."""
+        return _ident_from_token(tree.children[0])
+
+    def process_list(self, tree: Tree) -> list[Ident]:
+        """Return the comma-separated process identifiers in source order."""
+        return [self.visit(child) for child in tree.children]
+
+    def event(self, tree: Tree) -> SendEvent | RecvEvent:
+        """Unwrap a history event into its send or receive form."""
+        return self.visit(tree.children[0])
+
+    def send_event(self, tree: Tree) -> SendEvent:
+        """Build a send event from name, message, sender, and recipients."""
+        name, message_id, process_from_id, processes_to_ids = self.visit_children(
+            tree
+        )
+        return SendEvent(
+            name=name,
+            message_id=message_id,
+            process_from_id=process_from_id,
+            processes_to_ids=processes_to_ids,
+        )
+
+    def recv_event(self, tree: Tree) -> RecvEvent:
+        """Build a receive event from the referenced send name and targets."""
+        send_event_ref, process_ids = self.visit_children(tree)
+        return RecvEvent(send_event_ref=send_event_ref, process_ids=process_ids)
+
+
+def build_ast(tree: Tree) -> Ast:
+    """Translate ``tree`` (the ``start`` rule) into an ``Ast``.
+
+    Failure modes:
+        Same as :class:`AstBuilder`.
+    """
+    return AstBuilder().visit(tree)

spacetime/cli.py

@@ -0,0 +1,103 @@
+"""Command-line entry point: compile one DSL file and print its result."""
+
+import argparse
+import sys
+
+from .compiler import compile_file
+from .errors import DslError
+from .render import format_ast, format_parse_tree, format_refined_ast
+from .svg import render_svg
+
+_STAGE_TITLES = {
+    "parse": "parse tree",
+    "ast": "ast",
+    "refined": "refined ast",
+}
+
+_EPILOG = """\
+the language: three blocks, in any order
+
+  Processes { p  q }            declare process names, one per line
+  Messages  { m := "payload" }  declare a message name and its payload text
+  History   { ... }             the events, in the order they happen
+
+History events:
+
+  m1 := Send(msg) :: p -> q, r  process p sends message `msg` to q and r
+  Recv(m1) :: q                 process q receives the message sent as m1
+
+super simple example (save as hello.st, then run `spacetime hello.st`):
+
+  Processes {
+    p
+    q
+  }
+
+  Messages {
+    hello := "Hello"
+  }
+
+  History {
+    m1 := Send(hello) :: p -> q
+    Recv(m1) :: q
+  }
+"""
+
+
+def _print_stage(stage: str, output: object) -> None:
+    """Print one compiler stage with a header identifying the stage."""
+    renderers = {
+        "parse": format_parse_tree,
+        "ast": format_ast,
+        "refined": format_refined_ast,
+    }
+    print(f"== {_STAGE_TITLES[stage]} ==")
+    print(renderers[stage](output))
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Compile the file named on the command line and print its SVG diagram.
+
+    By default the SVG space-time diagram of the program is printed to
+    stdout. With ``--print-stages``, only the frontend runs: the parse tree
+    and both intermediate ASTs are printed as the pipeline produces them,
+    and no SVG is rendered.
+
+    Returns a process exit code: ``0`` on success, ``1`` when the file
+    cannot be read or the program contains a DSL error. Diagnostics go to
+    stderr; rendered output goes to stdout.
+    """
+    parser = argparse.ArgumentParser(
+        prog="space-time-dsl",
+        description="Compile a space-time diagram DSL file and print its SVG diagram.",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("path", help="DSL source file")
+    parser.add_argument(
+        "--print-stages",
+        action="store_true",
+        help="run only the frontend: print the parse tree and intermediate ASTs after every compiler stage",
+    )
+    parser.add_argument(
+        "--to-svg",
+        action="store_true",
+        help="print the SVG space-time diagram (this is the default)",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        program = compile_file(
+            args.path,
+            observe=_print_stage if args.print_stages else None,
+        )
+    except (DslError, OSError) as exc:
+        print(exc, file=sys.stderr)
+        return 1
+
+    if not args.print_stages:
+        # write, not print: render_svg already ends with a newline, and the
+        # golden file docs/sample_v2.svg must diff byte-exact against this
+        # output.
+        sys.stdout.write(render_svg(program))
+    return 0