plurimath 0.11.1 → 0.11.3

data/lib/plurimath/math/core.rb

@@ -353,6 +353,58 @@ namespace: "m")
         false
       end
 
+      def plus_operator?
+        false
+      end
+
+      def minus_operator?
+        false
+      end
+
+      def multiply_operator?
+        false
+      end
+
+      def divide_operator?
+        false
+      end
+
+      def power_operator?
+        false
+      end
+
+      def operator?
+        plus_operator? || minus_operator? || multiply_operator? ||
+          divide_operator? || power_operator?
+      end
+
+      def reserved_constant
+        nil
+      end
+
+      # Default evaluation entry point: a node that does not implement a
+      # numeric evaluation raises UnsupportedExpressionError. Concrete nodes
+      # (Number, Symbol operators, Function::*) override this.
+      def evaluate(evaluator)
+        evaluator.unsupported(self)
+      end
+
+      def open?
+        false
+      end
+
+      def close?
+        false
+      end
+
+      # The bound variable a node represents, or nil if it is not a plain
+      # variable. Symbols and text nodes that name a variable override this;
+      # it lets iteration indexes accept both `Symbols::Symbol` (AsciiMath/
+      # MathML) and `Function::Text` (OMML) without type-sniffing.
+      def variable_name
+        nil
+      end
+
       def unicodemath_parens(field, options:)
         paren = field.to_unicodemath(options: options)
         return paren if field.is_a?(Math::Function::Fenced)

data/lib/plurimath/math/evaluation/evaluator.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Math
+    module Evaluation
+      # Computes the numeric value of a Formula tree against variable
+      # bindings, enforcing the strict error contract: results are always
+      # real, finite numbers or one of the Errors::Evaluation classes is
+      # raised.
+      class Evaluator
+        def initialize(formula, bindings = {})
+          @formula = formula
+          @bindings = normalize_bindings(bindings)
+        end
+
+        def evaluate
+          result = begin
+            evaluate_formula(@formula)
+          rescue ::Math::DomainError => e
+            raise Errors::Evaluation::MathDomainError, e.message
+          rescue ::FloatDomainError
+            raise Errors::Evaluation::NonFiniteResultError
+          rescue ::ZeroDivisionError
+            raise Errors::Evaluation::DivisionByZeroError
+          end
+
+          raise Errors::Evaluation::NonFiniteResultError unless result.finite?
+
+          result
+        end
+
+        def evaluate_formula(formula)
+          real_result(ExpressionParser.new(self, formula.value).parse)
+        end
+
+        def evaluate_nodes(nodes)
+          evaluate_formula(Formula.new(Array(nodes)))
+        end
+
+        def evaluate_node(node)
+          case node
+          when nil
+            unsupported("missing operand")
+          when Formula
+            evaluate_formula(node)
+          else
+            real_result(node.evaluate(self))
+          end
+        end
+
+        def value_for(name)
+          raise Errors::Evaluation::MissingVariableError, name unless bindings.key?(name)
+
+          bindings[name]
+        end
+
+        def divide(dividend, divisor)
+          raise Errors::Evaluation::DivisionByZeroError if divisor.zero?
+
+          dividend / divisor.to_f
+        end
+
+        def modulo(dividend, divisor)
+          raise Errors::Evaluation::DivisionByZeroError if divisor.zero?
+
+          dividend % divisor
+        end
+
+        def power(base, exponent)
+          real_result(base**exponent)
+        end
+
+        # Non-real values are rejected per subexpression so they cannot reach
+        # other numeric operations. Non-finite values are only rejected on the
+        # final result, so correct asymptotic values like `1/exp(1000)` still
+        # evaluate.
+        def real_result(value)
+          raise Errors::Evaluation::MathDomainError, "result is not a real number" unless value.real?
+
+          value
+        end
+
+        # Comma-separated argument lists for functions like `max(2,3)`.
+        def evaluate_arguments(nodes)
+          split_on_commas(Array(nodes)).map { |segment| evaluate_nodes(segment) }
+        end
+
+        def function_arguments(node)
+          return evaluate_arguments(node.parameter_two) if node.is_a?(Function::Fenced)
+
+          evaluate_arguments(Array(node))
+        end
+
+        # Temporarily binds an iteration index, shadowing any outer binding
+        # of the same name and restoring it afterwards.
+        def with_binding(name, value)
+          had_key = bindings.key?(name)
+          previous = bindings[name]
+          bindings[name] = value
+          yield
+        ensure
+          had_key ? bindings[name] = previous : bindings.delete(name)
+        end
+
+        def unsupported(node_or_message)
+          raise Errors::Evaluation::UnsupportedExpressionError, unsupported_message(node_or_message)
+        end
+
+        private
+
+        attr_reader :bindings
+
+        def normalize_bindings(bindings)
+          bindings.to_hash.each_with_object({}) do |(key, value), normalized|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise Errors::Evaluation::InvalidBindingKeyError, key
+            end
+            unless value.is_a?(Numeric) && value.real?
+              raise Errors::Evaluation::InvalidBindingError.new(key, value)
+            end
+
+            normalized[key.to_s] = value
+          end
+        end
+
+        def split_on_commas(nodes)
+          nodes.each_with_object([[]]) do |node, segments|
+            node.is_a?(Symbols::Comma) ? segments << [] : segments.last << node
+          end
+        end
+
+        def unsupported_message(node_or_message)
+          return node_or_message if node_or_message.is_a?(String)
+          return "equation" if node_or_message.is_a?(Symbols::Equal)
+          return "number `#{node_or_message.value}`" if node_or_message.is_a?(Number)
+
+          if node_or_message.instance_of?(Symbols::Symbol) &&
+              node_or_message.value.to_s != ""
+            return "symbol `#{node_or_message.value}`"
+          end
+
+          node_or_message.class.name.sub(/^Plurimath::Math::/, "")
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/math/evaluation/expression_parser.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Math
+    module Evaluation
+      # Resolves operator precedence over the flat token sequences stored in
+      # Formula#value, delegating node evaluation back to the evaluator.
+      #
+      # Standard recursive-descent precedence ladder — each level parses its
+      # operands at the next-tighter level, so the operands of `+`/`-` are
+      # whole multiplicative expressions, and so on down to single operands:
+      #   parse_additive -> parse_multiplicative -> parse_unary
+      #     -> parse_power -> parse_operand
+      class ExpressionParser
+        def initialize(evaluator, tokens)
+          @evaluator = evaluator
+          @tokens = tokens
+          @index = 0
+        end
+
+        def parse
+          result = parse_additive
+          evaluator.unsupported(current) unless eof?
+
+          result
+        end
+
+        private
+
+        attr_reader :evaluator, :tokens
+
+        def parse_additive
+          result = parse_multiplicative
+          loop do
+            if take?(:plus_operator?)
+              result += parse_multiplicative
+            elsif take?(:minus_operator?)
+              result -= parse_multiplicative
+            else
+              break result
+            end
+          end
+        end
+
+        def parse_multiplicative
+          result = parse_unary
+          loop do
+            if take?(:multiply_operator?)
+              result *= parse_unary
+            elsif take?(:divide_operator?)
+              result = evaluator.divide(result, parse_unary)
+            elsif implicit_multiplication?
+              result *= parse_power
+            else
+              break result
+            end
+          end
+        end
+
+        def parse_unary
+          if take?(:plus_operator?)
+            parse_unary
+          elsif take?(:minus_operator?)
+            negated_unary
+          else
+            parse_power
+          end
+        end
+
+        # Unary minus binds tighter than `mod`, so `-7 mod 3` negates the
+        # dividend, not the result: `(-7) mod 3 == 2`, not `-(7 mod 3)`.
+        def negated_unary
+          return next_token.evaluate_negated(evaluator) if current.is_a?(Function::Mod)
+
+          -parse_unary
+        end
+
+        # Chained powers evaluate left-to-right, matching the left-nested
+        # trees parsers build for chains like `2^3^2`.
+        def parse_power
+          result = parse_operand
+          result = evaluator.power(result, parse_exponent) while take?(:power_operator?)
+          result
+        end
+
+        def parse_exponent
+          if take?(:plus_operator?)
+            parse_exponent
+          elsif take?(:minus_operator?)
+            negated_exponent
+          else
+            parse_operand
+          end
+        end
+
+        def negated_exponent
+          return next_token.evaluate_negated(evaluator) if current.is_a?(Function::Mod)
+
+          -parse_exponent
+        end
+
+        def parse_operand
+          evaluator.unsupported("empty expression") if eof?
+          return parse_group if open_paren?(current)
+
+          node = next_token
+          return bind_argument(node) if next_argument?(node)
+          return bind_log_argument(node) if log_argument?(node)
+
+          node = bind_nary_body(node) if nary_body?(node)
+          evaluator.evaluate_node(node)
+        end
+
+        # A non-close token before the close paren is reported as itself;
+        # "unmatched parenthesis" is reserved for true end-of-input.
+        def parse_group
+          advance
+          result = parse_additive
+          evaluator.unsupported(current || "unmatched parenthesis") unless close_paren?(current)
+
+          advance
+          result
+        end
+
+        # Unary functions and `log` parse separately from their argument in
+        # some syntaxes; both bind the following fenced group.
+        def next_argument?(node)
+          node.is_a?(Function::UnaryFunction) && node.parameter_one.nil? &&
+            current.is_a?(Function::Fenced)
+        end
+
+        def bind_argument(node)
+          evaluator.evaluate_node(node.class.new(next_token))
+        end
+
+        # MathML/OMML n-ary Sum/Prod carry their bounds but leave the body as
+        # the following sibling token; AsciiMath binds a single operand as the
+        # body, so we match by adopting the next operand as parameter_three.
+        def nary_body?(node)
+          (node.is_a?(Function::Sum) || node.is_a?(Function::Prod)) &&
+            node.parameter_three.nil? &&
+            node.parameter_one && node.parameter_two &&
+            !eof? && operand_start?(current)
+        end
+
+        # The body is a single following operand; if that operand is itself a
+        # sibling-body Sum/Prod (e.g. nested MathML `sum sum …`), complete it
+        # recursively so the inner body binds too.
+        def bind_nary_body(node)
+          body = next_token
+          body = bind_nary_body(body) if nary_body?(body)
+          node.class.new(node.parameter_one, node.parameter_two, body)
+        end
+
+        def log_argument?(node)
+          node.is_a?(Function::Log) && current.is_a?(Function::Fenced)
+        end
+
+        def bind_log_argument(node)
+          evaluator.real_result(node.evaluate_with_argument(evaluator, next_token))
+        end
+
+        # Adjacent operands multiply by juxtaposition (`2a`, `2(a+b)`), except
+        # two adjacent numeric literals, which usually indicate a split number
+        # literal. Signs are never consumed implicitly.
+        def implicit_multiplication?
+          operand_start?(current) &&
+            !(current.is_a?(Number) && tokens[@index - 1].is_a?(Number))
+        end
+
+        def operand_start?(node)
+          return false if node.nil? || node.operator?
+
+          !close_paren?(node)
+        end
+
+        def take?(predicate)
+          return false if eof? || !current.public_send(predicate)
+
+          advance
+          true
+        end
+
+        def next_token
+          token = current
+          advance
+          token
+        end
+
+        def open_paren?(node)
+          node&.open?
+        end
+
+        def close_paren?(node)
+          node&.close?
+        end
+
+        def current
+          token = tokens[@index]
+          evaluator.unsupported("malformed token") unless token.nil? || token.is_a?(Core)
+
+          token
+        end
+
+        def advance
+          @index += 1
+        end
+
+        def eof?
+          @index >= tokens.length
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/math/evaluation/iteration.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Math
+    module Evaluation
+      # Evaluates bounded Sum/Prod iterations: parses the `i=1` lower bound,
+      # validates the integer bounds and step limit, then folds the body with
+      # the index temporarily bound.
+      class Iteration
+        def initialize(evaluator, lower, upper, body)
+          @evaluator = evaluator
+          @lower = lower
+          @upper = upper
+          @body = body
+        end
+
+        def accumulate(initial, operation)
+          name, from = index_definition
+          to = evaluator.evaluate_node(upper)
+          validate_bounds(from, to)
+
+          (from..to).reduce(initial) do |accumulator, index|
+            accumulator.public_send(operation, body_value(name, index))
+          end
+        end
+
+        private
+
+        attr_reader :evaluator, :lower, :upper, :body
+
+        # Parses `i=1` style lower bounds into the index name and its start.
+        def index_definition
+          tokens = lower.is_a?(Formula) ? lower.value : Array(lower)
+          index = tokens.first
+          if index.is_a?(Core) && index.reserved_constant
+            evaluator.unsupported("reserved constant as iteration index")
+          end
+          name = index.is_a?(Core) ? index.variable_name : nil
+          unless name && tokens[1].is_a?(Symbols::Equal)
+            evaluator.unsupported("malformed iteration bounds")
+          end
+
+          [name, evaluator.evaluate_nodes(tokens[2..])]
+        end
+
+        def validate_bounds(from, to)
+          unless from.is_a?(Integer) && to.is_a?(Integer)
+            raise Errors::Evaluation::MathDomainError, "iteration bounds must be integers"
+          end
+
+          limit = Plurimath.configuration.evaluation_max_iterations
+          return if limit.nil? || (to - from + 1) <= limit
+
+          evaluator.unsupported("iteration range larger than #{limit} steps")
+        end
+
+        def body_value(name, index)
+          evaluator.with_binding(name, index) { evaluator.evaluate_node(body) }
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/math/evaluation.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "plurimath/errors/evaluation"
+
+module Plurimath
+  module Math
+    module Evaluation
+      autoload :Evaluator, "#{__dir__}/evaluation/evaluator"
+      autoload :ExpressionParser, "#{__dir__}/evaluation/expression_parser"
+      autoload :Iteration, "#{__dir__}/evaluation/iteration"
+    end
+  end
+end

data/lib/plurimath/math/formula.rb

@@ -54,6 +54,15 @@ module Plurimath
           object.left_right_wrapper == left_right_wrapper
       end
 
+      def evaluate(bindings = {})
+        hash = bindings.to_hash if bindings.respond_to?(:to_hash)
+        unless hash.is_a?(Hash)
+          raise ArgumentError, "bindings must be a Hash-like object"
+        end
+
+        Evaluation::Evaluator.new(self, hash).evaluate
+      end
+
       def to_asciimath(formatter: nil, unitsml: {}, options: nil)
         options ||= { formatter: formatter, unitsml: unitsml }.compact
         options[:formula] ||= self

data/lib/plurimath/math/function/abs.rb

@@ -39,6 +39,10 @@ module Plurimath
           "⒜#{unicodemath_parens(parameter_one, options: options)}"
         end
 
+        def evaluate(evaluator)
+          evaluator.evaluate_node(parameter_one).abs
+        end
+
         def intent_names
           { name: "absolute-value" }
         end

data/lib/plurimath/math/function/arccos.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          ::Math.acos(evaluator.evaluate_node(parameter_one))
+        end
       end
     end
   end

data/lib/plurimath/math/function/arcsin.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          ::Math.asin(evaluator.evaluate_node(parameter_one))
+        end
       end
     end
   end

