dentaku 3.5.8 → 4.0.1

data/lib/dentaku/ast/combinators.rb

@@ -1,4 +1,5 @@
 require_relative './operation'
+require 'dentaku/exceptions'
 
 module Dentaku
   module AST
@@ -20,10 +21,52 @@ module Dentaku
         :logical
       end
 
+      def dependencies(context = {})
+        return super if static_mode?(context)
+
+        left_deps = left.dependencies(context)
+        right_deps = right.dependencies(context)
+        return [] if left_deps.empty? && left.pure? && decisive?(left.value(context))
+        return [] if right_deps.empty? && right.pure? && decisive?(right.value(context))
+
+        (left_deps + right_deps).uniq
+      rescue Dentaku::Error
+        super
+      end
+
+      def value(context = {})
+        left_value = begin
+          left.value(context)
+        rescue UnboundVariableError => unbound
+          unbound
+        end
+
+        unless left_value.is_a?(UnboundVariableError)
+          return left_value if decisive?(left_value)
+
+          return right.value(context)
+        end
+
+        # The left operand is unbound; the right operand can still decide the
+        # result on its own. If it does not, the left value was needed.
+        right_value = right.value(context)
+        raise left_value unless decisive?(right_value)
+
+        right_value
+      end
+
       private
 
+      # static dependency check: this runs at parse time, and evaluating
+      # short-circuit guards here would execute user functions (#197)
       def valid_node?(node)
-        node && (node.dependencies.any? || node.type == :logical)
+        node && (node.dependencies(Node::STATIC_CONTEXT).any? || node.type == :logical)
+      end
+
+      # whether a single operand with this value already determines the
+      # result, regardless of the other operand
+      def decisive?(operand_value)
+        raise NotImplementedError
       end
     end
 
@@ -32,8 +75,10 @@ module Dentaku
         :and
       end
 
-      def value(context = {})
-        left.value(context) && right.value(context)
+      private
+
+      def decisive?(operand_value)
+        !operand_value
       end
     end
 
@@ -42,8 +87,10 @@ module Dentaku
         :or
       end
 
-      def value(context = {})
-        left.value(context) || right.value(context)
+      private
+
+      def decisive?(operand_value)
+        !!operand_value
       end
     end
   end

data/lib/dentaku/ast/comparators.rb

@@ -21,7 +21,7 @@ module Dentaku
 
         l.public_send(operator, r)
       rescue ::ArgumentError, ::TypeError => e
-        raise Dentaku::ArgumentError.for(:incompatible_type, value: r, for: l.class), e.message
+        raise Dentaku::ArgumentError.for(:incompatible_type, actual: r, expected: l.class), e.message
       end
 
       private
@@ -34,8 +34,7 @@ module Dentaku
 
       def validate_value(value)
         unless value.respond_to?(operator)
-          raise Dentaku::ArgumentError.for(:invalid_operator, operation: self.class, operator: operator),
-                "#{ self.class } requires operands that respond to #{operator}"
+          raise Dentaku::ArgumentError.for(:invalid_operator, operation: self.class, operator: operator)
         end
 
         value

data/lib/dentaku/ast/function.rb

@@ -22,12 +22,19 @@ module Dentaku
              .flat_map { |a, _| a.dependencies(context) }
       end
 
+      # volatile functions may not be evaluated during dependency
+      # resolution; registry-generated classes override this per the
+      # volatile: option passed at registration
+      def self.volatile?
+        false
+      end
+
       def self.get(name)
         registry.get(name)
       end
 
-      def self.register(name, type, implementation)
-        registry.register(name, type, implementation)
+      def self.register(name, type, implementation, volatile: false)
+        registry.register(name, type, implementation, volatile: volatile)
       end
 
       def self.register_class(name, function_class)
@@ -37,6 +44,12 @@ module Dentaku
       def self.registry
         @registry ||= FunctionRegistry.new
       end
+
+      private
+
+      def compute_pure?
+        !self.class.volatile? && args.all?(&:pure?)
+      end
     end
   end
 end

data/lib/dentaku/ast/function_registry.rb

@@ -8,7 +8,7 @@ module Dentaku
         nil
       end
 
-      def register(name, type, implementation, callback = nil)
+      def register(name, type, implementation, callback = nil, volatile: false)
         function = Class.new(Function) do
           def self.name=(name)
             @name = name.to_s
@@ -18,6 +18,21 @@ module Dentaku
             @name
           end
 
