Struct MapHandle 

pub struct MapHandle<'a, T = StoreEntry> { /* private fields */ }

A draft-time builder for populating a map entry in the Store.

Returned by Pipeline::map and Store::define_map. Methods are chainable so nested structures can be built in a single expression. Nested arrays and maps are added via insert_array and insert_map and return child handles borrowing from this one.

Implementations

impl<'a> MapHandle<'a, StoreEntry>

pub fn insert_array<K: Into<String>>( &mut self, key: K, ) -> Result<ArrayHandle<'_, StoreEntry>, StoreError>

Inserts a new nested array entry under key and returns a child handle borrowing from this one to populate it.

pub fn insert_map<K: Into<String>>( &mut self, key: K, ) -> Result<MapHandle<'_, StoreEntry>, StoreError>

Inserts a new nested map entry under key and returns a child handle borrowing from this one to populate it.

pub fn with_array<K: Into<String>, F: FnOnce(&mut ArrayHandle<'_, StoreEntry>) -> Result<(), StoreError>>( &mut self, key: K, body: F, ) -> Result<(), StoreError>

Inserts a nested array under key and hands it to a closure for population. Useful when the nested structure would otherwise force awkward temporaries.

Examples found in repository

examples/extend_store_nested.rs (lines 34-37)

fn write_grouped_data(store: &mut Store) -> Result<(), Box<dyn std::error::Error>> {
    store.with_map("by_severity", |groups| {
        groups.with_array("high", |arr| {
            arr.push("INC-001")?.push("INC-004")?;
            Ok(())
        })?;

        groups.with_array("medium", |arr| {
            arr.push("INC-002")?;
            Ok(())
        })?;

        groups.with_array("low", |arr| {
            arr.push("INC-003")?.push("INC-005")?.push("INC-006")?;
            Ok(())
        })?;

        Ok(())
    })?;

    Ok(())
}

fn write_nested_config(store: &mut Store) -> Result<(), Box<dyn std::error::Error>> {
    store.with_map("pipeline_config", |cfg| {
        cfg.insert("name", "signin_analysis")?;

        cfg.with_map("source", |src| {
            src.insert("type", "kql")?
                .insert("workspace", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")?;

            src.with_map("options", |opts| {
                opts.insert("timeout_secs", 30i64)?
                    .insert("max_rows", 10_000i64)?;
                Ok(())
            })?;

            Ok(())
        })?;

        cfg.with_array("outputs", |outputs| {
            let mut o = outputs.push_map()?;
            o.insert("format", "json")?
                .insert("path", "/tmp/results.json")?;

            let mut o = outputs.push_map()?;
            o.insert("format", "csv")?
                .insert("path", "/tmp/results.csv")?;

            Ok(())
        })?;

        Ok(())
    })?;

    Ok(())
}

examples/extend_store_collections.rs (lines 55-58)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut store = Store::new();

    // --- Chainable push ---
    // push() accepts V: Into<StoreEntry>. The blanket impl
    // `From<T: Into<Value>> for StoreEntry` means primitives work directly.
    let mut arr = store.define_array("numbers")?.push(1)?.push(2)?.push(3)?;

    let items = store.get("numbers")?.as_array()?;
    println!("numbers: len={}", items.len());
    assert_eq!(items.len(), 3);

    // --- Chainable insert ---
    // insert() accepts K: Into<String> and V: Into<StoreEntry>.
    let mut map = store.define_map("config")?;
    map.insert("host", "localhost")?
        .insert("port", 8080i64)?
        .insert("debug", true)?;

    let host = store.get("config")?.get_key("host")?.get_value()?;
    println!("config.host = {host:?}");

    // --- Closure API on Store ---
    // with_array scopes the handle so you don't need an explicit drop.
    store.with_array("tags", |arr| {
        arr.push("rust")?.push("pipeline")?.push("store")?;
        Ok(())
    })?;

    let tags = store.get("tags")?.as_array()?;
    println!("tags: len={}", tags.len());

    store.with_map("metadata", |map| {
        map.insert("version", "0.1.0")?.insert("stable", false)?;
        Ok(())
    })?;

    let version = store.get("metadata")?.get_key("version")?.get_value()?;
    println!("metadata.version = {version:?}");

    // --- Nested construction via MapHandle closures ---
    // with_array and with_map on MapHandle let you build nested structures
    // without manually managing sub-handles.
    store.with_map("server", |map| {
        map.insert("name", "prod-01")?;

        map.with_array("ports", |arr| {
            arr.push(80)?.push(443)?;
            Ok(())
        })?;

        map.with_map("tls", |tls| {
            tls.insert("enabled", true)?
                .insert("cert_path", "/etc/ssl/cert.pem")?;
            Ok(())
        })?;

        Ok(())
    })?;

    let tls_enabled = store
        .get("server")?
        .get_key("tls")?
        .get_key("enabled")?
        .get_value()?;
    println!("server.tls.enabled = {tls_enabled:?}");

    // --- push_map on ArrayHandle ---
    // Builds an array of maps — the most common pattern for tabular results.
    let mut arr = store.define_array("users")?;
    {
        let mut user = arr.push_map()?;
        user.insert("name", "Alice")?.insert("role", "admin")?;
    }
    {
        let mut user = arr.push_map()?;
        user.insert("name", "Bob")?.insert("role", "viewer")?;
    }

    let bob_role = store
        .get("users")?
        .get_index(1)?
        .get_key("role")?
        .get_value()?;
    println!("users[1].role = {bob_role:?}");
    assert_eq!(bob_role, &Value::Text("viewer".into()));

    println!("store_collections: ok");
    Ok(())
}

pub fn with_map<K: Into<String>, F: FnOnce(&mut MapHandle<'_, StoreEntry>) -> Result<(), StoreError>>( &mut self, key: K, body: F, ) -> Result<(), StoreError>

Inserts a nested map under key and hands it to a closure for population.

Examples found in repository

examples/extend_store_nested.rs (lines 59-70)

fn write_nested_config(store: &mut Store) -> Result<(), Box<dyn std::error::Error>> {
    store.with_map("pipeline_config", |cfg| {
        cfg.insert("name", "signin_analysis")?;

        cfg.with_map("source", |src| {
            src.insert("type", "kql")?
                .insert("workspace", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")?;

            src.with_map("options", |opts| {
                opts.insert("timeout_secs", 30i64)?
                    .insert("max_rows", 10_000i64)?;
                Ok(())
            })?;

            Ok(())
        })?;

        cfg.with_array("outputs", |outputs| {
            let mut o = outputs.push_map()?;
            o.insert("format", "json")?
                .insert("path", "/tmp/results.json")?;

            let mut o = outputs.push_map()?;
            o.insert("format", "csv")?
                .insert("path", "/tmp/results.csv")?;

            Ok(())
        })?;

        Ok(())
    })?;

    Ok(())
}

examples/extend_store_collections.rs (lines 60-64)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut store = Store::new();

    // --- Chainable push ---
    // push() accepts V: Into<StoreEntry>. The blanket impl
    // `From<T: Into<Value>> for StoreEntry` means primitives work directly.
    let mut arr = store.define_array("numbers")?.push(1)?.push(2)?.push(3)?;

    let items = store.get("numbers")?.as_array()?;
    println!("numbers: len={}", items.len());
    assert_eq!(items.len(), 3);

    // --- Chainable insert ---
    // insert() accepts K: Into<String> and V: Into<StoreEntry>.
    let mut map = store.define_map("config")?;
    map.insert("host", "localhost")?
        .insert("port", 8080i64)?
        .insert("debug", true)?;

    let host = store.get("config")?.get_key("host")?.get_value()?;
    println!("config.host = {host:?}");

    // --- Closure API on Store ---
    // with_array scopes the handle so you don't need an explicit drop.
    store.with_array("tags", |arr| {
        arr.push("rust")?.push("pipeline")?.push("store")?;
        Ok(())
    })?;

    let tags = store.get("tags")?.as_array()?;
    println!("tags: len={}", tags.len());

    store.with_map("metadata", |map| {
        map.insert("version", "0.1.0")?.insert("stable", false)?;
        Ok(())
    })?;

    let version = store.get("metadata")?.get_key("version")?.get_value()?;
    println!("metadata.version = {version:?}");

    // --- Nested construction via MapHandle closures ---
    // with_array and with_map on MapHandle let you build nested structures
    // without manually managing sub-handles.
    store.with_map("server", |map| {
        map.insert("name", "prod-01")?;

        map.with_array("ports", |arr| {
            arr.push(80)?.push(443)?;
            Ok(())
        })?;

        map.with_map("tls", |tls| {
            tls.insert("enabled", true)?
                .insert("cert_path", "/etc/ssl/cert.pem")?;
            Ok(())
        })?;

        Ok(())
    })?;

    let tls_enabled = store
        .get("server")?
        .get_key("tls")?
        .get_key("enabled")?
        .get_value()?;
    println!("server.tls.enabled = {tls_enabled:?}");

    // --- push_map on ArrayHandle ---
    // Builds an array of maps — the most common pattern for tabular results.
    let mut arr = store.define_array("users")?;
    {
        let mut user = arr.push_map()?;
        user.insert("name", "Alice")?.insert("role", "admin")?;
    }
    {
        let mut user = arr.push_map()?;
        user.insert("name", "Bob")?.insert("role", "viewer")?;
    }

    let bob_role = store
        .get("users")?
        .get_index(1)?
        .get_key("role")?
        .get_value()?;
    println!("users[1].role = {bob_role:?}");
    assert_eq!(bob_role, &Value::Text("viewer".into()));

    println!("store_collections: ok");
    Ok(())
}

impl<'a, T> MapHandle<'a, Vec<T>>

pub fn insert_array<K: Into<String>>( &mut self, key: K, ) -> Result<ArrayHandle<'_, T>, StoreError>

Inserts a new inner Vec<T> under key and returns a child array handle for populating it.

impl<'a, T> MapHandle<'a, HashMap<String, T>>

pub fn insert_map<K: Into<String>>( &mut self, key: K, ) -> Result<MapHandle<'_, T>, StoreError>

Inserts a new inner HashMap<String, T> under key and returns a child map handle for populating it.

impl<'a, T> MapHandle<'a, T>

pub fn new<N: Into<String>>(name: N, data: &'a mut HashMap<String, T>) -> Self

Wraps a mutable map in a handle under the given display name. Intended for extension code; user code obtains handles through Pipeline::map or Store::define_map.

pub fn insert<V: Into<T>, K: Into<String>>( &mut self, key: K, value: V, ) -> Result<&mut Self, StoreError>

Inserts a key/value pair into the map. Returns a mutable reference for chaining. An existing entry under the same key is overwritten.

Examples found in repository

examples/extend_store_nested.rs (line 14)

fn write_query_results(store: &mut Store) -> Result<(), Box<dyn std::error::Error>> {
    store.with_array("rows", |rows| {
        // Row 1 — all fields inserted via chaining, no .into() needed.
        let mut row = rows.push_map()?;
        row.insert("user", "alice@contoso.com")?
            .insert("ip", "10.0.0.1")?
            .insert("status", "Success")?
            .insert("attempts", 1i64)?;

        // Row 2
        let mut row = rows.push_map()?;
        row.insert("user", "bob@contoso.com")?
            .insert("ip", "192.168.1.50")?
            .insert("status", "Failure")?
            .insert("attempts", 3i64)?;

        Ok(())
    })?;

    Ok(())
}

fn write_grouped_data(store: &mut Store) -> Result<(), Box<dyn std::error::Error>> {
    store.with_map("by_severity", |groups| {
        groups.with_array("high", |arr| {
            arr.push("INC-001")?.push("INC-004")?;
            Ok(())
        })?;

        groups.with_array("medium", |arr| {
            arr.push("INC-002")?;
            Ok(())
        })?;

        groups.with_array("low", |arr| {
            arr.push("INC-003")?.push("INC-005")?.push("INC-006")?;
            Ok(())
        })?;

        Ok(())
    })?;

    Ok(())
}

fn write_nested_config(store: &mut Store) -> Result<(), Box<dyn std::error::Error>> {
    store.with_map("pipeline_config", |cfg| {
        cfg.insert("name", "signin_analysis")?;

        cfg.with_map("source", |src| {
            src.insert("type", "kql")?
                .insert("workspace", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")?;

            src.with_map("options", |opts| {
                opts.insert("timeout_secs", 30i64)?
                    .insert("max_rows", 10_000i64)?;
                Ok(())
            })?;

            Ok(())
        })?;

        cfg.with_array("outputs", |outputs| {
            let mut o = outputs.push_map()?;
            o.insert("format", "json")?
                .insert("path", "/tmp/results.json")?;

            let mut o = outputs.push_map()?;
            o.insert("format", "csv")?
                .insert("path", "/tmp/results.csv")?;

            Ok(())
        })?;

        Ok(())
    })?;

    Ok(())
}

examples/extend_store_collections.rs (line 24)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut store = Store::new();

    // --- Chainable push ---
    // push() accepts V: Into<StoreEntry>. The blanket impl
    // `From<T: Into<Value>> for StoreEntry` means primitives work directly.
    let mut arr = store.define_array("numbers")?.push(1)?.push(2)?.push(3)?;

    let items = store.get("numbers")?.as_array()?;
    println!("numbers: len={}", items.len());
    assert_eq!(items.len(), 3);

    // --- Chainable insert ---
    // insert() accepts K: Into<String> and V: Into<StoreEntry>.
    let mut map = store.define_map("config")?;
    map.insert("host", "localhost")?
        .insert("port", 8080i64)?
        .insert("debug", true)?;

    let host = store.get("config")?.get_key("host")?.get_value()?;
    println!("config.host = {host:?}");

    // --- Closure API on Store ---
    // with_array scopes the handle so you don't need an explicit drop.
    store.with_array("tags", |arr| {
        arr.push("rust")?.push("pipeline")?.push("store")?;
        Ok(())
    })?;

    let tags = store.get("tags")?.as_array()?;
    println!("tags: len={}", tags.len());

    store.with_map("metadata", |map| {
        map.insert("version", "0.1.0")?.insert("stable", false)?;
        Ok(())
    })?;

    let version = store.get("metadata")?.get_key("version")?.get_value()?;
    println!("metadata.version = {version:?}");

    // --- Nested construction via MapHandle closures ---
    // with_array and with_map on MapHandle let you build nested structures
    // without manually managing sub-handles.
    store.with_map("server", |map| {
        map.insert("name", "prod-01")?;

        map.with_array("ports", |arr| {
            arr.push(80)?.push(443)?;
            Ok(())
        })?;

        map.with_map("tls", |tls| {
            tls.insert("enabled", true)?
                .insert("cert_path", "/etc/ssl/cert.pem")?;
            Ok(())
        })?;

        Ok(())
    })?;

    let tls_enabled = store
        .get("server")?
        .get_key("tls")?
        .get_key("enabled")?
        .get_value()?;
    println!("server.tls.enabled = {tls_enabled:?}");

    // --- push_map on ArrayHandle ---
    // Builds an array of maps — the most common pattern for tabular results.
    let mut arr = store.define_array("users")?;
    {
        let mut user = arr.push_map()?;
        user.insert("name", "Alice")?.insert("role", "admin")?;
    }
    {
        let mut user = arr.push_map()?;
        user.insert("name", "Bob")?.insert("role", "viewer")?;
    }

    let bob_role = store
        .get("users")?
        .get_index(1)?
        .get_key("role")?
        .get_value()?;
    println!("users[1].role = {bob_role:?}");
    assert_eq!(bob_role, &Value::Text("viewer".into()));

    println!("store_collections: ok");
    Ok(())
}

examples/iter_map.rs (line 17)

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(())
}