cel 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4d35d9012196d61497f40e35c8e9dd9b1a9d7e1e922078a414cd574eacc439a
-  data.tar.gz: f2a0e48bc07e0c0b5eb23c7ea6d709a1b56fff3400b51204d26c3031f11db696
+  metadata.gz: 5e83a98ac5e076442ae06b53d13f43581a3982196f57582bbac02a08eef46ca9
+  data.tar.gz: 1fdb06029d13f3a47037688df7d4d4a77f65e237aa73d0e00fb6989a78600000
 SHA512:
-  metadata.gz: d39c028b26513ed27749f5bd7c5cfa57281b0433a5b5984418d657fd61441122e4cddae1942cdb7b3e3c9aeb0979d7387ca5d7444cea0afd04477615278acbfa
-  data.tar.gz: 442da2f399685e77bee5f743c693f0ef0fe9b333dfea333f61b17f8419a6bf7752aca14e0c5211ff0a8a526bc36a9a575a9e0cac53190f47e3af0b54097c26de
+  metadata.gz: 59eb650749f3b0fcef9a8ee66b6850831db66f116d851f35894d375191e280cac465e48c1f39103d6fcb21f7ebcf6c695f2cd286c65bcfb6c12ef08ddcb07400
+  data.tar.gz: b6dada73b82d27a17a6d9f23a672f36ec7c9af6f89eebef788227aba7b22cdc88720100ffcf5f466db70e923db689ff4df903942abb7ab2f8adeef70de4604df

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 ## [Unreleased]
 
+## [0.5.0] - 2025-12-11
+
+### Features
+
+#### Custom extensions
+
+A new `:extensions` kwarg is added to `Cel::Environment.new` which allows adding custom extensions, in a similar manner as what the standard extensions (like `math` or `string`) are done:
+
+```ruby
+module Ext
+  # defines a random function which takes no arguments and returns 42
+end
+
+Cel::Environment.new.evaluate("ext.random()") #=> raises error
+Cel::Environment.new(extensions: { ext: Ext }).evaluate("ext.random()") #=> 42
+```
+
+### Backwards Compatibility
+
+The ractor safety introduced in 0.4.1 has been relaxed in order to allow extensions of core classes by custom extensions, And you'll need to explicitly call `Cel.freeze` before using `cel` inside ractors. This is a direct consequence of how extensions patch `cel` core classes.
+
+ATTENTION: Changes may be introduced in the way core classes are patched by extensions, towards making `cel` ractor-safe by default. If you rely on custom extensions, do follow the migration instructions in subsequent releases.
+
+### Bugfixes
+
+Fixed checker type inference when using nexted expressions (like when using the `bind` extensions to evaluate cel sub-expressions).
+
 ## [0.4.1] - 2025-11-25
 
 ### Improvements

data/README.md