+          # only the first registration of a given name claims the constant
+          # under Dentaku::AST::Function, so later ones stay anonymous and
+          # would otherwise render as "#<Class:0x...>" in error messages
+          def self.display_name=(display_name)
+            @display_name = display_name
+          end
+
+          def self.to_s
+            @display_name || super
+          end
+
+          def self.inspect
+            to_s
+          end
+
           def self.implementation=(impl)
             @implementation = impl
           end
@@ -42,6 +57,14 @@ module Dentaku
             @callback
           end
 
+          def self.volatile=(volatile)
+            @volatile = volatile
+          end
+
+          def self.volatile?
+            @volatile
+          end
+
           def self.arity
             @implementation.arity < 0 ? nil : @implementation.arity
           end
@@ -64,12 +87,15 @@ module Dentaku
           end
         end
 
+        function.name = name
+        function.display_name = "#{Function}::#{normalize_name(name)}"
+
         define_class(name, function)
 
-        function.name = name
         function.type = type
         function.implementation = implementation
         function.callback = callback
+        function.volatile = volatile
 
         self[function_name(name)] = function
       end

data/lib/dentaku/ast/functions/and.rb

@@ -5,8 +5,8 @@ Dentaku::AST::Function.register(:and, :logical, lambda { |*args|
   if args.empty?
     raise Dentaku::ArgumentError.for(
       :too_few_arguments,
-      function_name: 'AND()', at_least: 1, given: 0
-    ), 'AND() requires at least one argument'
+      function_name: 'AND', expected: 1.., actual: 0
+    )
   end
 
   args.all? do |arg|
@@ -18,8 +18,8 @@ Dentaku::AST::Function.register(:and, :logical, lambda { |*args|
     else
       raise Dentaku::ArgumentError.for(
         :incompatible_type,
-        function_name: 'AND()', expect: :logical, actual: arg.class
-      ), 'AND() requires arguments to be logical expressions'
+        function_name: 'AND', expected: :logical, actual: arg
+      )
     end
   end
 })

data/lib/dentaku/ast/functions/avg.rb

