dentaku 3.5.7 → 4.0.0

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/dependency_resolver.rb

@@ -5,13 +5,14 @@ module Dentaku
     include TSort
 
     def self.find_resolve_order(vars_to_dependencies_hash, case_sensitive = false)
-      self.new(vars_to_dependencies_hash).sort
+      self.new(vars_to_dependencies_hash, case_sensitive).sort
     end
 
-    def initialize(vars_to_dependencies_hash)
-      @key_mapping = Hash[vars_to_dependencies_hash.keys.map { |k| [k.downcase, k] }]
-      # ensure variables are normalized strings
-      @vars_to_deps = Hash[vars_to_dependencies_hash.map { |k, v| [k.downcase.to_s, v] }]
+    def initialize(vars_to_dependencies_hash, case_sensitive = false)
+      @case_sensitive = case_sensitive
+      @key_mapping = Hash[vars_to_dependencies_hash.keys.map { |k| [normalized_name(k), k] }]
+      # normalize variables and their dependencies alike so child lookups match
+      @vars_to_deps = Hash[vars_to_dependencies_hash.map { |k, v| [normalized_name(k), v.map { |d| normalized_name(d) }] }]
     end
 
     def sort
@@ -25,5 +26,11 @@ module Dentaku
     def tsort_each_child(node, &block)
       @vars_to_deps.fetch(node.to_s, []).each(&block)
     end
+
+    private
+
+    def normalized_name(variable_name)
+      @case_sensitive ? variable_name.to_s : variable_name.to_s.downcase
+    end
   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

@@ -0,0 +1,68 @@
+module Dentaku
+  module NumericParser
+    NUMERIC_PATTERN = '((?:\d+(\.\d+)?|\.\d+)(?:(e|E)(\+|-)?\d+)?)\b'.freeze
+    # e.g:  [2, 1.2, .5, 1e10, 1.5E-10]
+    HEXADECIMAL_PATTERN = '(0x[0-9a-f]+)\b'.freeze
+    # e.g:  [0x1A3F]
+
+    class << self
+      def match(string)
+        regex = %r{\A(-?(#{ NUMERIC_PATTERN }|#{ HEXADECIMAL_PATTERN }))\z}i
+        string.match(regex)
+      end
+
+      def match_numeric(string)
+        regex = %r{\A(#{ NUMERIC_PATTERN })\z}i
+        string.match(regex)
+      end
+
+      def match_hexadecimal(string)
+        regex = %r{\A(#{ HEXADECIMAL_PATTERN })\z}i
+        string.match(regex)
+      end
+
+      def parse_numeric_string(raw)
+        raw =~ /(\.|e|E)/ ? BigDecimal(raw, Float::DIG + 1) : raw.to_i
+      end
+
+      def parse_hexadecimal_string(raw)
+        raw[2..-1].to_i(16)
+      end
+
+      def parse_string(raw)
+        return nil unless !!match(raw)
+
+        is_negative = raw.start_with?('-')
+        number_part = is_negative ? raw[1..-1] : raw
+
+        value = if number_part =~ /\A0x/i
+          parse_hexadecimal_string(number_part)
+        else
+          parse_numeric_string(number_part)
+        end
+
+        is_negative ? -value : value
+      end
+
+      # @return [Numeric] where possible it returns an Integer otherwise a BigDecimal.
+      # An Exception will be raised if a value is passed that cannot be cast to a Number.
+      def ensure_numeric!(value)
+        return value if value.is_a?(::Numeric)
+
+        if value.is_a?(::String)
+          number = parse_string(value)
+          return number if number
+        end
+
+        raise Dentaku::ArgumentError.for(:incompatible_type, actual: value, expected: Numeric),
+          "'#{value || value.class}' is not coercible to numeric"
+      end
+
+      def ensure_numeric(value)
+        ensure_numeric!(value)
+      rescue Dentaku::ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/dentaku/parser.rb

@@ -41,41 +41,42 @@ module Dentaku
     end
 
     def consume(count = 2)
-      operator = operations.pop
-      fail! :invalid_statement if operator.nil?
+      operation = operations.pop
+      fail! :invalid_statement if operation.nil?
 
       output_size = output.length
-      args_size = operator.arity || count
-      min_size = operator.arity || operator.min_param_count || count
-      max_size = operator.arity || operator.max_param_count || count
+      args_size = operation.arity || count
+      min_size = operation.arity || operation.min_param_count || count
+      max_size = operation.arity || operation.max_param_count || count
 
       if output_size < min_size || args_size < min_size
-        expect = min_size == max_size ? min_size : min_size..max_size
-        fail! :too_few_operands, operator: operator, expect: expect, actual: output_size
+        expected = min_size == max_size ? min_size : min_size..max_size
+        fail! :too_few_operands, operation: operation, expected: expected, actual: output_size
       end
 
       if (output_size > max_size && operations.empty?) || args_size > max_size
-        expect = min_size == max_size ? min_size : min_size..max_size
-        fail! :too_many_operands, operator: operator, expect: expect, actual: output_size
+        expected = min_size == max_size ? min_size : min_size..max_size
+        fail! :too_many_operands, operation: operation, expected: expected, actual: output_size
       end
 
       args = []
-      if operator == AST::Array && output.empty?
+      if operation == AST::Array && output.empty?
         # special case: empty array literal '{}'
-        output.push(operator.new)
+        output.push(operation.new)
       else
         fail! :invalid_statement if output_size < args_size
         args = Array.new(args_size) { output.pop }.reverse
-        output.push operator.new(*args)
+        output.push operation.new(*args)
       end
 
-      if operator.respond_to?(:callback) && !operator.callback.nil?
-        operator.callback.call(args)
+      if operation.respond_to?(:callback) && !operation.callback.nil?
+        operation.callback.call(args)
       end
     rescue ::ArgumentError => e
-      raise Dentaku::ArgumentError, e.message
+      raise if e.is_a?(Dentaku::ArgumentError)
+      raise Dentaku::ArgumentError.for(:invalid_value), e.message
     rescue NodeError => e
-      fail! :node_invalid, operator: operator, child: e.child, expect: e.expect, actual: e.actual
+      raise ParseError.for(:node_invalid, operation: operation, operand: e.operand, expected: e.expected, actual: e.actual), e.message
     end
 
     def parse
@@ -190,8 +191,11 @@ module Dentaku
           operations.push(AST::CaseConditional)
           consume(2)
           arities[-1] += 1
-        elsif operations.last == AST::Case
-          # First WHEN: finalize switch variable expression.
+        elsif operations[token_index].nil? ||
+              (operations[token_index] != AST::CaseWhen && operations[token_index] < AST::Operation)
+          # First WHEN: fold any operators pending from an unparenthesized
+          # switch expression, then finalize the switch variable.
+          consume_until(AST::Case)
           operations.push(AST::CaseSwitchVariable)
           consume
         end
@@ -268,7 +272,7 @@ module Dentaku
       when :close
         consume while operations.any? && operations.last != AST::Grouping
         lparen = operations.pop
-        fail! :unbalanced_parenthesis, token unless lparen == AST::Grouping
+        fail! :unbalanced_parenthesis, token: token unless lparen == AST::Grouping
         if operations.last && operations.last < AST::Function
           consume(arities.pop.succ)
         end
@@ -284,35 +288,7 @@ module Dentaku
     end
 
     def fail!(reason, **meta)
-      message =
-        case reason
-        when :node_invalid
-          "#{meta.fetch(:operator)} requires #{meta.fetch(:expect).join(', ')} operands, but got #{meta.fetch(:actual)}"
-        when :too_few_operands
-          "#{meta.fetch(:operator)} has too few operands (given #{meta.fetch(:actual)}, expected #{meta.fetch(:expect)})"
-        when :too_many_operands
-          "#{meta.fetch(:operator)} has too many operands (given #{meta.fetch(:actual)}, expected #{meta.fetch(:expect)})"
-        when :undefined_function
-          "Undefined function #{meta.fetch(:function_name)}"
-        when :unprocessed_token
-          "Unprocessed token #{meta.fetch(:token_name)}"
-        when :unknown_case_token
-          "Unknown case token #{meta.fetch(:token_name)}"
-        when :unbalanced_bracket
-          "Unbalanced bracket"
-        when :unbalanced_parenthesis
-          "Unbalanced parenthesis"
-        when :unknown_grouping_token
-          "Unknown grouping token #{meta.fetch(:token_name)}"
-        when :not_implemented_token_category
-          "Not implemented for tokens of category #{meta.fetch(:token_category)}"
-        when :invalid_statement
-          "Invalid statement"
-        else
-          raise ::ArgumentError, "Unhandled #{reason}"
-        end
-
-      raise ParseError.for(reason, **meta), message
+      raise ParseError.for(reason, **meta)
     end
   end
 end

data/lib/dentaku/print_visitor.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: false
 module Dentaku
   class PrintVisitor
     def initialize(node)

data/lib/dentaku/token_matcher.rb

@@ -93,46 +93,40 @@ module Dentaku
       @values.empty? || @values.key?(value)
     end
 
-    def self.datetime;       new(:datetime);                       end
-    def self.numeric;        new(:numeric);                        end
-    def self.string;         new(:string);                         end
-    def self.logical;        new(:logical);                        end
+    def self.datetime = new(:datetime)
+    def self.numeric = new(:numeric)
+    def self.string = new(:string)
+    def self.logical = new(:logical)
     def self.value
       new(:datetime) | new(:numeric) | new(:string) | new(:logical)
     end
 
-    def self.addsub;         new(:operator, [:add, :subtract]);    end
-    def self.subtract;       new(:operator, :subtract);            end
-    def self.anchored_minus; new(:operator, :subtract).caret;      end
-    def self.muldiv;         new(:operator, [:multiply, :divide]); end
-    def self.pow;            new(:operator, :pow);                 end
-    def self.mod;            new(:operator, :mod);                 end
-    def self.combinator;     new(:combinator);                     end
-
-    def self.comparator;     new(:comparator);                     end
-    def self.comp_gt;        new(:comparator, [:gt, :ge]);         end
-    def self.comp_lt;        new(:comparator, [:lt, :le]);         end
-
-    def self.open;           new(:grouping, :open);                end
-    def self.close;          new(:grouping, :close);               end
-    def self.comma;          new(:grouping, :comma);               end
-    def self.non_group;      new(:grouping).invert;                end
-    def self.non_group_star; new(:grouping).invert.star;           end
-    def self.non_close_plus; new(:grouping, :close).invert.plus;   end
-    def self.arguments;      (value | comma).plus;                 end
-
-    def self.if;             new(:function, :if);                  end
-    def self.round;          new(:function, :round);               end
-    def self.roundup;        new(:function, :roundup);             end
-    def self.rounddown;      new(:function, :rounddown);           end
-    def self.not;            new(:function, :not);                 end
-
-    def self.method_missing(name, *args, &block)
-      new(:function, name)
-    end
-
-    def self.respond_to_missing?(name, include_priv)
-      true
-    end
+    def self.addsub = new(:operator, [:add, :subtract])
+    def self.subtract = new(:operator, :subtract)
+    def self.anchored_minus = new(:operator, :subtract).caret
+    def self.muldiv = new(:operator, [:multiply, :divide])
+    def self.pow = new(:operator, :pow)
+    def self.mod = new(:operator, :mod)
+    def self.combinator = new(:combinator)
+
+    def self.comparator = new(:comparator)
+    def self.comp_gt = new(:comparator, [:gt, :ge])
+    def self.comp_lt = new(:comparator, [:lt, :le])
+
+    def self.open = new(:grouping, :open)
+    def self.close = new(:grouping, :close)
+    def self.comma = new(:grouping, :comma)
+    def self.non_group = new(:grouping).invert
+    def self.non_group_star = new(:grouping).invert.star
+    def self.non_close_plus = new(:grouping, :close).invert.plus
+    def self.arguments = (value | comma).plus
+
+    def self.function(name) = new(:function, name)
+
+    def self.if = function(:if)
+    def self.round = function(:round)
+    def self.roundup = function(:roundup)
+    def self.rounddown = function(:rounddown)
+    def self.not = function(:not)
   end
 end

data/lib/dentaku/token_matchers.rb

@@ -6,7 +6,7 @@ module Dentaku
 
     def self.function_token_matchers(function_name, *symbols)
       token_matchers(:open, *symbols, :close).unshift(
-        TokenMatcher.send(function_name)
+        TokenMatcher.function(function_name)
       )
     end
 
@@ -16,9 +16,9 @@ module Dentaku
         :comparator, :comp_gt, :comp_lt, :open, :close, :comma,
         :non_close_plus, :non_group, :non_group_star, :arguments,
         :logical, :combinator, :if, :round, :roundup, :rounddown, :not,
-        :anchored_minus, :math_neg_pow, :math_neg_mul
+        :anchored_minus
       ].each_with_object({}) do |name, matchers|
-        matchers[name] = TokenMatcher.send(name)
+        matchers[name] = TokenMatcher.public_send(name)
       end
 
       @matchers.fetch(symbol) do

data/lib/dentaku/token_scanner.rb

@@ -2,6 +2,7 @@ require 'bigdecimal'
 require 'time'
 require 'dentaku/string_casing'
 require 'dentaku/token'
+require 'dentaku/numeric_parser'
 
 module Dentaku
   class TokenScanner
@@ -95,13 +96,11 @@ module Dentaku
       end
 
       def numeric
-        new(:numeric, '((?:\d+(\.\d+)?|\.\d+)(?:(e|E)(\+|-)?\d+)?)\b', lambda { |raw|
-          raw =~ /(\.|e|E)/ ? BigDecimal(raw) : raw.to_i
-        })
+        new(:numeric, NumericParser::NUMERIC_PATTERN, lambda { |raw| NumericParser.parse_numeric_string(raw) })
       end
 
       def hexadecimal
-        new(:numeric, '(0x[0-9a-f]+)\b', lambda { |raw| raw[2..-1].to_i(16) })
+        new(:numeric, NumericParser::HEXADECIMAL_PATTERN, lambda { |raw| NumericParser.parse_hexadecimal_string(raw) })
       end
 
       def double_quoted_string