giles
ce8fed6b22
Some checks failed
Test, Build, and Deploy / test-build-deploy (push) Failing after 24s
98 lines
4.9 KiB
Plaintext
98 lines
4.9 KiB
Plaintext
;; lib/datalog/datalog.sx — public API documentation index.
|
||
;;
|
||
;; This file is reference-only — `load` is an epoch-protocol command,
|
||
;; not an SX function, so it cannot reload a list of files from inside
|
||
;; another `.sx` file. To set up a fresh sx_server session with all
|
||
;; modules in scope, issue these loads in order:
|
||
;;
|
||
;; (load "lib/datalog/tokenizer.sx")
|
||
;; (load "lib/datalog/parser.sx")
|
||
;; (load "lib/datalog/unify.sx")
|
||
;; (load "lib/datalog/db.sx")
|
||
;; (load "lib/datalog/builtins.sx")
|
||
;; (load "lib/datalog/aggregates.sx")
|
||
;; (load "lib/datalog/strata.sx")
|
||
;; (load "lib/datalog/eval.sx")
|
||
;; (load "lib/datalog/api.sx")
|
||
;; (load "lib/datalog/magic.sx")
|
||
;; (load "lib/datalog/demo.sx")
|
||
;;
|
||
;; (lib/datalog/conformance.sh runs this load list automatically.)
|
||
;;
|
||
;; ── Public API surface ─────────────────────────────────────────────
|
||
;;
|
||
;; Source / data:
|
||
;; (dl-tokenize "src") → token list
|
||
;; (dl-parse "src") → parsed clauses
|
||
;; (dl-program "src") → db built from a source string
|
||
;; (dl-program-data facts rules) → db from SX data lists; rules
|
||
;; accept either dict form or
|
||
;; list form with `<-` arrow
|
||
;;
|
||
;; Construction (mutates db):
|
||
;; (dl-make-db) empty db
|
||
;; (dl-add-fact! db lit) rejects non-ground
|
||
;; (dl-add-rule! db rule) rejects unsafe rules
|
||
;; (dl-rule head body) dict-rule constructor
|
||
;; (dl-add-clause! db clause) parser output → fact or rule
|
||
;; (dl-load-program! db src) string source
|
||
;; (dl-set-strategy! db strategy) :semi-naive default; :magic
|
||
;; is informational, use
|
||
;; dl-magic-query for actual
|
||
;; magic-sets evaluation
|
||
;;
|
||
;; Mutation:
|
||
;; (dl-assert! db lit) add + re-saturate
|
||
;; (dl-retract! db lit) drop EDB, wipe IDB, re-saturate
|
||
;; (dl-clear-idb! db) wipe rule-headed relations
|
||
;;
|
||
;; Query / inspection:
|
||
;; (dl-saturate! db) stratified semi-naive default
|
||
;; (dl-saturate-naive! db) reference (slow on chains)
|
||
;; (dl-saturate-rules! db rules) per-rule-set semi-naive worker
|
||
;; (dl-query db goal) list of substitution dicts
|
||
;; (dl-relation db rel-name) tuple list for a relation
|
||
;; (dl-rules db) rule list
|
||
;; (dl-fact-count db) total ground tuples
|
||
;; (dl-summary db) {<rel>: count} for inspection
|
||
;;
|
||
;; Single-call convenience:
|
||
;; (dl-eval source query-source) parse, run, return substs
|
||
;; (dl-eval-magic source query-source) single-goal → magic-sets
|
||
;;
|
||
;; Magic-sets (lib/datalog/magic.sx):
|
||
;; (dl-adorn-goal goal) "b/f" adornment string
|
||
;; (dl-rule-sips rule head-adn) SIPS analysis per body lit
|
||
;; (dl-magic-rewrite rules rel adn args)
|
||
;; rewritten rule list + seed
|
||
;; (dl-magic-query db query-goal) end-to-end magic-sets query
|
||
;;
|
||
;; ── Body literal kinds ─────────────────────────────────────────────
|
||
;;
|
||
;; Positive (rel arg ... arg)
|
||
;; Negation {:neg (rel arg ...)}
|
||
;; Comparison (< X Y), (<= X Y), (> X Y), (>= X Y),
|
||
;; (= X Y), (!= X Y)
|
||
;; Arithmetic (is Z (+ X Y)) and (- * /)
|
||
;; Aggregation (count R V Goal), (sum R V Goal),
|
||
;; (min R V Goal), (max R V Goal),
|
||
;; (findall L V Goal)
|
||
;;
|
||
;; ── Variable conventions ───────────────────────────────────────────
|
||
;;
|
||
;; Variables: SX symbols whose first char is uppercase A–Z or '_'.
|
||
;; Anonymous '_' is renamed to a fresh _anon<N> per occurrence at
|
||
;; rule/query load time so multiple '_' don't unify.
|
||
;;
|
||
;; ── Demo programs ──────────────────────────────────────────────────
|
||
;;
|
||
;; See lib/datalog/demo.sx — federation, content, permissions, and
|
||
;; the canonical "cooking posts by people I follow (transitively)"
|
||
;; example.
|
||
;;
|
||
;; ── Status ─────────────────────────────────────────────────────────
|
||
;;
|
||
;; See plans/datalog-on-sx.md — phase-by-phase progress log and
|
||
;; roadmap. Run `bash lib/datalog/conformance.sh` to refresh
|
||
;; `lib/datalog/scoreboard.{json,md}`.
|