Struct IterSource 

pub struct IterSource { /* private fields */ }

A draft-time reference to the store entry an iteration node should walk.

Passed to Pipeline::iter_array or Pipeline::iter_map to name the array or map the body iterates over. At runtime the reference is resolved against the runtime store; if the resolved entry is missing or has the wrong shape, the iteration fails with OperationError::IterSourceNotFound or OperationError::IterSourceTypeMismatch.

Implementations

impl IterSource

pub fn array(reference: impl Into<String>) -> Self

Builds an iter source pointing at an array entry. Use with Pipeline::iter_array.

Examples found in repository

examples/iter_array.rs (line 21)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── Basic iter_array: iterate over items and capture each ──
    println!("=== Basic iter_array ===");
    {
        let mut pipe = Pipeline::default();
        pipe.array("numbers")?.push(10)?.push(20)?.push(30)?;

        pipe.iter_array(
            "process",
            IterSource::array("numbers"),
            |_index, item, body| {
                body.step::<SetVar>(
                    "capture",
                    params!(
                        "name" => "doubled",
                        "value" => Param::reference(item),
                    ),
                )?;
                Ok(())
            },
        )?;

        pipe.hook(Logger::new().writer(std::io::stdout()));
        pipe.hook(Timeout::new(Duration::from_secs(5)));

        let complete = pipe.compile()?.run().wait()?;
        complete.debug();
    }

    // ── iter_array with parent variable references ──
    println!("\n=== iter_array referencing parent vars ===");
    {
        let mut pipe = Pipeline::default();
        pipe.var("prefix", "item_")?;
        pipe.array("items")?
            .push("alpha")?
            .push("beta")?
            .push("gamma")?;

        pipe.iter_array("loop", IterSource::array("items"), |_index, item, body| {
            body.step::<SetVar>(
                "combine",
                params!(
                    "name" => "label",
                    "value" => Param::template(vec![
                        Param::reference("prefix"),
                        Param::reference(item),
                    ]),
                ),
            )?;
            Ok(())
        })?;

        let complete = pipe.compile()?.run().wait()?;
        complete.debug();
    }

    // ── iter_array with multiple body steps ──
    println!("\n=== iter_array with multi-step body ===");
    {
        let mut pipe = Pipeline::default();
        pipe.var("suffix", "_processed")?;
        pipe.array("words")?.push("hello")?.push("world")?;

        pipe.iter_array("each", IterSource::array("words"), |_index, item, body| {
            body.step::<SetVar>(
                "tag",
                params!(
                    "name" => "tagged",
                    "value" => Param::template(vec![
                        Param::reference(item),
                        Param::reference("suffix"),
                    ]),
                ),
            )?;
            body.step::<SetVar>(
                "wrap",
                params!(
                    "name" => "wrapped",
                    "value" => Param::template(vec![
                        Param::literal("["),
                        Param::reference("tagged"),
                        Param::literal("]"),
                    ]),
                ),
            )?;
            Ok(())
        })?;

        let complete = pipe.compile()?.run().wait()?;
        complete.debug();
    }

    // ── Error: iter_array with unresolved source ──
    println!("\n=== iter_array unresolved source ===");
    {
        let mut pipe = Pipeline::default();

        pipe.iter_array("loop", IterSource::array("nonexistent"), |_, _, _| Ok(()))?;

        match pipe.compile() {
            Err(e) => println!("  Caught: {}", e),
            Ok(_) => println!("  ERROR: should have failed!"),
        }
    }

    // ── Error: iter_array body references unknown variable ──
    println!("\n=== iter_array unresolved body reference ===");
    {
        let mut pipe = Pipeline::default();
        pipe.array("items")?.push(1)?;

        pipe.iter_array("loop", IterSource::array("items"), |_, _, body| {
            body.step::<SetVar>(
                "bad",
                params!(
                    "name" => "out",
                    "value" => Param::reference("ghost"),
                ),
            )?;
            Ok(())
        })?;

        match pipe.compile() {
            Err(e) => println!("  Caught: {}", e),
            Ok(_) => println!("  ERROR: should have failed!"),
        }
    }

    Ok(())
}

pub fn map(reference: impl Into<String>) -> Self

Builds an iter source pointing at a map entry. Use with Pipeline::iter_map.

Examples found in repository

examples/iter_map.rs (line 23)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── Basic iter_map: iterate over key-value pairs ──
    println!("=== Basic iter_map ===");
    {
        let mut pipe = Pipeline::default();
        pipe.map("config")?
            .insert("host", "localhost")?
            .insert("port", "8080")?
            .insert("protocol", "https")?;

        pipe.iter_map(
            "read_config",
            IterSource::map("config"),
            |key, value, body| {
                body.step::<SetVar>(
                    "capture_key",
                    params!(
                        "name" => "current_key",
                        "value" => Param::reference(key),
                    ),
                )?;
                body.step::<SetVar>(
                    "capture_value",
                    params!(
                        "name" => "current_value",
                        "value" => Param::reference(value),
                    ),
                )?;
                Ok(())
            },
        )?;

        pipe.hook(Logger::new().writer(std::io::stdout()));
        pipe.hook(Timeout::new(Duration::from_secs(5)));

        let complete = pipe.compile()?.run().wait()?;
        complete.debug();
    }

    // ── iter_map with parent variable references ──
    println!("\n=== iter_map referencing parent vars ===");
    {
        let mut pipe = Pipeline::default();
        pipe.var("env", "production")?;
        pipe.map("settings")?
            .insert("db_host", "db.example.com")?
            .insert("cache_host", "cache.example.com")?;

        pipe.iter_map(
            "apply_env",
            IterSource::map("settings"),
            |key, value, body| {
                body.step::<SetVar>(
                    "label",
                    params!(
                        "name" => "entry",
                        "value" => Param::template(vec![
                            Param::reference("env"),
                            Param::literal("."),
                            Param::reference(key),
                            Param::literal("="),
                            Param::reference(value),
                        ]),
                    ),
                )?;
                Ok(())
            },
        )?;

        let complete = pipe.compile()?.run().wait()?;
        complete.debug();
    }

    // ── iter_map followed by regular steps ──
    println!("\n=== iter_map then regular steps ===");
    {
        let mut pipe = Pipeline::default();
        pipe.var("status", "ready")?;
        pipe.map("headers")?
            .insert("content-type", "application/json")?
            .insert("accept", "text/html")?;

        pipe.iter_map(
            "scan_headers",
            IterSource::map("headers"),
            |_key, value, body| {
                body.step::<SetVar>(
                    "save",
                    params!(
                        "name" => "last_header",
                        "value" => Param::reference(value),
                    ),
                )?;
                Ok(())
            },
        )?;

        // Regular step after the iteration
        pipe.step::<SetVar>(
            "finalize",
            params!(
                "name" => "done",
                "value" => Param::reference("status"),
            ),
        )?;

        pipe.returns(
            "result",
            params!(
                "status" => Param::reference("done"),
            ),
        )?;

        let complete = pipe.compile()?.run().wait()?;
        complete.debug();
    }

    // ── Error: iter_map with unresolved source ──
    println!("\n=== iter_map unresolved source ===");
    {
        let mut pipe = Pipeline::default();

        pipe.iter_map("loop", IterSource::map("missing"), |_, _, _| Ok(()))?;

        match pipe.compile() {
            Err(e) => println!("  Caught: {}", e),
            Ok(_) => println!("  ERROR: should have failed!"),
        }
    }

    // ── Error: iter_map body references unknown variable ──
    println!("\n=== iter_map unresolved body reference ===");
    {
        let mut pipe = Pipeline::default();
        pipe.map("data")?.insert("k", "v")?;

        pipe.iter_map("loop", IterSource::map("data"), |_, _, body| {
            body.step::<SetVar>(
                "bad",
                params!(
                    "name" => "out",
                    "value" => Param::reference("phantom"),
                ),
            )?;
            Ok(())
        })?;

        match pipe.compile() {
            Err(e) => println!("  Caught: {}", e),
            Ok(_) => println!("  ERROR: should have failed!"),
        }
    }

    Ok(())
}

pub fn reference(&self) -> &str

Read-only access to the underlying store reference. Used by external callers (e.g. serialisers) that need to walk a validated execution graph.