qql_core/lib.rs
1//! QQL language frontend: lexer, parser, typed AST, explain, and formatting.
2//!
3//! `qql-core` is the single owner of the QQL language surface. It performs no
4//! I/O: no networking, no file access, and no knowledge of Qdrant REST JSON or
5//! gRPC protobuf shapes. Lowering to transports lives in `qql-plan`
6//! (transport-neutral plans plus an optional REST projection) and the executor
7//! crate `qql` (REST / gRPC / edge execution).
8//!
9//! With default features the crate builds without third-party dependencies;
10//! `serde` and `json` are opt-in for AST serialization and dynamic-value
11//! conversion. Parser-only consumers — formatters, linters, language servers,
12//! code generators — therefore embed it cheaply.
13//!
14//! # Entry points
15//!
16//! - [`parser::Parser`] — source text → typed [`Stmt`](ast::Stmt) AST with
17//! strict validation (`Parser::parse_all` for multi-statement scripts)
18//! - [`ast::inject_filter`] — inject a typed comparison into an existing AST
19//! - [`explain`] — tree-formatted statement dumps for humans
20//! - [`fmt`] — canonical formatter; output re-parses to an identical AST
21//! - [`params`] — `:name` / `?` placeholder binding and substitution
22//!
23//! # Errors
24//!
25//! Every failure is a structured [`error::QqlError`] carrying a stable `code`,
26//! an explicit [`ErrorKind`](error::ErrorKind), and a byte-offset
27//! [`Span`](error::Span).
28
29extern crate alloc;
30
31/// Typed abstract syntax tree: statements, filter and formula expressions,
32/// values, and AST transforms.
33pub mod ast;
34/// Structured errors: stable codes, explicit [`ErrorKind`](error::ErrorKind),
35/// byte-offset spans.
36pub mod error;
37/// Tree-formatted statement explanations.
38pub mod explain;
39/// Canonical QQL formatter with parse → format → parse round-trip guarantees.
40pub mod fmt;
41/// Byte-offset lexer: source text → [`Token`](token::Token) stream.
42pub mod lexer;
43/// Parameter binding for `:name` / `?` placeholders with type-checked
44/// substitution.
45pub mod params;
46#[cfg(feature = "json")]
47/// Host-language parameter binding over JSON-shaped `params` values: the
48/// single batch-dispatch contract shared by every SDK binding.
49pub mod params_json;
50/// Recursive-descent parser: token stream → validated typed AST.
51pub mod parser;
52/// Lexical token kinds, spans, and keyword lookup tables.
53pub mod token;
54
55#[cfg(test)]
56mod tests;