spacetime-dsl 0.1.0__tar.gz

spacetime_dsl-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: spacetime-dsl
+Version: 0.1.0
+Summary: Compiler front-end for a DSL describing Lamport space-time diagrams
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: lark==1.3.1
+
+## Setup
+
+Requires Python 3.10 or newer (developed and tested on 3.13).
+
+Run `./setup.sh` to create the virtual environment and install the project.
+It performs an editable install (`pip install --editable . --group dev`), so
+`import spacetime` resolves to this checkout and the `spacetime` command is
+available inside `.venv/bin/`. Dependencies live in `pyproject.toml`.
+
+The environment lives **only** in `.venv/`. Do not create one in place at the
+repository root (`python3 -m venv .`): `setup.sh` refuses to run in that
+situation, and the stray `bin/`, `lib/`, `include/` and `pyvenv.cfg` would
+shadow the real environment.
+
+## Running
+
+Compile a DSL file and print its SVG space-time diagram to stdout:
+
+```bash
+source .venv/bin/activate
+spacetime example.txt        # equivalently: python -m spacetime example.txt
+```
+
+To inspect every compiler stage instead, add `--print-stages`. Only the
+frontend runs: it prints the Lark parse tree, the intermediate `Ast`, and
+the refined AST, each under a header, and no SVG is rendered:
+
+```bash
+spacetime --print-stages example.txt
+```
+
+Run the test suite:
+
+```bash
+source .venv/bin/activate
+pytest -q
+```
+
+## Specification
+
+- [`spacetime/grammar.lark`](spacetime/grammar.lark) — the entire
+  specification: the concrete syntax, plus the semantic rules documented
+  as an attribute grammar in comments.
+- [`docs/qualidade.md`](docs/qualidade.md) — language and grammar quality
+  evaluation (TP1, task 4), with metrics from `docs/metricas_gramatica.py`.
+
+## Linguagem para escrever lamport space-time diagrams
+
+Example:
+```
+Processes {
+  p
+  q
+  r
+}
+
+Messages {
+  request := "Request o que quiser"
+  ack := "Ack"
+  vote := "Votes for leader"
+}
+
+History {
+  m1 := Send(request) :: p -> q
+  Recv(m1) :: q
+
+  m2 := Send(ack) :: q -> p, q, r
+  Recv(m2) :: p, q
+
+  m3 := Send(request) :: r -> q
+  Recv(m3) :: q
+}
+```
+
+
+Results in:
+
+![Space time diagram](./docs/sample.svg)

spacetime_dsl-0.1.0/README.md

@@ -0,0 +1,78 @@
+## Setup
+
+Requires Python 3.10 or newer (developed and tested on 3.13).
+
+Run `./setup.sh` to create the virtual environment and install the project.
+It performs an editable install (`pip install --editable . --group dev`), so
+`import spacetime` resolves to this checkout and the `spacetime` command is
+available inside `.venv/bin/`. Dependencies live in `pyproject.toml`.
+
+The environment lives **only** in `.venv/`. Do not create one in place at the
+repository root (`python3 -m venv .`): `setup.sh` refuses to run in that
+situation, and the stray `bin/`, `lib/`, `include/` and `pyvenv.cfg` would
+shadow the real environment.
+
+## Running
+
+Compile a DSL file and print its SVG space-time diagram to stdout:
+
+```bash
+source .venv/bin/activate
+spacetime example.txt        # equivalently: python -m spacetime example.txt
+```
+
+To inspect every compiler stage instead, add `--print-stages`. Only the
+frontend runs: it prints the Lark parse tree, the intermediate `Ast`, and
+the refined AST, each under a header, and no SVG is rendered:
+
+```bash
+spacetime --print-stages example.txt
+```
+
+Run the test suite:
+
+```bash
+source .venv/bin/activate
+pytest -q
+```
+
+## Specification
+
+- [`spacetime/grammar.lark`](spacetime/grammar.lark) — the entire
+  specification: the concrete syntax, plus the semantic rules documented
+  as an attribute grammar in comments.
+- [`docs/qualidade.md`](docs/qualidade.md) — language and grammar quality
+  evaluation (TP1, task 4), with metrics from `docs/metricas_gramatica.py`.
+
+## Linguagem para escrever lamport space-time diagrams
+
+Example:
+```
+Processes {
+  p
+  q
+  r
+}
+
+Messages {
+  request := "Request o que quiser"
+  ack := "Ack"
+  vote := "Votes for leader"
+}
+
+History {
+  m1 := Send(request) :: p -> q
+  Recv(m1) :: q
+
+  m2 := Send(ack) :: q -> p, q, r
+  Recv(m2) :: p, q
+
+  m3 := Send(request) :: r -> q
+  Recv(m3) :: q
+}
+```
+
+
+Results in:
+
+![Space time diagram](./docs/sample.svg)

spacetime_dsl-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+# Build configuration for the `spacetime-dsl` distribution.
+#
+# The importable package is `spacetime/` (flat layout, repo root); the
+# distribution is named `spacetime-dsl` only to avoid colliding with the
+# unrelated `spacetime` project on PyPI. Nothing here is published yet.
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spacetime-dsl"
+version = "0.1.0"
+description = "Compiler front-end for a DSL describing Lamport space-time diagrams"
+readme = "README.md"
+requires-python = ">=3.10"
+# Runtime dependencies only. `lark` is what spacetime/parser.py imports;
+# the LarkAG fork that used to be listed here was never imported.
+dependencies = [
+    "lark==1.3.1",
+]
+
+[project.scripts]
+# `spacetime FILE` — argv is passed to cli.main, whose return value becomes
+# the process exit code (0 ok, 1 DSL or I/O error).
+spacetime = "spacetime.cli:main"
+
+[dependency-groups]
+# Install with: pip install --editable . --group dev
+dev = [
+    "pytest>=8",
+]
+
+[tool.setuptools]
+# Explicit: example.txt, tests/ and exercicios_random/ also sit at the repo
+# root and must not be picked up by flat-layout auto-discovery.
+packages = ["spacetime"]
+
+[tool.setuptools.package-data]
+# grammar.lark is read at runtime via Path(__file__).with_name("grammar.lark"),
+# so it must ship inside the package or an installed copy cannot parse anything.
+spacetime = ["grammar.lark"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spacetime_dsl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spacetime_dsl-0.1.0/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_dsl-0.1.0/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_dsl-0.1.0/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