Fix macro invocation and add more examples (#64)

* Document some public functions and modify macros interface a bit

* fix

* Add few more examples

* rebase

* Fix macro

* fix env

Author: nikola-jokic

README.md

@@ -35,6 +35,17 @@ done
 
 or run directly with `cargo run --example <name>` for interactive experimentation.
 
+### Example overview
+
+| Example | Highlights |
+| --- | --- |
+| `simple` | Basic expression evaluation, child runtimes, and scalar values. |
+| `create_function` | Registering function declarations plus native Rust implementations. |
+| `concurrency` | Sharing a runtime builder across threads for parallel evaluation. |
+| `user_role_derive` | Using the `derive` feature to expose Rust structs and methods to CEL. |
+| `comprehensions` | Practical use of CEL macros like `exists`, `filter`, `map`, and `all`. |
+| `env_snapshot` | Building, serializing, and rehydrating a reusable environment snapshot. |
+
 ## CLI
 
 The `cellang-cli` crate exposes a developer-friendly command line interface for inspecting CEL programs.

crates/cellang/examples/comprehensions.rs

@@ -0,0 +1,44 @@
+use cellang::Runtime;
+use cellang::value::{IntoValue, ListValue, MapValue, Value};
+use miette::Result;
+
+fn main() -> Result<()> {
+    let mut builder = Runtime::builder();
+    builder.set_variable("assets", sample_assets())?;
+    let runtime = builder.build();
+
+    let has_high_risk =
+        runtime.eval("assets.exists(asset, asset.risk >= 75)")?;
+    assert_eq!(has_high_risk, Value::Bool(true));
+
+    let prod_names = runtime.eval(
+        "assets.filter(asset, 'prod' in asset.tags).map(asset, asset.name)",
+    )?;
+    assert_eq!(prod_names, vec!["scanner", "api"].into_value());
+
+    let all_positive =
+        runtime.eval("assets.map(asset, asset.risk).all(risk, risk >= 0)")?;
+    assert_eq!(all_positive, Value::Bool(true));
+
+    Ok(())
+}
+
+fn sample_assets() -> Value {
+    let entries = vec![
+        asset("scanner", 80, &["prod", "pci"]),
+        asset("api", 65, &["prod"]),
+        asset("etl", 40, &["batch"]),
+    ];
+    Value::List(ListValue::from(entries))
+}
+
+fn asset(name: &str, risk: i64, tags: &[&str]) -> Value {
+    let mut record = MapValue::new();
+    record.insert("name", name);
+    record.insert("risk", risk);
+    record.insert(
+        "tags",
+        ListValue::from(tags.iter().copied().collect::<Vec<_>>()),
+    );
+    Value::Map(record)
+}

crates/cellang/examples/env_snapshot.rs

@@ -0,0 +1,120 @@
+use cellang::types::{
+    FieldDecl, FunctionDecl, IdentDecl, NamedType, OverloadDecl, StructType,
+    Type,
+};
+use cellang::value::{ListValue, StructValue, Value};
+use cellang::{Env, Runtime};
+use miette::{IntoDiagnostic, Result};
+
+fn main() -> Result<()> {
+    let env_cache =
+        serde_json::to_vec(&build_policy_env()).into_diagnostic()?;
+
+    let scenarios =
+        [("analytics", "write", true), ("security", "delete", false)];
+
+    for (owner, desired_access, expected) in scenarios {
+        let env: Env = serde_json::from_slice(&env_cache).into_diagnostic()?;
+        let mut builder = Runtime::builder();
+        builder.import_env_owned(env)?;
+        builder.register_function("same_tenant", same_tenant)?;
+        builder.set_variable("request", request_value())?;
+        builder.set_variable("resource_owner", owner)?;
+        builder.set_variable("desired_access", desired_access)?;
+        let runtime = builder.build();
+
+        let decision = runtime.eval(
+            "same_tenant(request.subject, resource_owner) && \
+             request.resource.accesses.exists(access, access == desired_access)",
+        )?;
+        assert_eq!(decision, Value::Bool(expected));
+    }
+
+    Ok(())
+}
+
+fn build_policy_env() -> Env {
+    let mut builder = Env::builder();
+
+    let mut resource = StructType::new("example.Resource")
+        .with_doc("Resource being evaluated in a policy");
+    resource
+        .add_field("kind", FieldDecl::new(Type::String))
+        .unwrap();
+    resource
+        .add_field(
+            "accesses",
+            FieldDecl::new(Type::list(Type::String))
+                .with_doc("Allowed operations on the resource"),
+        )
+        .unwrap();
+
+    let mut request = StructType::new("example.AccessRequest")
+        .with_doc("Wrapper around the incoming access request");
+    request
+        .add_field("subject", FieldDecl::new(Type::String))
+        .unwrap();
+    request
+        .add_field(
+            "resource",
+            FieldDecl::new(Type::struct_type(resource.name.clone()))
+                .with_doc("Resource being accessed"),
+        )
+        .unwrap();
+
+    builder.add_type(NamedType::Struct(resource)).unwrap();
+    builder
+        .add_type(NamedType::Struct(request.clone()))
+        .unwrap();
+
+    builder
+        .add_ident(
+            IdentDecl::new("request", Type::struct_type(request.name.clone()))
+                .with_doc("Access request provided at evaluation time"),
+        )
+        .unwrap();
+    builder
+        .add_ident(
+            IdentDecl::new("resource_owner", Type::String)
+                .with_doc("Tenant that owns the resource"),
+        )
+        .unwrap();
+    builder
+        .add_ident(
+            IdentDecl::new("desired_access", Type::String)
+                .with_doc("Operation requested by the caller"),
+        )
+        .unwrap();
+
+    builder.add_function(same_tenant_decl()).unwrap();
+
+    builder.build()
+}
+
+fn same_tenant(requester: String, owner: String) -> bool {
+    requester == owner
+}
+
+fn same_tenant_decl() -> FunctionDecl {
+    let mut decl = FunctionDecl::new("same_tenant")
+        .with_doc("Compares two tenant identifiers");
+    decl.add_overload(OverloadDecl::new(
+        "same_tenant_string_string",
+        vec![Type::String, Type::String],
+        Type::Bool,
+    ))
+    .unwrap();
+    decl
+}
+
+fn request_value() -> Value {
+    let mut resource = StructValue::new("example.Resource");
+    resource.set_field("kind", "dashboard");
+    resource.set_field("accesses", ListValue::from(vec!["read", "write"]));
+
+    let mut request = StructValue::new("example.AccessRequest");
+    request.set_field("subject", "analytics");
+    request.set_field("resource", resource);
+
+    Value::Struct(request)
+}

crates/cellang/examples/user_role.rs …tes/cellang/examples/user_role_derive.rscrates/cellang/examples/user_role.rs renamed to crates/cellang/examples/user_role_derive.rs crates/cellang/examples/user_role.rs renamed to crates/cellang/examples/user_role_derive.rs

@@ -995,7 +995,7 @@ fn ensure_arity(
 mod tests {
     use super::*;
     use crate::runtime::Runtime;
-    use crate::value::{StructValue, Value};
+    use crate::value::{IntoValue, ListValue, MapValue, StructValue, Value};
 
     #[test]
     fn evaluates_arithmetic_with_variables() {
@@ -1037,6 +1037,32 @@ mod tests {
         );
     }
 
+    #[test]
+    fn comprehension_macros_allow_function_calls() {
+        let runtime = runtime_with_assets();
+
+        let has_high_risk =
+            eval(&runtime, "exists(assets, asset, asset.risk >= 75)")
+                .expect("exists() macro should evaluate");
+        assert_eq!(has_high_risk, Value::Bool(true));
+
+        let prod_names = eval(&runtime, "map(assets, asset, asset.name)")
+            .expect("map() macro should evaluate");
+        assert_eq!(prod_names, vec!["scanner", "api", "etl"].into_value());
+
+        let filtered =
+            eval(&runtime, "filter(assets, asset, asset.risk >= 75)")
+                .expect("filter() macro should evaluate");
+        assert_eq!(
+            filtered,
+            Value::List(ListValue::from(vec![asset(
+                "scanner",
+                80,
+                &["prod", "pci"],
+            )])),
+        );
+    }
+
     fn runtime_with_user() -> Runtime {
         let mut builder = Runtime::builder();
         let mut user = StructValue::new("example.User");
@@ -1047,4 +1073,31 @@ mod tests {
             .expect("user variable to set");
         builder.build()
     }
+
+    fn runtime_with_assets() -> Runtime {
+        let mut builder = Runtime::builder();
+        builder
+            .set_variable("assets", sample_assets())
+            .expect("assets variable to set");
+        builder.build()
+    }
+
+    fn sample_assets() -> Value {
+        Value::List(ListValue::from(vec![
+            asset("scanner", 80, &["prod", "pci"]),
+            asset("api", 65, &["prod"]),
+            asset("etl", 40, &["batch"]),
+        ]))
+    }
+
+    fn asset(name: &str, risk: i64, tags: &[&str]) -> Value {
+        let mut record = MapValue::new();
+        record.insert("name", name);
+        record.insert("risk", risk);
+        record.insert(
+            "tags",
+            ListValue::from(tags.iter().copied().collect::<Vec<_>>()),
+        );
+        Value::Map(record)
+    }
 }

crates/cellang/src/interpreter.rs

@@ -113,49 +113,39 @@ pub fn detect_macro_call<'src>(
                 ComprehensionKind::All,
                 name,
                 args,
-                is_method,
                 ExpectedArity::Fixed(3),
-                true,
             )?)
         }
         "exists" if registry.is_enabled(MacroKind::Exists) => {
             Some(parse_comprehension(
                 ComprehensionKind::Exists,
                 name,
                 args,
-                is_method,
                 ExpectedArity::Fixed(3),
-                true,
             )?)
         }
         "exists_one" if registry.is_enabled(MacroKind::ExistsOne) => {
             Some(parse_comprehension(
                 ComprehensionKind::ExistsOne,
                 name,
                 args,
-                is_method,
                 ExpectedArity::Fixed(3),
-                true,
             )?)
         }
         "map" if registry.is_enabled(MacroKind::Map) => {
             Some(parse_comprehension(
                 ComprehensionKind::Map,
                 name,
                 args,
-                is_method,
                 ExpectedArity::Either(3, 4),
-                true,
             )?)
         }
         "filter" if registry.is_enabled(MacroKind::Filter) => {
             Some(parse_comprehension(
                 ComprehensionKind::Filter,
                 name,
                 args,
-                is_method,
                 ExpectedArity::Fixed(3),
-                true,
             )?)
         }
         _ => None,
@@ -205,16 +195,8 @@ fn parse_comprehension<'src>(
     kind: ComprehensionKind,
     macro_name: &str,
     args: &'src [TokenTree<'src>],
-    is_method: bool,
     arity: ExpectedArity,
-    require_method: bool,
 ) -> Result<MacroInvocation<'src>, RuntimeError> {
-    if require_method && !is_method {
-        return Err(RuntimeError::new(format!(
-            "Macro '{macro_name}' must be invoked using receiver call syntax"
-        )));
-    }
-
     let len_ok = match arity {
         ExpectedArity::Fixed(size) => args.len() == size,
         ExpectedArity::Either(a, b) => args.len() == a || args.len() == b,