data/lib/plurimath/math/function/arctan.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          ::Math.atan(evaluator.evaluate_node(parameter_one))
+        end
       end
     end
   end

data/lib/plurimath/math/function/ceil.rb

@@ -39,6 +39,10 @@ module Plurimath
           "#{first_value}#{parameter_one&.to_unicodemath(options: options)}#{second_value}"
         end
 
+        def evaluate(evaluator)
+          evaluator.evaluate_node(parameter_one).ceil
+        end
+
         def line_breaking(obj)
           parameter_one.line_breaking(obj)
           if obj.value_exist?

data/lib/plurimath/math/function/cos.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          ::Math.cos(evaluator.evaluate_node(parameter_one))
+        end
       end
     end
   end

data/lib/plurimath/math/function/cosh.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          ::Math.cosh(evaluator.evaluate_node(parameter_one))
+        end
       end
     end
   end

data/lib/plurimath/math/function/cot.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          evaluator.divide(1.0, ::Math.tan(evaluator.evaluate_node(parameter_one)))
+        end
       end
     end
   end

data/lib/plurimath/math/function/coth.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          evaluator.divide(1.0, ::Math.tanh(evaluator.evaluate_node(parameter_one)))
+        end
       end
     end
   end

data/lib/plurimath/math/function/csc.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          evaluator.divide(1.0, ::Math.sin(evaluator.evaluate_node(parameter_one)))
+        end
       end
     end
   end

data/lib/plurimath/math/function/csch.rb

@@ -7,6 +7,10 @@ module Plurimath
         def validate_function_formula
           false
         end
+
+        def evaluate(evaluator)
+          evaluator.divide(1.0, ::Math.sinh(evaluator.evaluate_node(parameter_one)))
+        end
       end
     end
   end

data/lib/plurimath/math/function/exp.rb

@@ -8,6 +8,10 @@ module Plurimath
           false
         end
 
+        def evaluate(evaluator)
+          ::Math.exp(evaluator.evaluate_node(parameter_one))
+        end
+
         def to_omml_without_math_tag(display_style, options:)
           array = []
           array << r_element("exp", rpr_tag: false) unless hide_function_name

data/lib/plurimath/math/function/fenced.rb

@@ -116,6 +116,10 @@ module Plurimath
           "#{unicode_open_paren(options: options)}#{fenced_value}#{unicode_close_paren(options: options)}"
         end
 
+        def evaluate(evaluator)
+          evaluator.evaluate_nodes(parameter_two)
+        end
+
         def to_asciimath_math_zone(spacing, last = false, indent = true,
 options:)
           filtered_values(parameter_two,

data/lib/plurimath/math/function/floor.rb

@@ -36,6 +36,10 @@ module Plurimath
           "#{first_value}#{parameter_one&.to_unicodemath(options: options)}#{second_value}"
         end
 
+        def evaluate(evaluator)
+          evaluator.evaluate_node(parameter_one).floor
+        end
+
         def line_breaking(obj)
           parameter_one.line_breaking(obj)
           if obj.value_exist?