Struct ComposeAdapter 

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

Implementations

impl<A: AstAdapter> ComposeAdapter<A>

pub fn new(outer: A) -> Self

pub fn with_csv_options(self, csv: CsvOptions) -> Self

The delimited-text options for this mount (builder-style).

pub fn with_decoding(self, decoding: SourceDecoding) -> Self

The source-boundary rule for this mount (builder-style): the ?encoding= option and the reporter the host chose. Reaches grafted archives too.

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 children_named(&self, node: NodeId, name: &str) -> Vec<NodeId>

A child by name: the outer source’s own lookup first (a database reads /books/7 by key), and the listing only where the node may hold a grafted document — a leaf with a path or with text. A miss on a node that cannot hold one stays a miss, without listing its children.

fn walks_for_references(&self) -> bool

The walk is open when the outer tree opens to it (a graft is read whole once reached).

fn can_refer_to(&self, source: NodeId, target: NodeId) -> Option<bool>

A declaration answers on its own side of the boundary; across it only a reference property of the source’s own can reach.

fn index_referrers( &self, scope: &str, property: &str, label: Option<&str>, target: NodeId, ) -> Option<Vec<NodeId>>

The outer source’s own index over a scope of its own nodes (a database reading /books/* by key).

fn resolves_references(&self) -> bool

The outer source, or any document grafted so far.

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<ExternalRef>

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, the graft’s own; on the outer tree, the outer’s declared references (a catalog key, a model ref), which no graft can hold a referrer for.

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 reference_properties(&self, source: NodeId, target: NodeId) -> Vec<String>

The reference properties declared on source that can land in target’s container: a catalog’s key columns into the target’s table, the fields of a model’s refs, the node’s own reference property. What t<-- and t<--(SCOPE) read when the query names no property; empty where none is declared.

fn tree_identities(&self) -> Vec<(String, NodeId)>

The trees of this arbor other trees refer to by name: each identity (a URL, a path, any string a reference may hold) with the node that stands for the tree. An identity ending in a separator is a base: every identity beneath it names the node reached beneath the base’s node by the remainder’s segments. Declared in a model (tree IDENTITY: PATH;) and automatic for a mount’s own target; the engine reads nothing inside an identity beyond prefix and separator.

fn reverse_label(&self, target: NodeId) -> Option<String>

The reference label under which a referrer’s property is also resolved when a reverse arrow asks about target and the query writes no label. None (the default): only the label-less resolution counts. An adapter whose label names a container (a table, a collection, a node label) returns the one target stands in, so /authors/1<--(/books/*::author_id) reads author_id as a key into authors without the query saying so. The engine derives no label of its own.

fn resolve_needs_label(&self, node: NodeId, property: &str) -> bool

Whether resolving property of node needs a reference label, because the property itself declares no target: a column with no key, or any property of a property graph, where a value names a node only under a node label. A label-less ::p--> over such a property is refused with the remedy, since an empty answer would read as “points nowhere”.

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

The names of the properties a node has — what “any property” means for <--(SCOPE::*). By default its off-tree properties, its reference property, and its children’s names (a row’s columns, an object’s keys are properties under the same names); an adapter whose properties are not children (an element’s attributes) lists them.

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 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 select(&self, from: NodeId, plan: &StepPlan<'_>) -> Option<Selection>

The search fast path: the nodes one step reaches from from under plan, answered from an index — None keeps the engine’s walk (the default folds children_named, descendants_named and descendants_where: select_by_hooks). Some must be exactly what the walk would find for the conjuncts it marks applied, under the engine’s standard equality; the engine tests the remaining conjuncts and every other predicate on the nodes returned. A child plan’s answer is never re-filtered by name (the adapter owns the name test, as children_named does); a descendant plan’s nodes still pass the nameless tests.

fn index_lookup( &self, scope: &str, property: &str, value: &Value, ) -> Option<Vec<NodeId>>

index SCOPE::prop; — the nodes of the declared scope whose property holds value, from an index the model keeps; None when no declaration covers the pair (the walk answers). An index changes cost, never the answer: the caller still tests each node it names.

fn select_plan(&self, scope: &[&str], plan: &StepPlan<'_>) -> Option<Vec<bool>>

The dry-run form of select: which of the plan’s conjuncts the adapter would apply, decided from its catalog alone (a column’s existence and type, an index’s presence), with no node in hand. scope is the literal path from the root to the step’s base (["invoices"] for /invoices/*[...]), empty at the root. None when the adapter cannot say — the static plan then counts every conjunct as the engine’s.

fn estimate(&self, scope: &[&str], plan: &StepPlan<'_>) -> Option<Estimate>

What reaching one step’s nodes would cost, said from the catalog with no node in hand (scope as for select_plan): a warehouse’s dry run, a table’s statistics, a file’s size, an arena’s count. None where the adapter has no estimator — the plan then reads “unknown” for the step.

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.

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; a run may override it (Run::quantifier_bound, the CLI’s --quantifier-bound). The shell gate and the invocation instant are the run’s alone (Run::allow_shell, Run::now).

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 count(&self, _from: NodeId, _plan: &StepPlan<'_>) -> Option<usize>

How many nodes one step reaches from from under plan, without materializing them — @| count right after the step asks before walking. None walks; Some must be exactly the walk’s count for the conjuncts the plan carries (every one of them, or none: a count cannot be partially applied). SQL: SELECT COUNT(*); a document index: the bucket’s length.

fn prefetch_properties(&self, _nodes: &[NodeId], _names: &[&str])

A batching hint, the projection twin of prefetch_links: the engine is about to read the properties names of every node in nodes (the next stage projects them). A remote adapter fetches the columns for the frontier in one round trip; semantics are unchanged either way.