dentaku 3.5.8 → 4.0.0

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
@@ -42,6 +42,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
@@ -70,6 +78,7 @@ module Dentaku
         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,6 +46,11 @@ module Dentaku
 
       private
 
+      # bypasses Operation's binary initialize, so left/right are unset
+      def compute_pure?
+        @node.pure?
+      end
+
       def valid_node?(node)
         node && (node.dependencies.any? || node.type == :numeric)
       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

data/lib/dentaku/calculator.rb

@@ -9,38 +9,46 @@ require 'dentaku/token'
 module Dentaku
   class Calculator
     include StringCasing
-    attr_reader :result, :memory, :tokenizer, :case_sensitive, :aliases,
+    attr_reader :result, :memory, :tokenizer, :case_sensitive,
                 :nested_data_support, :ast_cache, :raw_date_literals
 
-    def initialize(options = {})
+    def initialize(case_sensitive: false, aliases: nil, nested_data_support: true,
+                   raw_date_literals: true, ast_cache: {},
+                   cache_ast: nil, cache_dependency_order: nil)
       clear
       @tokenizer = Tokenizer.new
-      @case_sensitive = options.delete(:case_sensitive)
-      @aliases = options.delete(:aliases) || Dentaku.aliases
-      @nested_data_support = options.fetch(:nested_data_support, true)
-      options.delete(:nested_data_support)
-      @raw_date_literals = options.fetch(:raw_date_literals, true)
-      options.delete(:raw_date_literals)
-      @ast_cache = options
+      @case_sensitive = case_sensitive
+      @aliases = aliases
+      @nested_data_support = nested_data_support
+      @raw_date_literals = raw_date_literals
+      @ast_cache = ast_cache
+      @cache_ast = cache_ast
+      @cache_dependency_order = cache_dependency_order
       @disable_ast_cache = false
       @function_registry = Dentaku::AST::FunctionRegistry.new
     end
 
-    def self.add_function(name, type, body, callback = nil)
-      Dentaku::AST::FunctionRegistry.default.register(name, type, body, callback)
+    # explicitly configured aliases win; otherwise the module-level default is
+    # resolved lazily so it can be set after this calculator was created
+    def aliases
+      @aliases || Dentaku.aliases
+    end
+
+    def self.add_function(name, type, body, callback = nil, volatile: false)
+      Dentaku::AST::FunctionRegistry.default.register(name, type, body, callback, volatile: volatile)
     end
 
     def self.add_functions(functions)
-      functions.each { |(name, type, body, callback)| add_function(name, type, body, callback) }
+      functions.each { |(name, type, body, callback, volatile)| add_function(name, type, body, callback, volatile: !!volatile) }
     end
 
-    def add_function(name, type, body, callback = nil)
-      @function_registry.register(name, type, body, callback)
+    def add_function(name, type, body, callback = nil, volatile: false)
+      @function_registry.register(name, type, body, callback, volatile: volatile)
       self
     end
 
     def add_functions(functions)
-      functions.each { |(name, type, body, callback)| add_function(name, type, body, callback) }
+      functions.each { |(name, type, body, callback, volatile)| add_function(name, type, body, callback, volatile: !!volatile) }
       self
     end
 
@@ -56,7 +64,7 @@ module Dentaku
       return evaluate_array(expression, context, &block) if expression.is_a?(Array)
 
       evaluate!(expression, context)
-    rescue Dentaku::Error, Dentaku::ArgumentError, Dentaku::ZeroDivisionError => ex
+    rescue Dentaku::Error => ex
       block.call(expression, ex) if block_given?
     end
 
@@ -106,6 +114,20 @@ module Dentaku
       end
     end
 
+    # every identifier the expression could reference, regardless of
+    # branching: purely syntactic, ignores stored memory, and never
+    # evaluates guards or functions
+    def identifiers(expression)
+      case expression
+      when Dentaku::AST::Node
+        expression.dependencies(AST::Node::STATIC_CONTEXT).uniq
+      when Array
+        expression.flat_map { |e| identifiers(e) }.uniq
+      else
+        ast(expression).dependencies(AST::Node::STATIC_CONTEXT).uniq
+      end
+    end
+
     def ast(expression)
       return expression if expression.is_a?(AST::Node)
       return expression.map { |e| ast(e) } if expression.is_a? Array
@@ -186,7 +208,13 @@ module Dentaku
     end
 
     def cache_ast?
-      Dentaku.cache_ast? && !@disable_ast_cache
+      return false if @disable_ast_cache
+
+      @cache_ast.nil? ? Dentaku.cache_ast? : @cache_ast
+    end
+
+    def cache_dependency_order?
+      @cache_dependency_order.nil? ? Dentaku.cache_dependency_order? : @cache_dependency_order
     end
   end
 end

data/lib/dentaku/date_arithmetic.rb

@@ -20,7 +20,7 @@ module Dentaku
           change_datetime(@base, duration.unit, duration.value)
         end
       else
-        raise Dentaku::ArgumentError.for(:incompatible_type, value: duration, for: Numeric),
+        raise Dentaku::ArgumentError.for(:incompatible_type, actual: duration, expected: Numeric),
           "'#{duration || duration.class}' is not coercible for date arithmetic"
       end
     end
@@ -39,7 +39,7 @@ module Dentaku
       when Dentaku::TokenScanner::DATE_TIME_REGEXP
         @base - Time.parse(duration).to_datetime
       else
-        raise Dentaku::ArgumentError.for(:incompatible_type, value: duration, for: Numeric),
+        raise Dentaku::ArgumentError.for(:incompatible_type, actual: duration, expected: Numeric),
           "'#{duration || duration.class}' is not coercible for date arithmetic"
       end
     end

data/lib/dentaku/exceptions.rb

@@ -1,9 +1,16 @@
 module Dentaku
-  class Error < StandardError
-    attr_accessor :recipient_variable
+  # Shared by all Dentaku exceptions so that `rescue Dentaku::Error` catches
+  # everything the gem raises, including exceptions that subclass Ruby
+  # built-ins (Dentaku::ArgumentError, Dentaku::ZeroDivisionError).
+  module Error
+    attr_accessor :assigned_to
   end
 
-  class UnboundVariableError < Error
+  class BaseError < StandardError
+    include Error
+  end
+
+  class UnboundVariableError < BaseError
     attr_reader :unbound_variables
 
     def initialize(unbound_variables)
@@ -11,7 +18,7 @@ module Dentaku
     end
   end
 
-  class MathDomainError < Error
+  class MathDomainError < BaseError
     attr_reader :function_name, :args
 
     def initialize(function_name, args)
@@ -20,22 +27,23 @@ module Dentaku
     end
   end
 
-  class NodeError < Error
-    attr_reader :child, :expect, :actual
+  class NodeError < BaseError
+    attr_reader :operand, :expected, :actual
 
-    def initialize(expect, actual, child)
-      @expect = Array(expect)
+    def initialize(expected, actual, operand)
+      @expected = Array(expected)
       @actual = actual
-      @child = child
+      @operand = operand
     end
   end
 
-  class ParseError < Error
+  class ParseError < BaseError
     attr_reader :reason, :meta
 
     def initialize(reason, **meta)
       @reason = reason
       @meta = meta
+      super(default_message)
     end
 
     private_class_method :new
@@ -54,14 +62,49 @@ module Dentaku
 
       new(reason, **meta)
     end
+
+    private
+
+    def default_message
+      case reason
+      when :node_invalid
+        if meta.key?(:operation)
+          expected = Array(meta[:expected]).map { |e| e == :incompatible ? :compatible : e }
+          "#{meta[:operation]} requires #{expected.join(', ')} operands, but got #{meta[:actual]}"
+        else
+          "Node is invalid"
+        end
+      when :too_few_operands
+        "#{meta[:operation]} has too few operands (given #{meta[:actual]}, expected #{meta[:expected]})"
+      when :too_many_operands
+        "#{meta[:operation]} has too many operands (given #{meta[:actual]}, expected #{meta[:expected]})"
+      when :undefined_function
+        "Undefined function #{meta[:function_name]}"
+      when :unprocessed_token
+        "Unprocessed token #{meta[:token_name]}"
+      when :unknown_case_token
+        "Unknown case token #{meta[:token_name]}"
+      when :unbalanced_bracket
+        "Unbalanced bracket"
+      when :unbalanced_parenthesis
+        "Unbalanced parenthesis"
+      when :unknown_grouping_token
+        "Unknown grouping token #{meta[:token_name]}"
+      when :not_implemented_token_category
+        "Not implemented for tokens of category #{meta[:token_category]}"
+      when :invalid_statement
+        "Invalid statement"
+      end
+    end
   end
 
-  class TokenizerError < Error
+  class TokenizerError < BaseError
     attr_reader :reason, :meta
 
     def initialize(reason, **meta)
       @reason = reason
       @meta = meta
+      super(default_message)
     end
 
     private_class_method :new
@@ -80,15 +123,32 @@ module Dentaku
 
       new(reason, **meta)
     end
+
+    private
+
+    def default_message
+      case reason
+      when :parse_error
+        "parse error at: '#{meta[:at]}'"
+      when :too_many_opening_parentheses
+        "too many opening parentheses"
+      when :too_many_closing_parentheses
+        "too many closing parentheses"
+      when :unexpected_zero_width_match
+        "unexpected zero-width match (:#{meta[:token_category]}) at '#{meta[:at]}'"
+      end
+    end
   end
 
   class ArgumentError < ::ArgumentError
+    include Error
+
     attr_reader :reason, :meta
-    attr_accessor :recipient_variable
 
     def initialize(reason, **meta)
       @reason = reason
       @meta = meta
+      super(default_message)
     end
 
     private_class_method :new
@@ -108,9 +168,41 @@ module Dentaku
 
       new(reason, **meta)
     end
+
+    private
+
+    def default_message
+      case reason
+      when :incompatible_type
+        if meta.key?(:function_name)
+          "#{meta[:function_name]}() requires #{meta[:expected]} arguments, but got #{meta[:actual].class}"
+        else
+          "#{meta[:actual].class} is not compatible with #{meta[:expected]}"
+        end
+      when :invalid_operator
+        "#{meta[:operation]} requires operands that respond to #{meta[:operator]}"
+      when :invalid_value
+        if meta.key?(:expected)
+          "'#{meta[:actual]}' is not a valid #{meta[:expected]}"
+        elsif meta.key?(:actual)
+          "'#{meta[:actual]}' is not a valid value"
+        else
+          "Invalid value"
+        end
+      when :too_few_arguments
+        "#{meta[:function_name]}() has too few arguments (given #{meta[:actual]}, expected #{expected_count})"
+      when :wrong_number_of_arguments
+        "#{meta[:function_name]}() has the wrong number of arguments (given #{meta[:actual]}, expected #{expected_count})"
+      end
+    end
+
+    def expected_count
+      expected = meta[:expected]
+      expected.is_a?(Range) && expected.end.nil? ? "at least #{expected.begin}" : expected
+    end
   end
 
   class ZeroDivisionError < ::ZeroDivisionError
-    attr_accessor :recipient_variable
+    include Error
   end
 end

data/lib/dentaku/numeric_parser.rb

@@ -54,7 +54,7 @@ module Dentaku
           return number if number
         end
 
-        raise Dentaku::ArgumentError.for(:incompatible_type, value: value, for: Numeric),
+        raise Dentaku::ArgumentError.for(:incompatible_type, actual: value, expected: Numeric),
           "'#{value || value.class}' is not coercible to numeric"
       end