Implementation reference

To run the word tutorial in an application, load an array of strings, expose it as words and pass the user’s expression to Zirql. The application then handles the result. The complete Rust example shows this integration.

For an application over files, Build the CSV host explains how to load typed rows, expose bindings and evaluate a query before writing JSON. Its usage guide shows the input tables, queries, results and commands together.

An application can also expose its own objects and operations. This reference explains the Rust adapter interfaces, then follows the word model into native occurrences, source ownership and navigation.

Choose a data model

Your input	Useful representation	Application responsibilities
Words, numbers or report rows	Constructed arrays and records	Load data, expose bindings, handle results
Source occurrences	Records with offsets, or borrowed native items	Preserve source ownership and coordinates
Syntax nodes or operations	Native handles	Define identity, predicates, navigation and projections
Domain enums and indexed data	Nominal members and keyed arrays	Resolve identities and enforce domain shape rules

Constructed values often suffice. The adjacent-pair expression needs only an array of strings. Native values let queries retain references to existing objects and use operations that need their document or model context.

The adapter examples explain Zincite and Zirium’s choices at these boundaries. Usage instructions belong to their own documentation.

Connect text to evaluation

The library has several entry points, each suited to a different integration:

Entry point	Use
read_value_expression, read_value_expression_in_scope and ValueReaderHost	Parse shared expressions and delegate domain syntax
evaluate_query_value and ValueQueryHost	Evaluate constructed data with explicit binding reads and native leaves
parse_pipeline and Host	Embed the small filter/head/count pipeline reader
ProgramHost and ProjectionHost	Execute native programs and correlated report fields
Located Rust expression and program types	Integrate an existing parser or build queries directly
FunctionRequest / PreparedFunctions	Prepare typed pure functions and evaluate them with the active host

The word example uses the first two rows. Its reader knows one binding, and its value adapter supplies that binding under the same budget as evaluation. Add the other interfaces when your application needs native pipelines, programs or named functions.

Embedding in Rust describes hook obligations, native ownership, validation and projection. Construct programs in Rust shows program builders, parameters, functions and control-flow representations. The value evaluation reference covers expression nodes, type facts and owned results. Generate cargo doc --open for signatures at your dependency revision.

Define domain operations

A host can add a predicate such as prefix, a navigation step such as next_word, or a projection such as text. It parses the operation’s arguments into a typed payload and supplies its meaning during evaluation.

Keep generic language behavior in Zirql. For example, a host supplies direct edges and identity for path traversal; Zirql finds a bounded shortest witness. A host supplies a string projection; Zirql groups and sorts the resulting rows. The word-model extensions show how to choose these operations without making them part of the base language.

The shared reader owns generic query grammar, including common and MiniZinc comprehensions, records, conditionals and indexed literals. Domain arguments reenter the scoped expression reader. A narrow parse_domain_call hook handles signatures that require native/model facts, such as enum member resolution. The adapter call sequence keeps full-AST admission and actual input-file parsing with the host. Typed callers can also build located Rust trees directly.

Preserve ownership and enforce limits

Native handles retain their source or document owner. Equal printed names do not establish identity. The host rejects stale or foreign handles and decides which facts are complete enough to use.

Pass one budget through parsing, validation, native callbacks, copying and rendering. Charge host scans and admit allocations before doing the work. Nested evaluation continues with the remaining allowance. The budget and diagnostic API reference describes what the core charges and what the host must account for.

Return data and control effects

Results can remain Rust values. Rendering is an application decision: inspect the returned records, serialize them, or use native handles in another operation. The evaluator does not require a JSON conversion between stages.

If an application supports edits, it owns their legality and commit policy. Pure expression and function contexts must reject effects during preflight. Applications that promise all-or-nothing output must buffer or validate before publishing it. See library results and rendering.

Understand the implementation

The execution and cost guide explains what happens within a request, where values share storage and when results need copying. Read it when sizing a request budget or investigating an expensive query. A separate measurement report records a comparison of two evaluator revisions, including their small-query overhead.