Skip to content

[FEATURE] EBNF grammar specification and semantics documentation #233

Closed

Description

@adityamukho

Summary

Formal grammar specification and semantics documentation for the Minigraf Datalog query language.

Parent issue

Closes part of #230.

Deliverables

1. Conformance test harness

A machine-verifiable harness that ensures the grammar document exactly matches parser behaviour — so the spec can never silently diverge from the implementation.

  • tests/grammar/grammar.pest — executable PEG grammar (pest), the machine-checkable equivalent of the EBNF doc
  • tests/grammar/valid/ — corpus of structurally and semantically valid inputs (pest accepts + parser accepts)
  • tests/grammar/invalid/syntax/ — structurally malformed inputs (pest rejects + parser rejects)
  • tests/grammar/invalid/semantic/ — syntactically valid but semantically rejected inputs (pest accepts + parser rejects)
  • tests/grammar_conformance.rs — three #[test] functions, one per bucket, full-failure reporting

2. EBNF grammar document

Human-readable EBNF notation for the full query language syntax, derived from grammar.pest. Covers all EDN primitives, containers, top-level commands (transact, retract, query, rule), query clauses (:find, :where, :as-of, :valid-at, :with), where-clause variants (not, not-join, or, or-join, expr), aggregates, and window functions.

3. Semantics documentation

Prose documentation of the constraints enforced above the structural grammar layer:

  • Not-safety (variables in not/not-join must be bound in outer clauses)
  • Expression variable binding rules
  • Aggregate and :with variable binding requirements
  • Window function compatibility rules
  • UUID and ISO 8601 timestamp validation

Out of scope

Tutorials — tracked separately in #230.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions