cel-rs-rb 0.2.0-x86_64-linux → 0.3.0-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84dbc0c932c059a392416294cb936f7986b8d4718fd5bd91e30afd2c121d3a68
-  data.tar.gz: 52763c42c348f277cbe550831a4e56ae2fb0dbdb8e7df26a26eec7004461a5ea
+  metadata.gz: 6141fff7b7af7e907394dd3c8166180b2709c853a4cdb8074fc5d3236e243147
+  data.tar.gz: 007f3dd5efd09f4f6537f5c4c3f7619fa055fef65386b7d7040793e6bdc3f2eb
 SHA512:
-  metadata.gz: b264ec6eed57acc4555b1cfcd606e4d08faf51aa24729d997352c7289442a7b7a3d39d175d88475a0fa9b2086a29daabc0d179fc4ba33257e3c68c68b9f16a45
-  data.tar.gz: 556e5bc7f77a09cd97a919f340f327454858ee529c1a986c9c862e825fcc065de67df073b3815f349d34c7f9fb48ca090af30c499a6a997a4920f10f76a37abd
+  metadata.gz: a4e4808206e95e90e5ffb0cce51d7a677affde137043c2d4b051d9c3ef55c8e748c41381eba6eed1d4d45eaabb6b30ebfad3e516ece40f24eab692df9bf3a2c9
+  data.tar.gz: 0beaa7107f2c89aa24b496420143cbeebee3feeaa921876042acff3e5aa01dc1eed7e5bb9e2ce8d46b045a60a0da585ff9f48c1e26e668a752e31baee1309e6d

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://img.shields.io/gem/v/cel-rs-rb.svg)](https://rubygems.org/gems/cel-rs-rb)
 
-Ruby bindings for the Rust [`cel`](https://crates.io/crates/cel) crate, implemented with [Magnus](https://github.com/matsadler/magnus).
+Ruby bindings for the Rust [`cel`](https://crates.io/crates/cel) 0.15 crate, implemented with [Magnus](https://github.com/matsadler/magnus).
 
 ## Goals
 
@@ -32,10 +32,69 @@ program.execute(context)
 # => 60
 ```
 
+### Optional values
+
+Use optional access to handle missing fields, and `orValue` to supply a default:
+
+```ruby
+context = CEL::Context.build(user: {})
+CEL.compile("user.?name.orValue('unknown')").execute(context)
+# => "unknown"
+
+context = CEL::Context.build(user: {"name" => "Ada"})
+CEL.compile("user.?name.optMap(n, n.size()).orValue(0)").execute(context)
+# => 3
+```
+
+Unwrap optional values inside CEL with `orValue` or `value()` before returning
+them to Ruby. Returning an optional directly raises `CEL::TypeError`; it is not
+automatically converted to its contained value or `nil`.
+
+### `max` and `min`
+
+Default contexts include `max` and `min`. They take a list or positional arguments and
+return `nil` when given no values:
+
+```ruby
+CEL.compile("max(2, 9, -3)").execute   # => 9
+CEL.compile("min([2, 9, -3])").execute # => -3
+CEL.compile("max([])").execute         # => nil
+```
+
+### Extension libraries
+
+Opt into upstream CEL extension libraries when compiling a program:
+
+```ruby
+program = CEL.compile(
+  "[label.lowerAscii(), scores.sort(), math.greatest(scores), base64.encode(b'hi')]",
+  extensions: [:strings, :lists, :math, :encoders]
+)
+program.execute(CEL::Context.build(label: "TacoCat", scores: [2, 9, -3]))
+# => ["tacocat", [-3, 2, 9], 9, "aGk="]
+```
+
+| Library | Examples |
+| --- | --- |
+| [`strings`](https://docs.rs/cel/0.15.0/cel/extensions/fn.strings.html) | `'TacoCat'.lowerAscii()`, `'a,b'.split(',')` |
+| [`lists`](https://docs.rs/cel/0.15.0/cel/extensions/fn.lists.html) | `lists.range(3)`, `[3, 1, 2].sort()`, `items.sortBy(x, x.score)` |
+| [`math`](https://docs.rs/cel/0.15.0/cel/extensions/fn.math.html) | `math.greatest(1, 5, 3)`, `math.least([1, 5, 3])` |
+| [`encoders`](https://docs.rs/cel/0.15.0/cel/extensions/fn.encoders.html) | `base64.encode(b'hi')`, `base64.decode('aGk=')` |
+
+`CEL::Program.compile` accepts the same `extensions:` option. Names can be
+symbols or strings; unknown or repeated names raise `ArgumentError`.
+
+Extensions are disabled by default and registered per program, for both macro
+expansion and execution. They work with bare `execute` or a default context,
+including its variables and Ruby callbacks. They do not change other programs
+or add functions to explicitly empty contexts. Ruby callbacks that conflict
+with enabled extension functions raise `CEL::ExecutionError` during execution,
+just like conflicts with standard CEL builtins.
+
 ### API mapping
 
-- `CEL.compile(source)` -> `CEL::Program`
-- `CEL::Program.compile(source)` -> `CEL::Program`
+- `CEL.compile(source, extensions: [])` -> `CEL::Program`
+- `CEL::Program.compile(source, extensions: [])` -> `CEL::Program`
 - `CEL::Program#execute(context = nil)` -> Ruby value
 - `CEL::Program#references` -> `{ "variables" => [...], "functions" => [...] }`
 - `CEL::Context.new(empty = false)` -> context with builtins (`false`) or empty (`true`)
@@ -114,10 +173,12 @@ CI also runs the test suite on Ruby 3.3, Ruby 3.4, and Ruby 4.0 through Buildkit
 
 ## Releasing
 
-Releases publish **precompiled native gems** for six platforms
-(`x86_64-linux`, `aarch64-linux`, `x86_64-linux-musl`, `aarch64-linux-musl`,
-`arm64-darwin`, `x86_64-darwin`) to
-[rubygems.org](https://rubygems.org/gems/cel-rs-rb).
+Releases publish a generic `ruby` platform gem and **precompiled native gems**
+for six platforms (`x86_64-linux`, `aarch64-linux`, `x86_64-linux-musl`,
+`aarch64-linux-musl`, `arm64-darwin`, `x86_64-darwin`) to
+[rubygems.org](https://rubygems.org/gems/cel-rs-rb). The generic gem keeps
+RubyGems' latest-version metadata aligned; supported platforms should still
+resolve to their matching precompiled native gem.
 
 ### Cutting a release
 
@@ -148,5 +209,12 @@ The `release:verify-tag` step fails the build if the tag and
 
 ## Compatibility notes
 
+- Compilation uses the standard CEL environment, including optional access syntax (`user.?name`) and the `optMap` / `optFlatMap` macros.
+- The upstream strings, lists, math, and encoders extension libraries are opt-in through the `extensions:` compile option.
+- cel 0.15 no longer includes `max` and `min` by default, so default contexts register them for compatibility with cel 0.13. See [`max` and `min`](#max-and-min).
+- When upgrading from cel 0.13, replace list/map `.contains(value)` expressions with `value in collection`; `.contains()` now only accepts strings. Map literals with duplicate keys raise `CEL::ExecutionError`, and string `size()` counts Unicode code points rather than bytes. See the [cel 0.15 release notes](https://github.com/cel-rust/cel-rust/releases/tag/v0.15.0) for further CEL semantic changes.
+- `string(bytes)` now rejects invalid UTF-8. Numeric conversions reject out-of-range results, and parsed timestamps and durations must fit CEL's allowed ranges.
+- `all()` and `exists()` can now absorb an earlier evaluation error when a later element determines the result. For example, `[2, 1].exists(e, 6 / (2 - e) == 6)` returns `true` despite the first element's division by zero.
+- Ruby callbacks cannot shadow standard CEL builtins (such as `size`) in a default context; the compatibility functions `max` and `min` are exceptions. Conflicts raise `CEL::ExecutionError` when `Program#execute(context)` builds the execution snapshot, even if the expression does not call the conflicting function. Use `CEL::Context.new(true)` or `CEL::Context.build(empty: true)` to define functions without builtins. Registering the same custom callback name again replaces the previous callback.
 - Some CEL value variants (e.g. opaque custom Rust types) cannot be fully marshaled to Ruby and raise `CEL::TypeError`.
 - This project targets broad CEL compatibility, but parity for every Rust-only extension point is still evolving.

data/lib/cel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CEL
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/cel.rb

@@ -10,6 +10,10 @@ rescue LoadError
 end
 
 module CEL
+  def self.compile(source, extensions: [])
+    Program.compile(source, extensions: extensions)
+  end
+
   class Context
     class << self
       alias_method :__native_new, :new
@@ -34,6 +38,14 @@ module CEL
   end
 
   class Program
+    class << self
+      alias_method :__native_compile, :compile
+
+      def compile(source, extensions: [])
+        __native_compile(source, extensions.map(&:to_s))
+      end
+    end
+
     alias_method :__native_execute, :execute
 
     def execute(context = nil)

data/spec/cel_spec.rb

@@ -13,6 +13,49 @@ RSpec.describe CEL do
     it "raises parse errors for invalid programs" do
       expect { CEL.compile("1 +") }.to raise_error(CEL::ParseError)
     end
+
+    it "enables each upstream extension for compilation and execution" do
+      tests = {
+        strings: ["'TacoCat'.lowerAscii()", "tacocat"],
+        lists: ["[{'n': 8}, {'n': 2}, {'n': 5}].sortBy(x, x.n).map(x, x.n)", [2, 5, 8]],
+        math: ["math.greatest(2, 9, -3)", 9],
+        encoders: ["base64.encode(b'hi')", "aGk="]
+      }
+
+      tests.each do |extension, (expression, expected)|
+        program = CEL.compile(expression, extensions: [extension])
+        expect(program.execute).to eq(expected)
+        expect(program.execute(CEL::Context.new)).to eq(expected)
+      end
+    end
+
+    it "combines extensions with context variables and Ruby callbacks" do
+      context = CEL::Context.build(label: "TacoCat", scores: [2, 9, -3]) do |ctx|
+        ctx.define_function("decorate") { |value| "[#{value}]" }
+      end
+      program = CEL::Program.compile(
+        "[decorate(label.lowerAscii()), scores.sort(), math.greatest(scores), base64.encode(b'hi')]",
+        extensions: ["strings", "lists", "math", "encoders"]
+      )
+
+      expect(program.execute(context)).to eq(["[tacocat]", [-3, 2, 9], 9, "aGk="])
+    end
+
+    it "keeps extensions local to a program and excludes them from empty contexts" do
+      context = CEL::Context.new
+      enabled = CEL.compile("'ABC'.lowerAscii()", extensions: [:strings])
+      expect(enabled.execute(context)).to eq("abc")
+      expect { CEL.compile("'ABC'.lowerAscii()").execute(context) }.to raise_error(CEL::ExecutionError)
+      expect { enabled.execute(CEL::Context.new(true)) }.to raise_error(CEL::ExecutionError)
+
+      context.define_function("lowerAscii") { |value| value }
+      expect { enabled.execute(context) }.to raise_error(CEL::ExecutionError, /lowerAscii/)
+    end
+
+    it "rejects unknown and repeated extension registrations" do
+      expect { CEL.compile("1", extensions: [:unknown]) }.to raise_error(ArgumentError, /unknown/)
+      expect { CEL.compile("1", extensions: [:strings, "strings"]) }.to raise_error(ArgumentError)
+    end
   end
 
   describe CEL::Context do
@@ -63,6 +106,31 @@ RSpec.describe CEL do
       expect(CEL.compile("'hello'.startsWith('he')").execute(context)).to eq(true)
     end
 
+    it "marshals callback receivers, arguments, and results" do
+      context = CEL::Context.build(prefix: {"label" => "result"})
+      context.define_function("combine") do |target, values, suffix|
+        {target["label"] => values + [suffix]}
+      end
+
+      expect(CEL.compile("prefix.combine([2, 5], 9)").execute(context)).to eq("result" => [2, 5, 9])
+    end
+
+    it "reports builtin callback conflicts when building the execution context" do
+      context = CEL::Context.new
+      context.define_function("size") { |_| 99 }
+
+      expect { CEL.compile("size([1, 2])").execute(context) }
+        .to raise_error(CEL::ExecutionError, /size/)
+    end
+
+    it "replaces callbacks with the same name" do
+      context = CEL::Context.new
+      context.define_function("adjust") { |value| value + 1 }
+      context.define_function("adjust") { |value| value + 7 }
+
+      expect(CEL.compile("adjust(3)").execute(context)).to eq(10)
+    end
+
     it "raises clear type error for unsupported variable types" do
       context = CEL::Context.new
       expect { context.add_variable("bad", Object.new) }.to raise_error(CEL::TypeError)
@@ -77,6 +145,36 @@ RSpec.describe CEL do
       expect(refs["functions"]).to include("size")
     end
 
+    it "registers max and min by default" do
+      tests = {
+        "max(2, 9, -3)" => 9,
+        "min(2, 9, -3)" => -3,
+        "max([2, 9, -3])" => 9,
+        "min([2, 9, -3])" => -3,
+        "max()" => nil,
+        "min([])" => nil
+      }
+
+      [nil, CEL::Context.new].each do |context|
+        tests.each do |expression, expected|
+          expect(CEL.compile(expression).execute(context)).to eq(expected)
+        end
+      end
+    end
+
+    it "leaves max and min out of empty contexts and allows custom callbacks" do
+      ["max", "min"].each do |name|
+        program = CEL.compile("#{name}(2, 9)")
+        empty = CEL::Context.new(true)
+        expect { program.execute(empty) }.to raise_error(CEL::ExecutionError)
+
+        [empty, CEL::Context.new].each do |context|
+          context.define_function(name) { |a, b| a + b }
+          expect(program.execute(context)).to eq(11)
+        end
+      end
+    end
+
     it "ports core CEL suite behavior examples" do
       tests = {
         "size([1,2,3]) == 3" => true,
@@ -84,8 +182,13 @@ RSpec.describe CEL do
         "[1,2,3].filter(x, x > 1)" => [2, 3],
         "[1,2,3].exists(x, x == 2)" => true,
         "[1,2,3].all(x, x > 0)" => true,
-        "{'a': 1}.contains('a')" => true,
-        "optional.of(1).hasValue()" => true
+        "'a' in {'a': 1}" => true,
+        "optional.of(1).hasValue()" => true,
+        "size('café😊')" => 5,
+        "{'name': 'Ada'}.?name.optMap(n, n.size()).orValue(0)" => 3,
+        "{}.?name.optMap(n, n.size()).orValue(0)" => 0,
+        "{'user': {'name': 'Ada'}}.?user.optFlatMap(u, u.?name).orValue('missing')" => "Ada",
+        "[2, 1].exists(e, 6 / (2 - e) == 6)" => true
       }
 
       tests.each do |expr, expected|
@@ -113,6 +216,10 @@ RSpec.describe CEL do
       expect { program.execute }.to raise_error(CEL::ExecutionError)
     end
 
+    it "rejects duplicate map literal keys" do
+      expect { CEL.compile("{'a': 1, 'a': 2}").execute }.to raise_error(CEL::ExecutionError)
+    end
+
     it "releases GVL so other ruby threads can progress" do
       context = CEL::Context.new
       context.add_variable("items", Array.new(15_000, 1))

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cel-rs-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: x86_64-linux
 authors:
 - CEL Ruby Contributors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake