dentaku 3.5.8 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d84ad3261b937673547d328aae718b0a7389bca75b6aedaaa8b82dff2c1f9f9
-  data.tar.gz: 5f6e809c2a510e2d32a07ed0838ad878dd46bb9e475e73626dced73f219280c8
+  metadata.gz: a911d2d58c12144c0692b27a9abe5ad08716e1800deb9e9bda08bee04735b9ac
+  data.tar.gz: 8e55f39625ebb6a6a5f4d38b820137566c9bd2d529d411cb4c40c89770dbf048
 SHA512:
-  metadata.gz: e939d79f7b4defcc2596b2a83fe612fbebf298cdb2b3a38b0cd7978ef8bdabeab6321e2b381ad9de83d28cd10bd807eabd4af1c8d095446ffca3c7515cbfe015
-  data.tar.gz: 390db232aa4a54ca779e0ddfe762cfbf9b5279c60731809ca6a5d59013ef3f3d161c298dd315daae4beeb7c5a51f4285e29b5f48d241f77d33d63e7787a2f91b
+  metadata.gz: ac372c840c68d33bb1a6577640ea17812e0aab7b1f82c1979d1caac5ef670148743ecc77f87c8cf32a33e5e90d6f9f35f5d6da85da3e345beb64cf0a0d7d2b78
+  data.tar.gz: 4d9d05f5b7a79751cfc4f82576b6bddd5d621e02df4ee98282052d55cbe87c250d5f0906960726278ee078d9162f369a9efd42f166d7446d189aeb80de7c166d

data/.github/workflows/rspec.yml

@@ -8,12 +8,10 @@ jobs:
     strategy:
       matrix:
         ruby:
-        - '3.0'
-        - '3.1'
-        - '3.2'
+        - '3.2' # minimum supported Ruby
         - '3.3'
         - '3.4'
-        - '4.0'
+        - '4.0' # future compatibility signal
       fail-fast: false
     steps:
     - uses: actions/checkout@v4

data/.github/workflows/rubocop.yml

@@ -9,6 +9,6 @@ jobs:
     - uses: actions/checkout@v4
     - uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3'
+        ruby-version: '3.2'
         bundler-cache: true
     - run: bundle exec rubocop

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.2
   # RuboCop has a bunch of cops enabled by default. This setting tells RuboCop
   # to ignore them, so only the ones explicitly set in this file are enabled.
   DisabledByDefault: true

data/CHANGELOG.md

@@ -1,6 +1,79 @@
 # Change Log
 
-## [UNRELEASED]
+## [v4.0.0] 2026-08-01
+BREAKING CHANGES
+- require Ruby 3.2 or newer
+- `Calculator.new` takes keyword arguments; the AST cache must now be passed
+  explicitly via `ast_cache:` instead of as leftover options, unknown options
+  raise `ArgumentError`, and the passed values are no longer mutated
+- `Dentaku::Error` is now a module included by all Dentaku exceptions, so
+  `rescue Dentaku::Error` also catches `Dentaku::ArgumentError` and
+  `Dentaku::ZeroDivisionError`; exceptions that previously subclassed
+  `Dentaku::Error` now subclass `Dentaku::BaseError`
+- unify exception metadata naming: the "required vs. received" pair is now
+  `expected:` / `actual:` everywhere (previously a mix of `expect:`/`actual:`,
+  `for:`/`value:`, `at_least:`/`given:`, and `exact:`/`given:`); arity
+  expectations are an Integer or Range (`expected: 1..` means "at least one")
+  and `actual:` always carries the offending value itself, not its class
+- `meta[:operation]` is now always the AST class and `meta[:operator]` the
+  method symbol (previously `ParseError` used `:operator` for the class);
+  `NodeError#child` is renamed to `#operand` (it holds the failing operand's
+  position, `:left` / `:right` / `:node`) and `NodeError#expect` to `#expected`;
+  `function_name:` metadata carries bare names (`'AND'`, not `'AND()'`)
+- `Dentaku::Error#recipient_variable` is renamed to `#assigned_to`
+- bitwise operations on non-integer operands raise `:incompatible_type`
+  (previously `:invalid_operator`) with a descriptive message instead of a
+  bare "Dentaku::ArgumentError"
+- indexing into a non-indexable value (e.g. `a[0]` where `a` is a number,
+  `NULL`, or a boolean) now raises `Dentaku::ArgumentError` instead of
+  silently returning a bit-reference result or leaking a raw Ruby
+  `NoMethodError`; an incompatible index type (e.g. a string index into an
+  array) raises `Dentaku::ArgumentError` instead of a raw `TypeError`
+- `AND` / `OR` short-circuit: an unbound variable no longer raises when the
+  bound operand already decides the result (#234); formulas are documented
+  as pure, and misspelled identifiers on never-taken branches are no longer
+  reported at evaluation time (use `dependencies` for static validation)
+- `TokenMatcher` no longer builds function matchers via `method_missing`; use
+  `TokenMatcher.function(name)` (the unused `math_neg_pow` / `math_neg_mul`
+  matcher symbols were removed)
+
+OTHER CHANGES
+- add `volatile:` option to `add_function` / `add_functions` / function
+  registration for functions that read external state or return different
+  values across calls; volatile functions are never executed during
+  dependency analysis, so a conditional guarded by one reports all branches
+  as dependencies (and `evaluate!` requires variables from every branch),
+  and the guard is evaluated exactly once per `evaluate!` instead of twice
+  (#339, thanks @d-krushinsky)
+- add `Calculator#identifiers`, a purely syntactic listing of every
+  identifier a formula could reference regardless of branching -- nothing
+  is evaluated and stored variables are not subtracted (#197, #339)
+- cache flags can be set per calculator (`cache_ast:`,
+  `cache_dependency_order:`), defaulting to the module-level settings
+- module-level `Dentaku.aliases` is resolved lazily, so aliases set after a
+  calculator was created (including the implicit top-level calculator) apply
+- `CASE` expressions only report dependencies for the branch that would be
+  taken when the switch value is resolvable
+- operand type-mismatch parse errors now read as natural English: the parser
+  preserves the node-level message ("Dentaku::AST::Addition requires operands
+  that are numeric or compatible types, not string") instead of rebuilding a
+  misleading one ("requires incompatible operands, but got string"); the
+  metadata-derived fallback message says "compatible" rather than
+  "incompatible" (idea from #341, thanks @moskvin)
+- `Dentaku::ArgumentError`, `ParseError`, and `TokenizerError` build their own
+  default messages from `reason` and `meta` (existing message text is
+  unchanged); `Parser#fail!` and `Tokenizer#fail!` reduce to one-liners
+- fix parsing of `CASE` statements with an unparenthesized operation as the
+  switch expression (`CASE a % 5 WHEN ...`), which also makes `PrintVisitor`
+  output for such statements re-parseable
+- fix `recipient_variable` being nil inside `solve` blocks, a regression
+  introduced in 3.5.4 (#333)
+- fix crashes on two error paths: the parser's unbalanced-parenthesis report
+  raised a Ruby `ArgumentError` instead of a `ParseError`, and the tokenizer's
+  zero-width-match report raised a `KeyError` instead of a `TokenizerError`
+- document Ruby compatibility policy
+- modernize low-risk Ruby syntax
+- remove Travis CI configuration
 
 ## [v3.5.8] 2026-08-01
 - unify numeric matching and parsing

data/Gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in dentaku.gemspec
 gemspec

data/README.md

@@ -13,6 +13,16 @@ language that allows run-time binding of values to variables referenced in the
 formulas.  It is intended to safely evaluate untrusted expressions without
 opening security holes.
 
+COMPATIBILITY
+-------------
+
+Dentaku supports Ruby 3.2 and newer, tracking Ruby's own maintenance policy:
+when a Ruby version reaches end-of-life, it may be dropped from the supported
+compatibility contract in the next major or minor release. Older Rubies may
+continue to work, but are not tested.
+
+New code should target the lowest supported Ruby version, currently Ruby 3.2.
+
 EXAMPLE
 -------
 
@@ -124,6 +134,13 @@ phases, so if performance is a concern, you can enable AST caching:
 Dentaku.enable_ast_cache!
 ```
 
+Caching can also be controlled per calculator, overriding the module-level
+setting:
+
+```ruby
+calculator = Dentaku::Calculator.new(cache_ast: true)
+```
+
 After this, Dentaku will cache the AST of each formula that it evaluates, so
 subsequent evaluations (even with different values for variables) will be much
 faster -- closer to 4x native Ruby speed.  As usual, these benchmarks should be
@@ -131,6 +148,57 @@ considered rough estimates, and you should measure with representative formulas
 from your application.  Also, if new formulas are constantly introduced to your
 application, AST caching will consume more memory with each new formula.
 
+DEPENDENCY ANALYSIS AND SHORT-CIRCUITING
+----------------------------------------
+
+Dentaku treats formulas as pure: a subexpression may be evaluated zero, one,
+or more than one time (for example, a guard position may be evaluated once
+during dependency analysis and again during evaluation), so custom functions
+should not rely on side effects or call counts.  Functions that fall outside
+this contract -- reading external state, performing I/O, or returning
+different values across calls -- must be registered with `volatile: true`
+(see EXTERNAL FUNCTIONS below).  Volatile functions are never invoked during
+dependency analysis; in guard positions this means no branch can be pruned,
+so all branches count as dependencies and `evaluate!` requires variables
+from every branch to be bound.
+
+Logical constructs short-circuit.  `IF` and `CASE` only evaluate the branch
+that is taken, and `AND` / `OR` resolve as soon as one operand decides the
+result.  An unbound variable raises `Dentaku::UnboundVariableError` only when
+its value is actually needed:
+
+```ruby
+calculator.evaluate!('a OR b', a: true)   #=> true
+calculator.evaluate!('a OR b', a: false)  #=> raises Dentaku::UnboundVariableError
+```
+
+Two methods answer two different questions about a formula's inputs:
+
+`calculator.dependencies(expression, context)` reports the identifiers a
+formula still needs, given what is already known.  It is resolution-aware:
+guard positions (`IF` predicates, `CASE` switches, `AND` / `OR` operands)
+whose own dependencies are already satisfied are evaluated -- executing any
+(non-volatile) functions they contain -- in order to prune branches that
+cannot be taken.
+
+`calculator.identifiers(expression)` reports every identifier the formula
+could ever reference, regardless of branching.  It is purely syntactic:
+nothing is evaluated, no functions run (volatile or not), and stored
+variables are not subtracted.  Use it to statically list a formula's
+possible inputs, e.g. to tell users what values they may need to supply.
+
+```ruby
+calculator.dependencies('IF(x > 5, y, z)', x: 7)  #=> ["y"]
+calculator.identifiers('IF(x > 5, y, z)')         #=> ["x", "y", "z"]
+```
+
+Because unused operands are never checked at evaluation time, a misspelled
+identifier on a branch that is not taken will not be reported; use
+`identifiers` for static validation.
+
+Context keys prefixed with a double underscore (e.g. `__evaluation_mode`)
+are reserved for internal use.
+
 BUILT-IN OPERATORS AND FUNCTIONS
 ---------------------------------
 
@@ -279,6 +347,25 @@ function)
 Functions can be added individually using Calculator#add_function, or en masse
 using Calculator#add_functions.
 
+Dentaku assumes registered functions are pure (see DEPENDENCY ANALYSIS AND
+SHORT-CIRCUITING above).  A function that reads external state, performs
+I/O, or returns different values across calls must be declared volatile so
+that dependency analysis never executes it:
+
+```ruby
+> c = Dentaku::Calculator.new
+> c.add_function(:user_level, :numeric, -> { Current.user.level }, volatile: true)
+> c.identifiers('IF(user_level() > 50, high_rate, low_rate)')
+#=> ["high_rate", "low_rate"]
+```
+
+A volatile function in a guard position prevents branch pruning: both
+branches count as dependencies, and `evaluate!` requires variables from
+every branch (Dentaku cannot know in advance which branch will be taken).
+The predicate itself is then evaluated exactly once per `evaluate!` call,
+at evaluation time.  In `add_functions`, pass volatility as a fifth tuple
+element: `[:user_level, :numeric, -> { ... }, nil, true]`.
+
 FUNCTION ALIASES
 ----------------
 

data/dentaku.gemspec

@@ -1,25 +1,32 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "dentaku/version"
+require_relative "lib/dentaku/version"
 
 Gem::Specification.new do |s|
   s.name        = "dentaku"
   s.version     = Dentaku::VERSION
   s.authors     = ["Solomon White"]
   s.email       = ["rubysolo@gmail.com"]
-  s.homepage    = "http://github.com/rubysolo/dentaku"
+  s.homepage    = "https://github.com/rubysolo/dentaku"
   s.licenses    = %w(MIT)
   s.summary     = 'A formula language parser and evaluator'
   s.description = <<-DESC
     Dentaku is a parser and evaluator for mathematical formulas
   DESC
 
-  s.add_dependency('bigdecimal')
-  s.add_dependency('concurrent-ruby')
-  s.add_dependency('tsort')
+  s.metadata = {
+    "homepage_uri"          => s.homepage,
+    "source_code_uri"       => s.homepage,
+    "changelog_uri"         => "#{s.homepage}/blob/main/CHANGELOG.md",
+    "bug_tracker_uri"       => "#{s.homepage}/issues",
+    "rubygems_mfa_required" => "true",
+  }
+
+  s.add_dependency('bigdecimal', '>= 3.1')
+  s.add_dependency('concurrent-ruby', '~> 1.1')
+  s.add_dependency('tsort', '>= 0.1.1')
+
+  s.required_ruby_version = ">= 3.2"
 
   s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ["lib"]
 end

data/lib/dentaku/ast/access.rb

@@ -1,3 +1,4 @@
+require_relative "../exceptions"
 require_relative "./node"
 
 module Dentaku
@@ -25,7 +26,17 @@ module Dentaku
       def value(context = {})
         structure = @structure.value(context)
         index = @index.value(context)
-        structure[index]
+
+        unless structure.respond_to?(:[]) && !structure.is_a?(::Numeric)
+          raise Dentaku::ArgumentError.for(:incompatible_type, actual: structure),
+                "#{self.class} requires an indexable structure, but got #{structure.class}"
+        end
+
+        begin
+          structure[index]
+        rescue ::TypeError => e
+          raise Dentaku::ArgumentError.for(:incompatible_type, actual: index), e.message
+        end
       end
 
       def dependencies(context = {})
@@ -39,6 +50,12 @@ module Dentaku
       def accept(visitor)
         visitor.visit_access(self)
       end
+
+      private
+
+      def compute_pure?
+        @structure.pure? && @index.pure?
+      end
     end
   end
 end

data/lib/dentaku/ast/arithmetic.rb

@@ -41,7 +41,7 @@ module Dentaku
         l.public_send(operator, r)
       rescue ::TypeError => e
         # Right cannot be converted to a suitable type for left. e.g. [] + 1
-        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
 
       def cast(val)
@@ -97,14 +97,13 @@ module Dentaku
 
       def validate_operation(val)
         unless val.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
       end
 
       def validate_format(string)
         unless Dentaku::NumericParser.match(string)
-          raise Dentaku::ArgumentError.for(:invalid_value, value: string, for: BigDecimal),
+          raise Dentaku::ArgumentError.for(:invalid_value, actual: string, expected: BigDecimal),
                 "String input '#{string}' is not coercible to numeric"
         end
       end

data/lib/dentaku/ast/array.rb

@@ -33,6 +33,12 @@ module Dentaku
       def accept(visitor)
         visitor.visit_array(self)
       end
+
+      private
+
+      def compute_pure?
+        @elements.all?(&:pure?)
+      end
     end
   end
 end

data/lib/dentaku/ast/bitwise.rb

@@ -8,10 +8,12 @@ module Dentaku
         right_value = right.value(context)
 
         left_value.public_send(operator, right_value)
-      rescue NoMethodError => e
-        raise Dentaku::ArgumentError.for(:invalid_operator, value: left_value, for: left_value.class)
-      rescue TypeError => e
-        raise Dentaku::ArgumentError.for(:invalid_operator, value: right_value, for: right_value.class)
+      rescue NoMethodError
+        raise Dentaku::ArgumentError.for(:incompatible_type, actual: left_value, expected: Integer),
+              "#{self.class} requires integer operands, but got #{left_value.class}"
+      rescue TypeError
+        raise Dentaku::ArgumentError.for(:incompatible_type, actual: right_value, expected: Integer),
+              "#{self.class} requires integer operands, but got #{right_value.class}"
       end
     end
 

data/lib/dentaku/ast/case/case_conditional.rb

@@ -33,6 +33,12 @@ module Dentaku
       def accept(visitor)
         visitor.visit_case_conditional(self)
       end
+
+      private
+
+      def compute_pure?
+        @when.pure? && @then.pure?
+      end
     end
   end
 end

data/lib/dentaku/ast/case/case_else.rb

@@ -30,6 +30,12 @@ module Dentaku
       def accept(visitor)
         visitor.visit_else(self)
       end
+
+      private
+
+      def compute_pure?
+        @node.pure?
+      end
     end
   end
 end

data/lib/dentaku/ast/case/case_switch_variable.rb

@@ -30,6 +30,12 @@ module Dentaku
       def accept(visitor)
         visitor.visit_switch(self)
       end
+
+      private
+
+      def compute_pure?
+        @node.pure?
+      end
     end
   end
 end

data/lib/dentaku/ast/case/case_then.rb

@@ -30,6 +30,12 @@ module Dentaku
       def accept(visitor)
         visitor.visit_then(self)
       end
+
+      private
+
+      def compute_pure?
+        @node.pure?
+      end
     end
   end
 end

data/lib/dentaku/ast/case/case_when.rb

@@ -34,6 +34,13 @@ module Dentaku
       def to_s
         'WHEN'
       end
+
+      private
+
+      # bypasses Operation's binary initialize, so left/right are unset
+      def compute_pure?
+        @node.pure?
+      end
     end
   end
 end

data/lib/dentaku/ast/case.rb

@@ -65,10 +65,19 @@ module Dentaku
       end
 
       def dependencies(context = {})
-        # TODO: should short-circuit
-        switch_dependencies(context) +
-        condition_dependencies(context) +
+        return all_dependencies(context) if static_mode?(context) || !prunable?
+
+        switch_value = @switch.value(context)
+
+        @conditions.each do |condition|
+          if condition.when.value(context) == switch_value
+            return condition.then.dependencies(context)
+          end
+        end
+
         else_dependencies(context)
+      rescue Dentaku::Error
+        all_dependencies(context)
       end
 
       def accept(visitor)
@@ -77,6 +86,20 @@ module Dentaku
 
       private
 
+      # pruning evaluates the switch and each when-clause until one matches;
+      # all of them must be side-effect free before we may do that
+      def prunable?
+        return @prunable if defined?(@prunable)
+
+        @prunable = @switch.pure? && @conditions.all? { |condition| condition.when.pure? }
+      end
+
+      def all_dependencies(context)
+        switch_dependencies(context) +
+        condition_dependencies(context) +
+        else_dependencies(context)
+      end
+
       def switch_dependencies(context = {})
         @switch.dependencies(context)
       end
@@ -88,6 +111,10 @@ module Dentaku
       def else_dependencies(context = {})
         @else ? @else.dependencies(context) : []
       end
+
+      def compute_pure?
+        ([@switch] + @conditions + [@else]).compact.all?(&:pure?)
+      end
     end
   end
 end

data/lib/dentaku/ast/combinators.rb

@@ -1,4 +1,5 @@
 require_relative './operation'
+require 'dentaku/exceptions'
 
 module Dentaku
   module AST
@@ -20,11 +21,51 @@ 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
 
       def valid_node?(node)
         node && (node.dependencies.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
 
     class And < Combinator
@@ -32,8 +73,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 +85,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