Crate quarb 

The Quarb query engine.

Quarb is a query language for arbors — tree-spanned graphs. This crate is the engine: it lexes and parses a query, then evaluates it against an AstAdapter that maps some data source onto the arbor model.

It currently implements tree navigation in full (child, descendant, parent, ancestor, and sibling hops; proximal/distal reach; root and leaf anchors; literal, glob, and ~(...) regex name matching; <trait> filters), scalar projection (:: properties, ::: core metadata, ;;; adapter metadata), [...] predicates (comparisons, and/or/not/!, structural conditions, index selection), || union, -> / <- crosslink navigation, path patterns ((...) groups with subpath alternation and +/*/{m,n} quantifiers — simple-path expansion under the adapter’s quantifier bound), and the register system: per-capsa | f transforms, @| f whole-context aggregation, | . push and | $. recall of breadcrumbs, and | .(expr) subcontexts for grouped aggregation. It also does correlation: E1 <=> E2[…$*1…] joins two contexts, a predicate referencing a prior expression’s context via $*N. It also resolves cross-references: ::prop--> maps a reference to its target node (a JSON adapter follows a $ref JSON Pointer). The reverse resolution <-- and pattern search => are not built yet. See doc/impl.tex.

let hits = run("//*.rs", &Empty).unwrap();
assert!(matches!(hits, QueryResult::Nodes(ns) if ns.is_empty()));

Re-exports

pub use adapter::AllowShell;

pub use adapter::AstAdapter;

pub use adapter::NodeId;

pub use adapter::QuantifierBound;

pub use adapter::WithNow;

Modules

adapter

The adapter surface: how a data source plugs into the engine.

highlight

Syntax highlighting for query text — one tokenizer, three emits.

quantity

The quantital fragment: unit-text parsing behind Value::Quantity (spec: The Quantital Fragment).

reflect

Reflection: the query arbor.

temporal

The temporal fragment: ISO-8601 parsing and formatting, and the civil-calendar arithmetic behind Value::Instant and Value::Duration.

Structs

Defs

A table of named fragments (def &name: body;), expanded at parse time. Names are unique; a definition may invoke only earlier definitions, so recursion is impossible by construction.

Enums

QuarbError

Errors raised while lexing, parsing, or executing a query.

QueryResult

The result of evaluating a query: a node set, or,—,after a projection,—,a list of scalar values (one per node).

Value

A projected scalar value.

Functions

base64

RFC 4648 base64, padded.

base64_decode

RFC 4648 base64 decoding (standard alphabet, padding and whitespace tolerated). None on any other character.

expand

Parse query (expanding defs) and render it back to canonical query text — the expansion lens (qua --expand). Pure fragments only: a data-aware macro (&name!) needs expand_with.

expand_with

Like expand, with the dataset at hand, so data-aware macros (&name!) can read it at expansion time.

is_calculator

True if query (inline defs allowed) opens with an expression head or a lone root anchor and never navigates a document: every branch is a step-less, projection-less root anchor and there are no correlations. Such a query can run against a bare root with no mounted target — the calculator invocation (spec: The Expression Head). Unparseable text answers false; the caller’s normal run path owns the error message.

parse_defs

Parse a definitions file — def &name(params): body; statements only — into a fragment table for run_with_defs. Lines whose first non-blank character is # are comments: a defs file is a library, and a library wants a header. (Query text proper has no comment syntax — queries are one-liners; the annotation lives in the defs file.)

run

Lex, parse, and evaluate query against adapter.

run_traced

Like run, but returning the final capsae as (node, topic) pairs, so each result value still knows which node produced it — the provenance-bearing form used by typed emission (qua --daiv). A None topic is a node result.

run_traced_with_defs

Like run_traced, with a pre-seeded fragment table.

run_with_defs

Like run, with a pre-seeded fragment table (a --defs file); inline def statements extend it.

sha256

The SHA-256 digest of data, as 32 raw bytes (FIPS 180-4).

sha256_hex

The SHA-256 digest of data, as lowercase hex.

strip_defs_comments

Blank out the # comment lines of a defs file, preserving line structure. Session layers that prepend defs text to query text (quai, the notebook kernels) must store the stripped form — the query lexer itself has no comment syntax.

Type Aliases

Result

Convenience alias for engine results.