Struct ComposeAdapter 

pub struct ComposeAdapter<A: AstAdapter> { /* private fields */ }

Implementations

impl<A: AstAdapter> ComposeAdapter<A>

pub fn new(outer: A) -> Self

pub fn with_document_reader(self, reader: DocumentReader) -> Self

Hand document leaves to the host’s reader first (builder-style); needs the outer leaves’ paths (with_source_paths).

pub fn with_document_urls( self, document_url: fn(&A, NodeId) -> Option<String>, ) -> Self

Declare where each outer leaf’s document is served from (builder-style): a text-level graft joins its relative references against that URL, and --> from any graft lands on the leaf holding the referenced document (its fragment’s bearer when named) without a host registration.

pub fn with_source_graft(self, graft: SourceGraft) -> Self

Choose the level source-file leaves graft at (builder-style; the default is the syntax level).

pub fn with_document_graft(self, graft: DocumentGraft) -> Self

Choose the level marked-up documents graft at (builder-style; the default is the DOM).

pub fn with_source_paths( outer: A, source_path: fn(&A, NodeId) -> Option<PathBuf>, ) -> Self

Like new, with a hook mapping outer leaves to filesystem paths, so archive leaves (.zip, .tar[.gz]) graft too. The grafted archive composes in turn: its own parseable entries graft, and one path walks filesystem → archive → document.

pub fn outer(&self) -> &A

The wrapped adapter (for outer-specific calls).

pub fn locator( &self, node: NodeId, outer_locator: impl Fn(NodeId) -> String, ) -> String

A combined locator: outer_locator(leaf)!inner-path for grafted nodes.

Trait Implementations

impl<A: AstAdapter> AstAdapter for ComposeAdapter<A>

fn non_tree_nodes(&self) -> Vec<NodeId>

The outer tree’s non-tree nodes, then each graft’s (the grafts already read).

fn answers_to(&self, node: NodeId, name: &str) -> bool

A written name reaches a node by the owning adapter’s rule (its aliases included).

fn traits(&self, node: NodeId) -> Vec<String>

The graft root IS the outer leaf, so the leaf wears the grafted document’s own traits too — a page’s declared tags on the file that holds it.

fn aliased_metadata(&self, node: NodeId) -> &'static [&'static str]

A graft’s own aliases are not merged: a node either belongs to the outer document or to a graft, and the alias list is consulted only after the owning adapter’s property misses.

fn provenance(&self, node: NodeId) -> Provenance

A graft is a provenance layer: the grafted document’s own components win, and the outer leaf it was parsed from fills the rest (with an fs outer: the file’s path and mtime). The jar-style composite locator is deliberately not the source — ?src names a document, and the intra-document address is dpid’s job.

fn provenance_list(&self, node: NodeId) -> ProvenanceList

The same layering, entry by entry.

fn has_trait(&self, node: NodeId, name: &str) -> bool

A trait test reaches the graft — and, on the outer leaf, the graft’s root, as traits does.

fn external_ref( &self, node: NodeId, property: &str, hint: Option<&str>, ) -> Option<String>

A graft’s external references (a text-level ref leaving its document) come through; an outer leaf’s own do too.

fn resolve_fragment(&self, node: NodeId, fragment: &str) -> Option<NodeId>

A fragment lands inside the document: on an outer leaf that holds a graft, inside that graft.

fn document_by_ref(&self, id: &str) -> Option<NodeId>

The leaf serving a URL, from the declared document URLs; else whatever the outer answers.

fn reverse_resolve( &self, node: NodeId, property: Option<&str>, hint: Option<&str>, ) -> Option<Vec<NodeId>>

A reverse index answers on one side of the boundary only: inside a graft, or on the outer tree when no graft could hold a referrer (the outer’s answer cannot see grafts).

fn descendants_named( &self, node: NodeId, name: &str, ) -> Option<Vec<(NodeId, usize)>>

Inside a graft the graft’s index answers; on the outer tree a name may also live inside grafts, so the walk stays.

fn root(&self) -> NodeId

The root node — the initial navigation context.

fn children(&self, node: NodeId) -> Vec<NodeId>

The tree children of node, in document order.

fn name(&self, node: NodeId) -> Option<String>

The name of node — the label of its incoming tree edge.

fn parent(&self, node: NodeId) -> Option<NodeId>

The parent of node, or None for the root.

fn child_host(&self, node: NodeId) -> NodeId

The node whose children an explicit child step from node reads. The default is node itself. An adapter whose tree holds transparent links (a filesystem’s symlink to a directory) answers the link’s target, so /link/name lands on the target’s own child — the same node /target/name reaches. The descendant walk never consults this: it reads children alone, so a linked subtree is walked once, under its own parent, and a cycle of links cannot trap it.

fn properties(&self, node: NodeId) -> Vec<(String, Value)>

The node’s own properties, enumerated — name and value, in the source’s order — for readings that keep values off the tree (the JSON property reading, where an object’s scalar fields are no nodes). The serializers (| json, | xml, | kaiv) merge them with the children, a child winning a shared name. The default is none: for a reading whose values are all nodes, the children already say everything.

