Enum Comprehension 

pub enum Comprehension {
    Clause {
        name: String,
        source: Source,
    },
    Cartesian {
        children: Vec<Comprehension>,
    },
    Zip {
        children: Vec<Comprehension>,
        mode: ZipMode,
    },
    Union {
        children: Vec<Comprehension>,
    },
    Filter {
        child: Box<Comprehension>,
        predicate: String,
    },
    Order {
        child: Box<Comprehension>,
        strategy: StrategyName,
        truncation: Option<u64>,
    },
}

The six-variant operator-tree comprehension.

Closure under composition (spec §4.1 C1): every variant holds one or more Comprehension operands plus constructor-specific scalar parameters (predicate, strategy, truncation, zip mode, source).

Box<Comprehension> appears wherever a variant needs a single child operand; Vec<Comprehension> wherever a constructor takes N children (cartesian, zip, union).

Variants

Clause

Leaf source per spec §3.1. Binds name to one value per dispense, drawn from source.

Fields

name: String

The name bound.

source: Source

Where the values come from.

Cartesian

Cross-product combinator per spec §3.2. Children must have disjoint name sets (V1).

Fields

children: Vec<Comprehension>

The factors.

Zip

Lockstep combinator per spec §3.3. Children must be discrete (V7) and have disjoint name sets (V1).

Fields

children: Vec<Comprehension>

The streams zipped.

mode: ZipMode

The length policy.

Union

Concatenation combinator per spec §3.4. Children must share an identical tuple shape (V2) and all be discrete (V9).

Fields

children: Vec<Comprehension>

The streams concatenated, in order.

Filter

Selection modifier per spec §3.5. Predicate is a GK boolean expression; names must close over the child’s coordinates plus the parent scope (V3).

Fields

child: Box<Comprehension>

The stream filtered.

predicate: String

The predicate, a boolean expression over the tuple and the parent scope.

Order

Permutation modifier per spec §3.6. strategy must accept the child’s IndexFn (V4); truncation limits the dispensed count.

Fields

child: Box<Comprehension>

The stream ordered.

strategy: StrategyName

The strategy applied.

truncation: Option<u64>

The dispensed count cap, if any.

Implementations

impl Comprehension

pub fn clause<S>(name: S, source: Source) -> Comprehension

where S: Into<String>,

Construct a leaf clause.

pub fn cartesian(children: Vec<Comprehension>) -> Comprehension

Construct a cartesian over the supplied children.

pub fn zip(children: Vec<Comprehension>, mode: ZipMode) -> Comprehension

Construct a zip over the supplied children with the given mode.

pub fn union(children: Vec<Comprehension>) -> Comprehension

Construct a union over the supplied children.

pub fn filter<S>(child: Comprehension, predicate: S) -> Comprehension

where S: Into<String>,

Construct a filter wrapping child with predicate.

pub fn order( child: Comprehension, strategy: StrategyName, truncation: Option<u64>, ) -> Comprehension

Construct an order node wrapping child.

pub fn coordinate_names(&self) -> Vec<String>

Compute the comprehension’s coordinate name set, recursively. The result preserves declaration order (per spec §3.2 + §3.4’s “in declaration order” tuple shape rules). Used by V1, V2, V3, and the predicate analyzer’s coord-set input.

pub fn coordinate_specs(&self) -> Vec<(String, String)>

Compute (coordinate_name, source_text) pairs in declaration order, deduplicated by name (first occurrence wins). Source text is the round-trip-to- legacy form — IntRange { 1, 10, 1 } → "1..10", Literal { [10, 100] } → "10, 100", etc.

Used by the runtime’s per-iter scope-kernel synthesis to construct a [(var, spec_expr)] list for type detection (per build_for_each_scope_kernel’s probe pre-evaluation).

pub fn referenced_source_names(&self) -> BTreeSet<String>

Grammar-based extraction of the free names referenced by every source spec in this comprehension subtree — workload params, outer iter-vars, and wires that a Generator spec (concat(foo), bare eh_values) consumes. Each spec is parsed with the canonical Polydat expression grammar (crate::refs::referenced_names) rather than byte-scanned, so a bare source reference is recognised exactly as the kernel compiler would resolve it. WorkloadParamList { name } contributes name directly; literals / ranges / intervals contribute nothing. Used by the workload validator’s declared-but-unreferenced check.

pub fn is_clause(&self) -> bool

true if this node is a leaf clause.

pub fn is_combinator(&self) -> bool

true if this node is one of the three combinators.

pub fn is_modifier(&self) -> bool

true if this node is a modifier (filter or order).

pub fn children(&self) -> Box<dyn Iterator<Item = &Comprehension> + '_>

Iterate this node’s direct operand children. Returns an empty iterator for leaf clauses.

pub fn node_count(&self) -> usize

Count of nodes in the AST (this node + all descendants). Used by the optimizer’s well-founded measure for termination (spec §10.6.3).

pub fn depth(&self) -> usize

Maximum depth of the AST. Constant for flat composition, O(log N) for balanced trees. Bounds the operator stack per spec §9.3.

impl Comprehension

pub fn metadata(&self) -> Metadata

Compute this node’s metadata bundle per spec §10.7.2.

Bottom-up: every child’s metadata is computed first, then this node’s. Constant-time per node above the child cost. Total — never fails, never partial.

For non-leaf nodes the metadata is recomputed on every call (no caching at this layer); consumers that need memoization should wrap externally. This is fine because the propagation cost is O(N) total nodes and the optimizer (Phase 6) re-propagates after each rewrite anyway.

Trait Implementations

impl Clone for Comprehension

fn clone(&self) -> Comprehension

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Comprehension

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Comprehension

fn deserialize<__D>( __deserializer: __D, ) -> Result<Comprehension, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Comprehension

fn eq(&self, other: &Comprehension) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Comprehension

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Comprehension