Module spec 

Comprehension specification surface — author-friendly input form for YAML / JSON consumers.

Polydat owns the conversion from a YAML/JSON-native structural form into the algebra-layer Comprehension AST. Consumers (nb-workload, REPL, tooling) deserialize into ComprehensionSpec via serde and call ComprehensionSpec::into_algebra; text-block consumers call parse_text which routes through serde for them.

Single for verb

Per spec §8.1, the surface has one keyword. The RHS shape disambiguates which constructor:

# Single clause
for: "k in 1..10"

# Multi-clause cartesian (one inline string)
for: "k in 1..10, limit in [10, 100, 1000]"

# Multi-clause cartesian (list of strings)
for:
  - "k in 1..10"
  - "limit in [10, 100, 1000]"

# Union of sub-spaces (list of clause lists)
for:
  - ["k in 10",  "limit in 1..50"]
  - ["k in 100", "limit in 1..500"]

With optional modifiers:

for: "k in 1..10, limit in 1..100"
where: "{k} * {limit} <= 1000"
order: "halton/50"

Architecture

The friendly surface delegates structural parsing to the existing legacy parsers in crate::comprehension::parse — parse_clause_list, parse_comprehension_text, parse_order_spec. Those parsers produce a legacy Comprehension AST with raw string sources. The legacy_convert module then walks the legacy AST and assembles the algebra-layer AST, using source_parser::parse_source for typed-source classification of each clause’s RHS string.

This is the single bridge: every conversion of a polydat-grammar input to the algebra layer funnels through legacy_convert::legacy_to_algebra.

Modules

legacy_convert

Legacy → algebra AST converter.

serde_form

ComprehensionSpec — author-friendly serde-deserializable form, plus its conversion into the algebra-layer AST.

source_parser

Source-string grammar parser — turns the user-facing source expression (e.g. "1..10", "[a, b, c]", "fib(8)") into a typed Source value.

text

parse_text — entry point for text-block consumers.

Structs

ComprehensionSpec

The friendly, serde-deserializable comprehension surface.

Enums

ConvertError

Errors produced when converting a legacy AST to algebra.

ForSpec

The three accepted shapes of the for field.

SourceParseError

Errors that can arise during source-string parsing.

SpecConvertError

Errors produced when converting a ComprehensionSpec to the algebra-layer AST.

TextParseError

Errors produced by parse_text.

Functions

legacy_to_algebra

Convert a legacy LegacyAst to the algebra-layer AlgebraAst.

parse_clause

Parse a single clause.

parse_clause_list

Parse a comma-separated clause list — the textual content of one comprehension sub-space.

parse_comprehension_text

Parse the full Polydat comprehension text grammar: <clause_list> [where <predicate>].

parse_inline

Parse a single inline for-clause string — possibly multi-clause, e.g. "k in 1..10, limit in [1, 2, 3]" — into the algebra-layer AlgebraAst.

parse_order_spec

Parse an order spec string into a TraversalOrder.

parse_source

Parse a source-expression string into a typed Source.

parse_text

Parse a YAML or JSON text block describing a comprehension into the algebra-layer AST.