@@ -5,8 +5,8 @@ Dentaku::AST::Function.register(:avg, :numeric, ->(*args) {
   if flatten_args.empty?
     raise Dentaku::ArgumentError.for(
         :too_few_arguments,
-        function_name: 'AVG()', at_least: 1, given: 0
-    ), 'AVG() requires at least one argument'
+        function_name: 'AVG', expected: 1.., actual: 0
+    )
   end
 
   flatten_args.map { |arg| Dentaku::NumericParser.ensure_numeric!(arg) }.reduce(0, :+) / BigDecimal(flatten_args.length)

data/lib/dentaku/ast/functions/duration.rb

@@ -25,7 +25,7 @@ module Dentaku
           when /months?/ then :month
           when /days?/ then :day
           else
-            raise Dentaku::ArgumentError.for(:incompatible_type, value: unit, for: Duration),
+            raise Dentaku::ArgumentError.for(:incompatible_type, actual: unit, expected: Duration),
               "'#{unit || unit.class}' is not a valid duration unit"
           end
         end

data/lib/dentaku/ast/functions/if.rb

@@ -36,8 +36,16 @@ module Dentaku
       end
 
       def dependencies(context = {})
+        return all_arg_dependencies(context) if static_mode?(context) || !predicate.pure?
+
         predicate.value(context) ? left.dependencies(context) : right.dependencies(context)
-      rescue Dentaku::Error, Dentaku::ArgumentError, Dentaku::ZeroDivisionError
+      rescue Dentaku::Error
+        all_arg_dependencies(context)
+      end
+
+      private
+
+      def all_arg_dependencies(context)
         args.flat_map { |arg| arg.dependencies(context) }.uniq
       end
     end

data/lib/dentaku/ast/functions/intercept.rb

@@ -4,7 +4,7 @@ Dentaku::AST::Function.register(:intercept, :list, ->(*args) {
   if args.length != 2
     raise Dentaku::ArgumentError.for(
         :wrong_number_of_arguments,
-        function_name: 'INTERCEPT()', exact: 2, given: args.length
+        function_name: 'INTERCEPT', expected: 2, actual: args.length
     ), 'INTERCEPT() requires exactly two arrays of numbers'
   end
 
@@ -12,7 +12,7 @@ Dentaku::AST::Function.register(:intercept, :list, ->(*args) {
   if !x_values.is_a?(Array) || !y_values.is_a?(Array) || x_values.length != y_values.length
     raise Dentaku::ArgumentError.for(
         :invalid_value,
-        function_name: 'INTERCEPT()'
+        function_name: 'INTERCEPT'
     ), 'INTERCEPT() requires arrays of equal length'
   end
 

data/lib/dentaku/ast/functions/mul.rb

@@ -4,8 +4,8 @@ Dentaku::AST::Function.register(:mul, :numeric, ->(*args) {
   if args.empty?
     raise Dentaku::ArgumentError.for(
         :too_few_arguments,
-        function_name: 'MUL()', at_least: 1, given: 0
-    ), 'MUL() requires at least one argument'
+        function_name: 'MUL', expected: 1.., actual: 0
+    )
   end
 
   args.flatten.map { |arg| Dentaku::NumericParser.ensure_numeric!(arg) }.reduce(1, :*)

data/lib/dentaku/ast/functions/or.rb

@@ -5,8 +5,8 @@ Dentaku::AST::Function.register(:or, :logical, lambda { |*args|
   if args.empty?
     raise Dentaku::ArgumentError.for(
       :too_few_arguments,
-      function_name: 'OR()', at_least: 1, given: 0
-    ), 'OR() requires at least one argument'
+      function_name: 'OR', expected: 1.., actual: 0
+    )
   end
 
   args.any? do |arg|
@@ -18,8 +18,8 @@ Dentaku::AST::Function.register(:or, :logical, lambda { |*args|
     else
       raise Dentaku::ArgumentError.for(
         :incompatible_type,
-        function_name: 'OR()', expect: :logical, actual: arg.class
-      ), 'OR() requires arguments to be logical expressions'
+        function_name: 'OR', expected: :logical, actual: arg
+      )
     end
   end
 })

data/lib/dentaku/ast/functions/pluck.rb

@@ -16,7 +16,7 @@ module Dentaku
         collection = Array(@args[0].value(context))
 
         unless collection.all? { |elem| elem.is_a?(Hash) }
-          raise ArgumentError.for(:incompatible_type, value: collection),
+          raise ArgumentError.for(:incompatible_type, actual: collection),
                 'PLUCK() requires first argument to be an array of hashes'
         end
 

data/lib/dentaku/ast/functions/string_functions.rb

@@ -11,7 +11,7 @@ module Dentaku
         def negative_argument_failure(fun, arg = 'length')
           raise Dentaku::ArgumentError.for(
             :invalid_value,
-            function_name: "#{fun}()"
+            function_name: fun
           ), "#{fun}() requires #{arg} to be positive"
         end
       end

data/lib/dentaku/ast/functions/sum.rb

@@ -4,8 +4,8 @@ Dentaku::AST::Function.register(:sum, :numeric, ->(*args) {
   if args.empty?
     raise Dentaku::ArgumentError.for(
         :too_few_arguments,
-        function_name: 'SUM()', at_least: 1, given: 0
-    ), 'SUM() requires at least one argument'
+        function_name: 'SUM', expected: 1.., actual: 0
+    )
   end
 
   args.flatten.map { |arg| Dentaku::NumericParser.ensure_numeric!(arg) }.reduce(0, :+)

data/lib/dentaku/ast/functions/xor.rb

@@ -16,8 +16,8 @@ module Dentaku
         if @args.empty?
           raise Dentaku::ArgumentError.for(
             :too_few_arguments,
-            function_name: 'XOR()', at_least: 1, given: 0
-          ), 'XOR() requires at least one argument'
+            function_name: 'XOR', expected: 1.., actual: 0
+          )
         end
 
         true_arg_count = 0
@@ -31,8 +31,8 @@ module Dentaku
           else
             raise Dentaku::ArgumentError.for(
               :incompatible_type,
-              function_name: 'XOR()', expect: :logical, actual: arg.class
-            ), 'XOR() requires arguments to be logical expressions'
+              function_name: 'XOR', expected: :logical, actual: arg
+            )
           end
         end
         true_arg_count == 1

data/lib/dentaku/ast/grouping.rb

@@ -18,6 +18,12 @@ module Dentaku
       def dependencies(context = {})
         @node.dependencies(context)
       end
+
+      private
+
+      def compute_pure?
+        @node.pure?
+      end
     end
   end
 end

data/lib/dentaku/ast/negation.rb

@@ -46,8 +46,15 @@ module Dentaku
 
       private
 
+      # bypasses Operation's binary initialize, so left/right are unset
+      def compute_pure?
+        @node.pure?
+      end
+
+      # static dependency check: this runs at parse time, and evaluating
+      # short-circuit guards here would execute user functions (#197)
       def valid_node?(node)
-        node && (node.dependencies.any? || node.type == :numeric)
+        node && (node.dependencies(Node::STATIC_CONTEXT).any? || node.type == :numeric)
       end
     end
   end

data/lib/dentaku/ast/node.rb

@@ -1,6 +1,12 @@
 module Dentaku
   module AST
     class Node
+      # reserved context key (double-underscore prefix, like
+      # __evaluation_mode) that switches dependencies() into static mode:
+      # guards are never evaluated and every branch is reported
+      STATIC_MODE_KEY = "__static_dependencies".freeze
+      STATIC_CONTEXT = { STATIC_MODE_KEY => true }.freeze
+
       def self.precedence
         0
       end
@@ -17,6 +23,15 @@ module Dentaku
         []
       end
 
+      # whether this subtree may be evaluated during dependency resolution
+      # without running volatile user code; a property of the parsed AST,
+      # computed once and memoized
+      def pure?
+        return @pure if defined?(@pure)
+
+        @pure = compute_pure?
+      end
+
       def type
         nil
       end
@@ -24,6 +39,16 @@ module Dentaku
       def name
         self.class.name.to_s.split("::").last.upcase
       end
+
+      private
+
+      def static_mode?(context)
+        context[STATIC_MODE_KEY] == true
+      end
+
+      def compute_pure?
+        true
+      end
     end
   end
 end

data/lib/dentaku/ast/operation.rb

@@ -39,6 +39,13 @@ module Dentaku
       def operator_spacing
         " "
       end
+
+      private
+
+      # compact: unary operations (e.g. Percentage) only populate left
+      def compute_pure?
+        [left, right].compact.all?(&:pure?)
+      end
     end
   end
 end

data/lib/dentaku/bulk_expression_solver.rb

@@ -11,8 +11,8 @@ module Dentaku
         @calculator = calculator
       end
 
-      def evaluate(*args)
-        @calculator.evaluate!(*args)
+      def evaluate(*args, &block)
+        @calculator.evaluate!(*args, &block)
       end
     end
 
@@ -22,10 +22,9 @@ module Dentaku
         @block = block || ->(*) { :undefined }
       end
 
-      def evaluate(*args)
-        @calculator.evaluate(*args) { |expr, ex|
-          @block.call(ex)
-        }
+      def evaluate(*args, &block)
+        handler = block || ->(_expr, ex) { @block.call(ex) }
+        @calculator.evaluate(*args, &handler)
       end
     end
 
@@ -79,7 +78,7 @@ module Dentaku
 
     def expression_with_exception_handler(var_name, &block)
       ->(_expr, ex) {
-        ex.recipient_variable = var_name
+        ex.assigned_to = var_name
         block.call(ex)
       }
     end
@@ -106,7 +105,7 @@ module Dentaku
             context.merge(results),
             &expression_with_exception_handler(var_name, &block)
           ).tap { |res|
-            res.recipient_variable = var_name if res.respond_to?(:recipient_variable=)
+            res.assigned_to = var_name if res.respond_to?(:assigned_to=)
             res
           }
         end
@@ -120,7 +119,7 @@ module Dentaku
     def with_rescues(var_name, results, block)
       yield
     rescue Dentaku::UnboundVariableError, Dentaku::ZeroDivisionError, Dentaku::ArgumentError => ex
-      ex.recipient_variable = var_name
+      ex.assigned_to = var_name
       results[var_name] = block.call(ex)
     ensure
       stored_name = normalized_name(var_name)
@@ -157,7 +156,7 @@ module Dentaku
       cache_key = "#{!!calculator.case_sensitive}|#{expressions.keys.map(&:to_s).sort.join("|")}"
       @ordered_deps ||= self.class.dependency_cache.fetch(cache_key) {
         DependencyResolver.find_resolve_order(dependencies, calculator.case_sensitive).tap do |d|
-          self.class.dependency_cache[cache_key] = d if Dentaku.cache_dependency_order?
+          self.class.dependency_cache[cache_key] = d if calculator.cache_dependency_order?
         end
       }
     end