Struct Comprehension 

pub struct Comprehension {
    pub mode: ComprehensionMode,
    pub filter: Option<String>,
    pub order: Option<TraversalOrder>,
}

The static shape of an iteration scope. See module doc.

filter is an optional Polydat predicate evaluated against each emitted tuple. Tuples for which the predicate evaluates to Value::Bool(false) are skipped — children don’t run for them.

Predicate syntax: a string interpolation expression in the same shape as clause spec text — clause-bound names and inherited scope names appear as {name} placeholders, the rest is a const-evaluable expression. The evaluator interpolates {var} placeholders against the per-tuple kernel (which has every clause value installed and parent-scope wiring done), then runs eval_const_expr on the result. The expression must yield Value::Bool.

Examples:

• {k} * {limit} < 1000
• {profile} == "ann"
• {k} > {threshold} (where threshold is an inherited name)

Cartesian and Union modes both honor the same single filter — it composes uniformly over the cross product (one predicate against each tuple) regardless of how the tuple space was assembled.

Fields

mode: ComprehensionMode

How the tuple space is assembled: one cross product, or a union of subspaces.

filter: Option<String>

A predicate applied to every tuple, if any.

order: Option<TraversalOrder>

The traversal order, if one was written.

Implementations

impl Comprehension

pub fn cartesian(clauses: Vec<Clause>) -> Comprehension

A cross product of the clauses with no filter or order.

pub fn union(subspaces: Vec<Vec<Clause>>) -> Comprehension

A union of subspaces with no filter or order.

pub fn union_from(subspaces: Vec<Subspace>) -> Comprehension

Construct a Union from already-wrapped Subspace values. Use this when subspaces carry metadata; the union(...) shorthand wraps bare Vec<Clause> lists.

pub fn with_filter(self, predicate: impl Into<String>) -> Comprehension

Attach a filter predicate, returning self for builder chaining. The predicate is a Polydat expression that must evaluate to Value::Bool per tuple — anything else is a runtime error from the comprehension’s evaluator.

pub fn with_order(self, order: TraversalOrder) -> Comprehension

Attach a traversal order, returning self for builder chaining. See TraversalOrder and SRD-18d.

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

Variable names this comprehension declares, in declaration order, deduplicated. For Cartesian mode that’s exactly the LHS of each clause. For Union mode the names typically repeat across sub-spaces; dedup gives the operator-visible coordinate set (children see one extern per name regardless of sub-space count).

Order is first-occurrence (preserves the user’s authored intent — k before limit in "k in …, limit in …" stays in that order even after dedup).

pub fn flat_clauses(&self) -> Vec<&Clause>

Every clause in the comprehension flattened into one iterator, in declaration order. For Cartesian mode that’s the clause list directly; for Union mode it’s the concatenation of all sub-spaces’ clauses (preserving order, including any repeats — callers that want unique names should use Self::coordinate_names).

pub fn clause_count(&self) -> usize

Number of clauses across all sub-spaces (with repetition for Union mode). For Cartesian mode this is also the number of coordinates; for Union mode see Self::coordinate_names for the deduplicated count.

pub fn is_cartesian(&self) -> bool

Whether the mode is one cross product.

pub fn is_union(&self) -> bool

Whether the mode is a union of subspaces.

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

Validate the comprehension’s static structure. Returns the empty Ok(()) if every invariant holds; otherwise Err(messages) where each message names one violation.

This is the single entry point for AST-shape invariants — parse_comprehension_text, workload-load, dryrun, and any future linter all route through here so the rule set lives in exactly one place.

Checks performed:

1. Non-empty clause set. Cartesian must have ≥ 1 clause; Union must have ≥ 1 sub-space, each with ≥ 1 clause.
2. No coordinate-name collisions in Cartesian mode. Every variable must be unique across the clause list (Cartesian product of two clauses with the same name is undefined). Union mode permits repeated names — that’s the structural Union signal.
3. Order/mode compatibility. Index-space orderings (reverse_lex, diagonal, antidiagonal, extrema, shells, halton, sobol, lhs) require a single Cartesian lattice — they’re rejected on Union mode where there is no such lattice. lex and custom are accepted on both modes.

Filter / parallel-iter length checks happen at iteration time (they require evaluation, not just structure).

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 Display for Comprehension

Canonical text rendering of a comprehension: <clauses> [where <filter>] [order <spec>].

Cartesian: clauses are joined by , . Union: each sub-space is rendered as a parenthesised clause group joined by | to make the sub-space boundaries visible (the textual short-form parser detects Union via repeated-name signal, but the explicit form is what Display emits to keep the round-trip semantics-preserving regardless of sub-space layout).

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

Formats the value using the given formatter.

impl Eq for Comprehension

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