@@ -162,6 +162,35 @@ res = env.evaluate('tuple(1, 2)') #=> Tuple instance
 res.value #=> [1, 2]
 ```
 
+### Custom Extensions
+
+`cel` already supports the [conformance spec extensions packages](https://pkg.go.dev/github.com/google/cel-go/ext#section-readme). However, if you need to add your own, you can do so:
+
+```ruby
+module Ext
+  def __check(funcall, checker:)
+    func = funcall.func
+    args = funcall.args
+
+    case func
+    when :random
+      checker.check_arity(func, args, 0)
+      return TYPES[:int]
+    else
+      checker.unsupported_operation(funcall)
+    end
+  end
+
+  # extensions will always receive the program instance as a kwarg
+  def random(program:)
+    42
+  end
+end
+
+env = Cel::Environment.new(extensions: { ext: Ext})
+env.evaluate("ext.random()") #=> 42
+```
+
 ## Spec Coverage
 
 `cel` is tested against the conformance suite from the [cel-spec repository](https://github.com/google/cel-spec/tree/master/conformance), and supports all features from the language except:
@@ -180,6 +209,14 @@ If this is something you're interested in (helping out), add a mention in the co
 
 All Rubies greater or equal to 2.7, and always latest JRuby and Truffleruby.
 
+`cel` can be used inside ractors, but you need to freeze it first:
+
+```ruby
+# can't be used in ractors
+Cel.freeze
+# can be used in ractors
+```
+
 ## Development
 
 Clone the repo in your local machine, where you have `ruby` installed. Then you can:

data/lib/cel/checker.rb

@@ -85,12 +85,12 @@ module Cel
       raise CheckError, "unsupported operation (#{op})"
     end
 
-    private
-
     def merge(declarations)
       Checker.new(@environment, @declarations ? @declarations.merge(declarations) : declarations)
     end
 
+    private
+
     def check_literal(literal)
       case literal
       when List
@@ -228,8 +228,8 @@ module Cel
 
       return check_standard_func(funcall) unless var
 
-      if var.is_a?(Identifier) && Cel::EXTENSIONS.include?(var.to_sym)
-        return Cel::EXTENSIONS[var.to_sym].__check(funcall, checker: self)
+      if var.is_a?(Identifier) && @environment.extensions.include?(var.to_sym)
+        return @environment.extensions[var.to_sym].__check(funcall, checker: self)
       end
 
       var_type ||= infer_variable_type(var)
@@ -321,7 +321,9 @@ module Cel
           var_type.element_type = element_checker.check(predicate)
           var_type
         else
-          return Cel::EXTENSIONS[:strings].__check(funcall, checker: self) if Cel::EXTENSIONS.key?(:strings)
+          if @environment.extensions.key?(:strings)
+            return @environment.extensions[:strings].__check(funcall, checker: self)
+          end
 
           unsupported_operation(funcall)
         end
@@ -335,7 +337,9 @@ module Cel
           # TODO: verify if string can be transformed into a regex
           return TYPES[:bool] if find_match_all_types(%i[string], call(args.first))
         else
-          return Cel::EXTENSIONS[:strings].__check(funcall, checker: self) if Cel::EXTENSIONS.key?(:strings)
+          if @environment.extensions.key?(:strings)
+            return @environment.extensions[:strings].__check(funcall, checker: self)
+          end
 
           unsupported_type(funcall)
         end

data/lib/cel/context.rb

@@ -2,13 +2,17 @@
 
 module Cel
   class Context
-    attr_reader :declarations, :bindings
+    attr_reader :bindings
 
-    def initialize(declarations, bindings)
-      @declarations = declarations
+    def initialize(environment, bindings)
+      @environment = environment
       @bindings = bindings.dup
     end
 
+    def declarations
+      @environment.declarations
+    end
+
     def lookup(identifier)
       raise EvaluateError, "no value in context for #{identifier}" unless @bindings
 
@@ -63,7 +67,7 @@ module Cel
     end
 
     def merge(bindings)
-      Context.new(@declarations, @bindings ? @bindings.merge(bindings) : bindings)
+      Context.new(@environment, @bindings ? @bindings.merge(bindings) : bindings)
     end
 
     private
@@ -73,7 +77,7 @@ module Cel
     end
 
     def to_cel_primitive(k, v)
-      if @declarations && (type = @declarations[k])
+      if @environment.declarations && (type = @environment.declarations[k])
         type = TYPES[type] if type.is_a?(Symbol)
 
         if type.is_a?(Class) && type < Protobuf.base_class

data/lib/cel/environment.rb

@@ -2,17 +2,19 @@
 
 module Cel
   class Environment
-    attr_reader :declarations, :package
+    attr_reader :declarations, :extensions, :package
 
     def initialize(
       declarations: nil,
       container: nil,
+      extensions: nil,
       disable_check: false,
       **kwargs
     )
       @disable_check = disable_check
       @declarations = declarations
       @container = container
+      @extensions = extensions ? EXTENSIONS.merge(extensions) : EXTENSIONS
       @package = nil
       @checker = Checker.new(self)
 
@@ -65,10 +67,12 @@ module Cel
 
     def evaluate(expr, bindings = nil)
       declarations, bindings = process_bindings(bindings)
-      context = Context.new(declarations, bindings)
+      context = Context.new(self, bindings)
       expr = @parser.parse(expr) if expr.is_a?(::String)
       @checker.check(expr) unless @disable_check
-      Program.new(context, self).evaluate(expr)
+      with(declarations: declarations) do
+        Program.new(context, self).evaluate(expr)
+      end
     end
 
     def process_bindings(bindings)
@@ -93,14 +97,17 @@ module Cel
 
     def with(declarations:, disable_check: @disable_check)
       prev_declarations = @declarations
+      prev_checker = @checker
       prev_disable_check = @disable_check
 
-      @declarations = declarations.merge(declarations)
+      @declarations = prev_declarations ? prev_declarations.merge(declarations) : declarations
+      @checker = prev_checker.merge(@declarations)
       @disable_check = disable_check
 
       yield
     ensure
       @declarations = prev_declarations
+      @checker = prev_checker
       @disable_check = prev_disable_check
     end
 
@@ -116,8 +123,8 @@ module Cel
     end
 
     def evaluate(bindings = nil)
-      declarations, bindings = @environment.process_bindings(bindings)
-      context = Context.new(declarations, bindings)
+      _, bindings = @environment.process_bindings(bindings)
+      context = Context.new(@environment, bindings)
       Program.new(context, @environment).evaluate(@ast)
     end
   end

data/lib/cel/extensions/bind.rb

@@ -19,15 +19,14 @@ module Cel
 
         type = checker.call(type)
 
-        checker.environment.with(declarations: { id => type }) do
+        checker.environment.with(declarations: { id.to_sym => type }) do
           checker.environment.check(expr)
         end
       end
 
       def bind(var, val, expr, program:)
         program.environment.with(declarations: { var.to_sym => val.type }, disable_check: false) do
-          bindings = program.context.bindings.merge({ var.to_sym => val })
-          program.environment.evaluate(expr, bindings)
+          program.with_extra_context({ var.to_sym => val }).evaluate(expr)
         end
       end
     end

data/lib/cel/program.rb

@@ -57,8 +57,8 @@ module Cel
     def evaluate_identifier(identifier)
       id_sym = identifier.to_sym
 
-      if Cel::EXTENSIONS.key?(id_sym)
-        Cel::EXTENSIONS[id_sym]
+      if @environment.extensions.key?(id_sym)
+        @environment.extensions[id_sym]
       elsif Cel::PRIMITIVE_TYPES.include?(id_sym)
         TYPES[identifier.to_sym]
       else

data/lib/cel/version.rb

@@ -2,6 +2,6 @@
 
 module Cel
   module Ruby
-    VERSION = "0.4.1"
+    VERSION = "0.5.0"
   end
 end

data/lib/cel.rb

@@ -255,16 +255,19 @@ module Cel
     end.join("::")
   end
 
-  # freeze constants to make cel ractor-friendly
-  Number.freeze
-  Bool.freeze
-  Null.freeze
-  String.freeze
-  Bytes.freeze
-  List.freeze
-  Map.freeze
-  Timestamp.freeze
-  Duration.freeze
-  Type.freeze
-  TYPES.each_value(&:freeze).freeze
+  def freeze
+    # freeze constants to make cel ractor-friendly
+    Number.freeze
+    Bool.freeze
+    Null.freeze
+    String.freeze
+    Bytes.freeze
+    List.freeze
+    Map.freeze
+    Timestamp.freeze
+    Duration.freeze
+    Type.freeze
+    TYPES.each_value(&:freeze).freeze
+    super
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cel
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Tiago Cardoso