fn property(&self, node: NodeId, name: &str) -> Option<Value>

A named property of node — ::prop. None if absent.

fn default_value(&self, node: NodeId) -> Option<Value>

The default projection of node — bare ::, adapter-specific (a filesystem adapter returns file content).

fn metadata(&self, node: NodeId, key: &str) -> Option<Value>

Adapter-defined metadata — ::::key (a filesystem adapter’s size, modified, permissions, …). None if absent.

fn resolve( &self, node: NodeId, property: &str, hint: Option<&str>, ) -> Option<NodeId>

Resolve a cross-reference: ::property-->hint maps node’s property (a value that references another node) to its target, with an optional adapter-specific hint (a relation type such as an html rel, or a target container such as a table). A JSON adapter resolves a $ref JSON Pointer; None if unresolvable.

fn ref_property(&self, node: NodeId) -> Option<String>

The property carrying node’s own reference, for the bare arrow (//a-->): an html anchor’s href, an iframe’s src. None for a node that references nothing.

fn ref_label(&self, node: NodeId, property: &str) -> Option<String>

The relation name a resolution edge from node via property carries — html’s rel attribute. None falls back to the property name as the edge label.

fn prefetch_links(&self, nodes: &[NodeId], dir: LinkDir)

A batching hint: the engine is about to follow dir crosslinks from every node in nodes. An adapter backed by a store may fetch them in one statement; semantics are unchanged either way.

fn links(&self, node: NodeId) -> Vec<(String, NodeId)>

Outgoing crosslinks from node, as (label, target) pairs, for -> navigation (a filesystem adapter’s symlinks).

fn backlinks(&self, node: NodeId) -> Vec<(String, NodeId)>

Incoming crosslinks to node, as (label, source) pairs, for <- navigation. May be expensive (an adapter that does not precompute edges must search for referrers).

fn link_property( &self, source: NodeId, label: &str, target: NodeId, name: &str, ) -> Option<Value>

A property of the crosslink source --label--> target — the $-::prop read. Adapters whose edges carry data (a property graph’s relationship properties) override this; None if the edge is bare or unknown. Where parallel edges share source, label, and target, the adapter answers for one of them, consistently.

fn children_named(&self, node: NodeId, name: &str) -> Vec<NodeId>

The children of node whose edge name is exactly name — the engine’s fast path for name-matcher child hops. The default filters children; an adapter whose containers cannot be enumerated (permission-scoped or unbounded remote trees) overrides this with a direct, name-addressed lookup. Must be observationally identical to the default wherever enumeration works. The adapter owns the name test: it may deliberately alias — resolve a name to a node whose edge name differs (git revision syntax landing on a hash-named commit) — and the engine will not re-filter. Container-scoped resolution like that stays child-axis only; per-node spelling aliases belong in answers_to, which this default consults.

fn descendants_where( &self, _node: NodeId, _name: &str, _property: &str, _value: &Value, ) -> Option<Vec<(NodeId, usize)>>

The descendants of node named name whose property property equals value, each with its depth, in document order — the fast path behind //name[::property = "value"] for an adapter that indexes a property (the corpus reading’s positional index answers //token[::lower = "tom"] from it). None keeps the engine’s walk and its comparison; Some must be exactly what the walk would find under the standard equality, so an adapter answers only the values it can compare as the engine does (text against text).

fn quantifier_bound(&self) -> usize

The quantifier bound N_max: the depth to which open-ended path quantifiers (+, *, {m,}) expand, and the ceiling of any explicit {m,n} (the effective upper bound is min(n, N_max)). An adapter whose natural structures run deep may raise it; the CLI overrides it per run (qua --quantifier-bound).

fn allow_shell(&self) -> bool

Whether the sh(...) pipeline stage may run external commands. False by default — query text stays inert data — and enabled per run by the CLI (qua --allow-shell) through the AllowShell wrapper.

fn invocation_instant(&self) -> Option<(i64, u32)>

The invocation instant now() denotes (spec: The Temporal Fragment, Determinism): one UTC timeline point bound by the runner BEFORE evaluation begins — evaluation itself never reads a clock. None by default (a library run is fully deterministic; now() reads as null); the CLI binds it at startup — pinnable with qua --now — through the WithNow wrapper.

fn has_node(&self, node: NodeId) -> bool

Whether node is an id this adapter minted — the guard behind the node-id anchor ((!N)), which may name an id from an earlier run (ids are minted deterministically: the same source, the same ids). The default probes the id through parent and name and treats a panic as absence, so an adapter that indexes by id needs no override; one that can answer cheaply should.

fn unit_scale(&self, expr: &str) -> Option<(f64, String)>

The scale of a unit expression — (factor, canonical SI-base expansion) — for the unital reading’s criterion text (spec: The Quantital Fragment). The default answers from the engine’s frozen built-in table; a unit-aware adapter (kaiv) overrides it to include the mounted document’s own custom units, so [::range < '50kellicam'] resolves through the document’s .!units imports.