plurimath 0.11.1 → 0.11.3

data/README.adoc

@@ -286,6 +286,83 @@ formula = Plurimath::Math.parse(omml, :omml)
 ----
 
 
+=== Evaluating formulas
+
+`Plurimath::Math::Formula#evaluate` computes numeric results from supported
+semantic formula trees.
+
+[source,ruby]
+----
+formula = Plurimath::Math.parse("sqrt(a^2+b^2)", :asciimath)
+formula.evaluate(a: 3, b: 4)
+# => 5.0
+----
+
+Variable bindings can use string or symbol keys.
+
+[source,ruby]
+----
+formula = Plurimath::Math.parse("a+b-c*d", :asciimath)
+formula.evaluate("a" => 10, b: 5, c: 2, d: 3)
+# => 9
+----
+
+Evaluation supports numeric literals, variables, addition, subtraction,
+multiplication, division, fractions, powers, grouping, square roots, `pi`,
+roots, absolute values, floor/ceiling, `sin`, `cos`, `tan`, inverse trig,
+reciprocal trig, hyperbolic trig, `ln`, and `exp`. Trigonometric functions use
+radians.
+
+Logarithms evaluate with `ln`, `lg`, and `log` — `log` defaults to base 10,
+`log_b` uses the subscript base (which must be positive and not 1), and a
+superscript such as `log_2^3(8)` raises the result to that power. `mod`,
+`max`, `min`, `gcd`, and `lcm` are supported (`gcd`/`lcm` require integer
+arguments), as are bounded `sum` and `prod` with integer bounds — empty
+ranges follow the standard conventions of `0` for sums and `1` for products,
+and the iteration index shadows any outer binding of the same name. Ranges
+are capped at `Plurimath.configuration.evaluation_max_iterations` (default
+1,000,000) to guard against runaway loops; set it (globally via
+`Plurimath.configure` or scoped via `Plurimath.with_configuration`) to a
+larger value, or to `nil` to remove the cap.
+
+`pi` resolves to the constant from each syntax's pi symbol — `pi` in
+AsciiMath, `\pi` in LaTeX, and the `π` symbol (or `π` entity) in the
+other syntaxes. Plain-text `pi` is treated per syntax: a single bindable
+variable in MathML (`<mi>pi</mi>`) and OMML text runs, but individual
+identifiers (`p*i`) in LaTeX, UnicodeMath, and HTML, which tokenize letters
+one by one.
+
+Implicit multiplication by juxtaposition is supported for adjacent operands,
+so `2a`, `2(a+b)`, `(a+b)(a-b)`, and `pi r^2` multiply. Two adjacent numeric
+literals such as `2 3` raise instead, because that shape usually indicates a
+split number literal.
+
+Chained powers follow the parsed tree structure, so `2^3^2` evaluates as
+`(2^3)^2`; use explicit grouping such as `2^(3^2)` for right association.
+Division uses `Float` arithmetic, and pole detection is exact: `cot(0)` raises
+a division-by-zero error, while `sec(pi/2)` returns a large finite number
+because the floating-point value of `pi/2` is not exactly the pole.
+
+Binding values must be real `Numeric` values. A recognized `pi` constant
+always resolves to its numeric value and cannot be overridden by a binding
+such as `pi: 3`.
+
+Binding keys must be strings or symbols; other key types raise
+`Plurimath::Math::Evaluation::InvalidBindingKeyError`.
+
+Missing variables raise
+`Plurimath::Math::Evaluation::MissingVariableError`. Binding values that are
+not real numbers raise `Plurimath::Math::Evaluation::InvalidBindingError`.
+Division by zero raises `Plurimath::Math::Evaluation::DivisionByZeroError`.
+Math domain violations such as `ln(-1)`, including results that are not real
+numbers, raise `Plurimath::Math::Evaluation::MathDomainError`. Evaluations
+that do not produce a finite number, such as `ln(0)`, raise
+`Plurimath::Math::Evaluation::NonFiniteResultError`. Unsupported expressions,
+including equations that would require solving, raise
+`Plurimath::Math::Evaluation::UnsupportedExpressionError`. All evaluation
+errors subclass `Plurimath::Math::Evaluation::Error`.
+
+
 === Converting to other formats
 
 Once you have a `Plurimath::Math::Formula` object, you can convert it to
@@ -811,6 +888,205 @@ The decimal separator is rendered as configured by the `decimal` option.
 NOTE: The fractional-part conversion treats the digits after the decimal point as a fractional value (for example, `"10.75"` is interpreted
 as decimal `0.75` for the fractional part) and converts that real value to the requested base, honoring the configured precision.
 
+
+===== Semantic base notation rendering
+
+When numbers are formatted with a non-decimal `base`, Plurimath produces
+*structured output* in each representation language rather than flat
+prefix/postfix strings. The base is rendered as a subscript, making the
+output semantically rich and accessible to screen readers and other tools.
+
+For plain-text uses (`localized_number`), prefix/postfix notation is still
+available through the `base_prefix` and `base_postfix` options.
+
+.Semantic rendering by format
+[example]
+====
+[source,ruby]
+----
+formatter = Plurimath::Formatter::Standard.new(options: { base: 16 })
+Plurimath.configuration.number_formatter = formatter
+
+formula = Plurimath::Math.parse("255", :asciimath)
+
+formula.to_asciimath
+# => "ff_(16)"
+
+formula.to_latex
+# => "\\mathrm{ff}_{16}"
+
+formula.to_html
+# => "ff<sub>16</sub>"
+
+formula.to_unicodemath
+# => "ff_(16)"
+----
+
+MathML produces a structured `<msub>` element:
+
+[source,xml]
+----
+<msub><mn>ff</mn><mn>16</mn></msub>
+----
+
+OMML produces a structured `<m:sSub>` element:
+
+[source,xml]
+----
+<m:sSub>
+  <m:sSubPr>...</m:sSubPr>
+  <m:e><m:r><m:t>ff</m:t></m:r></m:e>
+  <m:sub><m:r><m:t>16</m:t></m:r></m:sub>
+</m:sSub>
+----
+====
+
+Negative numbers wrap the sign around the subscript structure:
+
+[source,ruby]
+----
+formula = Plurimath::Math.parse("-255", :asciimath)
+formula.to_latex
+# => "-\\mathrm{ff}_{16}"
+----
+
+[source,xml]
+----
+<mrow><mo>-</mo><msub><mn>ff</mn><mn>16</mn></msub></mrow>
+====
+
+
+===== Structured notation rendering
+
+Scientific and engineering notation also produces structured output in MathML.
+The `× 10^exp` portion is rendered as separate elements:
+
+[source,ruby]
+----
+formatter = Plurimath::Formatter::Standard.new(
+  options: { notation: :scientific, exponent_sign: :plus },
+)
+Plurimath.configuration.number_formatter = formatter
+
+formula = Plurimath::Math.parse("14000", :asciimath)
+----
+
+[source,xml]
+----
+<mrow>
+  <mn>1.4000</mn>
+  <mo>×</mo>
+  <msup><mn>10</mn><mn>+4</mn></msup>
+</mrow>
+----
+
+E-notation remains as a flat `<mn>` element:
+
+[source,xml]
+----
+<mn>1.4000E+4</mn>
+====
+
+
+===== Structured formatter API
+
+`NumberFormatter#localized_number` continues to return a flat string for
+backward compatibility. A new `NumberFormatter#formatted_number` method returns
+a structured value object that carries the semantic parts of the formatted
+number.
+
+[source,ruby]
+----
+formatter = Plurimath::NumberFormatter.new(:en)
+result = formatter.formatted_number("255", format: { base: 16 })
+
+result                                   # => FormattedNumber
+result.to_s                              # => "0xff"
+result.digits_string                     # => "ff"
+result.sign_text                         # => nil (no sign for positive numbers)
+result.base_notation.base                # => 16
+result.negative?                         # => false
+result.fractional?                       # => false
+----
+
+The `sign_text` accessor returns `"-"` for negative numbers, `"+"` when
+`number_sign: :plus` is set, and `nil` otherwise. Output renderers use it
+to produce format-specific sign elements.
+
+For notation numbers, `formatted_number` returns a `FormattedNotation` value
+object:
+
+[source,ruby]
+----
+result = formatter.formatted_number("14000", format: { notation: :scientific })
+
+result                                   # => FormattedNotation
+result.to_s                              # => "1.4000 × 10^4"
+result.coefficient                       # => FormattedNumber
+result.coefficient.to_s                  # => "1.4000"
+result.exponent                          # => 4
+result.formatted_exponent                # => "4" ("+4" when exponent_sign: :plus)
+result.notation_style                    # => :scientific
+----
+
+These value objects are what Plurimath uses internally to produce the
+structured output shown above.
+
+
+===== Storing base on Math::Number
+
+`Plurimath::Math::Number` now accepts a `base:` keyword, storing the radix
+as a semantic attribute. When present, the stored base is used as the default
+for formatting — no explicit `base:` option is needed in the format hash.
+
+[source,ruby]
+----
+number = Plurimath::Math::Number.new("FF", base: 16)
+# When rendered with a configured formatter, the stored base (16) is used:
+number.to_asciimath(options: {})
+# => "ff_(16)"
+----
+
+The stored base represents the *semantic truth* about the number and takes
+precedence over the formatter's built-in base configuration. An explicit
+`format: { base: N }` parameter still overrides everything.
+
+
+===== Parse-time base prefix literals
+
+All four input parsers (AsciiMath, LaTeX, UnicodeMath, HTML) recognize
+base-prefixed number literals and store the base automatically on the
+resulting `Math::Number` node — no manual `base:` keyword needed.
+
+[cols="1,1,3", options="header"]
+|===
+|Prefix |Base |Example
+
+|`0x` / `0X` |16 |`0xFF`, `0xBE EF`
+|`0b` / `0B` |2  |`0b1010`
+|`0o` / `0O` |8  |`0o17`
+|===
+
+[source,ruby]
+----
+formula = Plurimath::Math.parse("0xFF", :asciimath)
+formula.value.first.value  # => "FF"
+formula.value.first.base   # => 16
+
+# The stored base drives semantic rendering in every output format:
+formula.to_asciimath  # => "ff_(16)"
+formula.to_latex      # => "\mathrm{ff}_{16}"
+formula.to_html       # => "ff<sub>16</sub>"
+----
+
+NOTE: Hex literals store the original hex digits (`"FF"`) because letters
+are unambiguous. Binary and octal literals store the *decimal equivalent*
+(`0b1010` → value `"10"`) because their digit sets overlap with decimal.
+
+The shared `Plurimath::BaseNumberPrefix` module defines these parser and
+transform rules once; every format parser includes it. Adding a new base
+prefix requires editing only `lib/plurimath/base_number_prefix.rb`.
+
 ===== Base conversion with other formatting options
 
 Base conversion works seamlessly with other formatting options such as `precision`, `digit_count`,
@@ -1671,12 +1947,12 @@ end
 
 Formula rendering uses the first formatter method available in this order:
 `format_number(formula, number)`, then `format(formula, number)`, then
-`localized_number(number.value.to_s)`. This keeps existing custom formatters
-working while giving new custom formatters a method name specific to formula
-number formatting.
-
-New custom formatters should define `format_number`; the `format` fallback
-exists for compatibility with existing custom formatters.
+`formatted_number(number.value.to_s)` (returns a structured value object),
+then `localized_number(number.value.to_s)` (returns a flat string). This
+keeps existing custom formatters working while giving new code access to the
+structured result through `formatted_number`. New custom formatters should
+define `format_number`; the `format` fallback exists for compatibility with
+existing custom formatters.
 
 To implement contextual formatting, define a `format_number` method in a custom
 formatter subclass.

data/lib/plurimath/asciimath/parse.rb

@@ -3,6 +3,8 @@
 module Plurimath
   class Asciimath
     class Parse < Parslet::Parser
+      include Plurimath::BaseNumberPrefix::Parser
+
       rule(:td)     { expression.as(:td) }
       rule(:base)   { str("__|").absent? >> str("_") }
       rule(:power)  { str("^") }
@@ -10,7 +12,10 @@ module Plurimath
       rule(:comma)  { str(",") >> space? }
       rule(:space?) { space.maybe }
       rule(:number) do
-        (match("[0-9]").repeat(1) >> decimal_marker >> match("[0-9]").repeat(1)).as(:number) |
+        hex_number |
+          binary_number |
+          octal_number |
+          (match("[0-9]").repeat(1) >> decimal_marker >> match("[0-9]").repeat(1)).as(:number) |
           match("[0-9]").repeat(1).as(:number) |
           str(".").as(:symbol)
       end

data/lib/plurimath/asciimath/transform.rb

@@ -3,6 +3,8 @@
 module Plurimath
   class Asciimath
     class Transform < Parslet::Transform
+      include Plurimath::BaseNumberPrefix::Transform
+
       rule(mod: simple(:mod))       { mod }
       rule(frac: simple(:frac))     { frac }
       rule(unary: simple(:unary))   { unary }

data/lib/plurimath/base_number_prefix.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Plurimath
+  # Shared base-prefix number literal rules (0x, 0b, 0o) for all Parslet
+  # parsers and transforms. Including the Parser sub-module adds hex/binary/
+  # octal parser atoms; including the Transform sub-module adds the
+  # corresponding Math::Number construction rules. Define base prefixes here
+  # once — every format parser picks them up automatically.
+  module BaseNumberPrefix
+    # Adds Parslet parser rules for hex/binary/octal prefixed literals.
+    # Include in any Parslet::Parser subclass.
+    module Parser
+      def self.included(base)
+        base.class_eval do
+          rule(:hex_number) do
+            (str("0x") | str("0X")) >> match["0-9a-fA-F"].repeat(1).as(:hex_number)
+          end
+
+          rule(:binary_number) do
+            (str("0b") | str("0B")) >> match["01"].repeat(1).as(:binary_number)
+          end
+
+          rule(:octal_number) do
+            (str("0o") | str("0O")) >> match["0-7"].repeat(1).as(:octal_number)
+          end
+        end
+      end
+    end
+
+    # Adds Parslet transform rules that build Math::Number with the correct
+    # base attribute from hex/binary/octal parse tree nodes.
+    # Include in any Parslet::Transform subclass.
+    module Transform
+      def self.included(base)
+        base.class_eval do
+          rule(hex_number: simple(:hex)) { Math::Number.new(hex.to_s, base: 16) }
+          rule(binary_number: simple(:bin)) { Math::Number.new(bin.to_s.to_i(2).to_s, base: 2) }
+          rule(octal_number: simple(:oct)) { Math::Number.new(oct.to_s.to_i(8).to_s, base: 8) }
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/configuration.rb

@@ -4,7 +4,15 @@ module Plurimath
   class Configuration
     DEFAULT_DECIMAL = "."
 
-    attr_accessor :number_formatter, :locale
+    # Cap on bounded sum/prod iterations, guarding the untrusted-document
+    # evaluation path against runaway loops. Set to nil to disable the cap.
+    DEFAULT_MAX_ITERATIONS = 100_000
+
+    attr_accessor :number_formatter, :locale, :evaluation_max_iterations
+
+    def initialize
+      @evaluation_max_iterations = DEFAULT_MAX_ITERATIONS
+    end
 
     def deprecation
       Deprecation

data/lib/plurimath/errors/evaluation/division_by_zero_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      class DivisionByZeroError < Error
+        def initialize
+          super("divided by 0")
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/errors/evaluation/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      class Error < Plurimath::Error; end
+    end
+  end
+end

data/lib/plurimath/errors/evaluation/invalid_binding_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      class InvalidBindingError < Error
+        def initialize(name, value)
+          super("wrong value for variable `#{name}` " \
+                "(given #{value.class}, expected a real number)")
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/errors/evaluation/invalid_binding_key_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      class InvalidBindingKeyError < Error
+        def initialize(key)
+          super("wrong type for binding key " \
+                "(given #{key.class}, expected String or Symbol)")
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/errors/evaluation/math_domain_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      class MathDomainError < Error; end
+    end
+  end
+end

data/lib/plurimath/errors/evaluation/missing_variable_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      class MissingVariableError < Error
+        def initialize(name)
+          super("missing value for variable `#{name}`")
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/errors/evaluation/non_finite_result_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      class NonFiniteResultError < Error
+        def initialize
+          super("result is not a finite number")
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/errors/evaluation/unsupported_expression_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      class UnsupportedExpressionError < Error
+        def initialize(message)
+          super("unsupported expression: #{message}")
+        end
+      end
+    end
+  end
+end

data/lib/plurimath/errors/evaluation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    module Evaluation
+      autoload :Error, "#{__dir__}/evaluation/error"
+      autoload :DivisionByZeroError, "#{__dir__}/evaluation/division_by_zero_error"
+      autoload :InvalidBindingError, "#{__dir__}/evaluation/invalid_binding_error"
+      autoload :InvalidBindingKeyError,
+               "#{__dir__}/evaluation/invalid_binding_key_error"
+      autoload :MathDomainError, "#{__dir__}/evaluation/math_domain_error"
+      autoload :MissingVariableError, "#{__dir__}/evaluation/missing_variable_error"
+      autoload :NonFiniteResultError, "#{__dir__}/evaluation/non_finite_result_error"
+      autoload :UnsupportedExpressionError,
+               "#{__dir__}/evaluation/unsupported_expression_error"
+    end
+  end
+end

data/lib/plurimath/errors.rb

@@ -2,6 +2,7 @@
 
 module Plurimath
   module Errors
+    autoload :Evaluation, "#{__dir__}/errors/evaluation"
     autoload :InvalidNumber, "#{__dir__}/errors/invalid_number"
     autoload :UnsupportedBase, "#{__dir__}/errors/unsupported_base"
     autoload :UnsupportedLocale, "#{__dir__}/errors/unsupported_locale"

data/lib/plurimath/formatter/numbers/base_notation.rb

@@ -3,8 +3,10 @@
 module Plurimath
   module Formatter
     module Numbers
-      # Applies base prefix/postfix notation after numeric digits have already
-      # been rendered.
+      # Describes base prefix/postfix notation as a resolved value object.
+      # Constructed from FormatOptions via .from_options; carries the resolved
+      # prefix and postfix strings so renderers can decide how to represent the
+      # base (inline text, MathML subscript, LaTeX subscript, etc.).
       class BaseNotation
         DEFAULT_PREFIXES = {
           2 => "0b",
@@ -13,59 +15,80 @@ module Plurimath
           16 => "0x",
         }.freeze
 
-        attr_reader :base
+        attr_reader :base, :prefix, :postfix, :hex_capital
 
-        def initialize(options)
-          @options = options
-          @base = @options.base
-          validate_base!
+        def initialize(base:, prefix: "", postfix: "", hex_capital: nil,
+                       explicit_prefix: false, explicit_postfix: false)
+          @base = base
+          @prefix = prefix
+          @postfix = postfix
+          @hex_capital = hex_capital
+          @explicit_prefix = explicit_prefix
+          @explicit_postfix = explicit_postfix
         end
 
-        def apply(string)
-          rendered = if upcase_hex?
-                       string.tr(Base::HEX_DIGITS,
-                                 Base::HEX_DIGITS.upcase)
-                     else
-                       string
-                     end
-          return rendered if default?
+        def self.from_options(options)
+          base = options.base
+          validate!(base)
 
-          "#{base_prefix}#{rendered}#{base_postfix}"
+          new(
+            base: base,
+            prefix: resolve_prefix(options, base),
+            postfix: options.base_postfix.to_s,
+            hex_capital: options.hex_capital,
+            explicit_prefix: options.base_prefix?,
+            explicit_postfix: options.base_postfix?,
+          )
+        end
+
+        def self.supported?(base)
+          DEFAULT_PREFIXES.key?(base)
         end
 
         def default?
           base == Base::DEFAULT_BASE
         end
 
-        def self.supported?(base)
-          DEFAULT_PREFIXES.key?(base)
+        # Caller overrode prefix or postfix at format-call time. Renderers that
+        # honor semantic base notation (msub, \mathrm{}_{base}, _(base)) must
+        # defer to the literal prefix/postfix in that case.
+        def literal?
+          !default? && (explicit_prefix? || explicit_postfix?)
+        end
+
+        def semantic?
+          !default? && !literal?
+        end
+
+        def upcase_hex?
+          base == 16 && hex_capital == true
+        end
+
+        def wrap(digits)
+          "#{prefix}#{digits}#{postfix}"
         end
 
         private
 
-        attr_reader :options
+        attr_reader :explicit_prefix, :explicit_postfix
 
-        def base_prefix
+        alias explicit_prefix? explicit_prefix
+        alias explicit_postfix? explicit_postfix
+
+        def self.resolve_prefix(options, base)
           return options.base_prefix if options.base_prefix?
-          # A postfix without an explicit prefix opts out of the default prefix.
           return "" if options.base_postfix?
 
           DEFAULT_PREFIXES[base]
         end
+        private_class_method :resolve_prefix
 
-        def base_postfix
-          options.base_postfix.to_s
-        end
-
-        def upcase_hex?
-          base == 16 && options.hex_capital == true
-        end
-
-        def validate_base!
-          return if self.class.supported?(base)
+        def self.validate!(base)
+          return if supported?(base)
 
           raise Plurimath::Errors::UnsupportedBase.new(base, DEFAULT_PREFIXES)
         end
+        private_class_method :validate!
       end
     end
   end