plurimath 0.11.0 → 0.11.3

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    class InvalidNumber < Plurimath::Error
+      def initialize(value)
+        @value = value
+        super(message)
+      end
+
+      def message
+        "[plurimath] Invalid number #{@value.inspect} for number formatting. " \
+          "Expected a numeric string such as \"1234\", \"-12.34\", or \"1.2e5\"."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/unsupported_base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Errors
+    class UnsupportedBase < Plurimath::Error
+      def initialize(base, supported_bases)
+        @base = base
+        @supported = supported_bases.keys.join(", ")
+        super(message)
+      end
+
+      def message
+        "[plurimath] Unsupported base `#{@base}` for number formatting. " \
+          "[plurimath] The formatter `:base` option must be one of: #{@supported}."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/{formatter/unsupported_locale.rb → unsupported_locale.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Plurimath
-  module Formatter
+  module Errors
     class UnsupportedLocale < Plurimath::Error
       def initialize(locale, supported_locales)
         @locale = locale

data/lib/plurimath/errors.rb

@@ -1 +1,10 @@
 # frozen_string_literal: true
+
+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"
+  end
+end

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,54 +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 = upcase_hex? ? string.tr(Base::HEX_DIGITS, Base::HEX_DIGITS.upcase) : string
-          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 UnsupportedBase.new(base, DEFAULT_PREFIXES)
+          raise Plurimath::Errors::UnsupportedBase.new(base, DEFAULT_PREFIXES)
         end
+        private_class_method :validate!
       end
     end
   end

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

@@ -32,11 +32,16 @@ module Plurimath
         end
 
         def base
-          symbols[:base] || Base::DEFAULT_BASE
+          value = symbols[:base]
+          return Base::DEFAULT_BASE if value.nil?
+
+          # Numeric String/Symbol forms are normalized; anything else is left
+          # raw so BaseNotation reports it through UnsupportedBase.
+          coerce_integer(value) { return value }
         end
 
         def base_prefix
-          symbols[:base_prefix].to_s
+          separator_option(:base_prefix).to_s
         end
 
         def base_prefix?
@@ -44,7 +49,7 @@ module Plurimath
         end
 
         def base_postfix
-          symbols[:base_postfix]
+          separator_option(:base_postfix)
         end
 
         def base_postfix?
@@ -52,56 +57,84 @@ module Plurimath
         end
 
         def decimal
-          symbols.fetch(:decimal, DEFAULT_DECIMAL)
+          # An explicitly passed nil renders without a separator; output
+          # correctness is then the caller's responsibility.
+          separator_option(:decimal, default: DEFAULT_DECIMAL)
         end
 
         def digit_count
-          symbols[:digit_count].to_i
+          integer_option(:digit_count, default: 0)
         end
 
         def fraction_group
-          symbols[:fraction_group].to_s
+          separator_option(:fraction_group).to_s
         end
 
         def fraction_group_digits
-          symbols[:fraction_group_digits]
+          integer_option(:fraction_group_digits)
         end
 
         def group
-          symbols[:group] || DEFAULT_GROUP
+          # Unlike decimal, an explicit nil group falls back to the default
+          # separator; use "" to disable grouping.
+          (separator_option(:group,
+                            default: DEFAULT_GROUP) || DEFAULT_GROUP).to_s
         end
 
         def group_digits
-          symbols[:group_digits] || DEFAULT_GROUP_DIGITS
+          integer_option(:group_digits, default: DEFAULT_GROUP_DIGITS)
         end
 
         def hex_capital
-          symbols[:hex_capital]
+          value = symbols[:hex_capital]
+          # nil is handled first: under Opal `when nil` spuriously matches
+          # non-nil values (nil === 1.5 is true there), so it must not appear
+          # in the type whitelist below.
+          return if value.nil?
+
+          # Accept only Boolean/String/Symbol and reject any other type.
+          # Attribute-parsing callers deliver String/Symbol (:true,
+          # "numbers_only"), so the accepted forms normalize through to_s.
+          case value
+          when true, false, String, Symbol
+            case value.to_s
+            when "true" then true
+            when "numbers_only" then :numbers_only
+            end
+          else
+            invalid_option!(:hex_capital, value)
+          end
         end
 
         def number_sign
-          symbols[:number_sign]
+          symbol_option(:number_sign)
         end
 
         def padding
-          value = symbols.fetch(:padding, DEFAULT_PADDING).to_s
+          value = separator_option(:padding, default: DEFAULT_PADDING).to_s
           value.empty? ? DEFAULT_PADDING : value[0]
         end
 
         def padding_digits
-          symbols[:padding_digits].to_i
+          integer_option(:padding_digits, default: 0)
         end
 
         def padding_group_digits
-          symbols[:padding_group_digits].to_i
+          integer_option(:padding_group_digits, default: 0)
         end
 
         def notation_supported?
           NotationRenderer.supported?(notation)
         end
 
+        # Whether precision came from the caller (kwarg or symbols) rather
+        # than being inferred from the source by the resolver.
+        def explicit_precision?
+          @explicit_precision
+        end
+
         def significant
-          symbols[:significant].to_i
+          integer_option(:significant, default: 0)
         end
 
         def to_h
@@ -111,7 +144,19 @@ module Plurimath
         private
 
         def resolve_precision(source, precision, precision_resolver)
-          effective_precision = precision || symbols[:precision]
+          # A nil check (not ||) so that explicit false reaches validation.
+          effective_precision = precision.nil? ? symbols[:precision] : precision
+          unless effective_precision.nil?
+            value = effective_precision
+            effective_precision = coerce_integer(value) do
+              invalid_option!(:precision, value)
+            end
+            if effective_precision.negative?
+              invalid_option!(:precision, value,
+                              expected: "a non-negative integer")
+            end
+          end
+          @explicit_precision = !effective_precision.nil?
           return effective_precision unless precision_resolver
 
           precision_resolver.resolve(
@@ -119,12 +164,73 @@ module Plurimath
             precision: effective_precision,
             base: base,
             significant: significant,
+            digit_count: digit_count,
             notation_supported: notation_supported?,
           )
         end
 
+        # Counts must be non-negative Integers; numeric String/Symbol forms are
+        # normalized because attribute-parsing callers deliver those.
+        def integer_option(key, default: nil)
+          value = symbols[key]
+          return default if value.nil?
+
+          integer = coerce_integer(value) { invalid_option!(key, value) }
+          if integer.negative?
+            invalid_option!(key, value,
+                            expected: "a non-negative integer")
+          end
+
+          integer
+        end
+
+        def coerce_integer(value)
+          # Note on Opal: JS has a single number type, so a whole-valued Float
+          # (4.0) is indistinguishable from the Integer 4 (same value, same
+          # to_s "4") — under Opal it is treated as that integer. MRI rejects
+          # Floats here; non-whole Floats (1.5) are rejected in both runtimes.
+          case value
+          when ::Integer then value
+          when true, false, Float then yield
+          else
+            begin
+              Integer(value.to_s, 10)
+            rescue ArgumentError, TypeError
+              yield
+            end
+          end
+        end
+
+        # Separators are free-form strings; explicit nil disables the
+        # separator, and Booleans are always a caller bug.
+        def separator_option(key, default: nil)
+          value = symbols.fetch(key, default)
+          invalid_option!(key, value) if [true, false].include?(value)
+
+          value
+        end
+
         def symbol_option(key)
-          symbols[key]&.to_sym
+          value = symbols[key]
+          return if value.nil?
+
+          # Enumerated/symbol options accept only String or Symbol; reject
+          # other types (and booleans) instead of coercing arbitrary input.
+          unless value.is_a?(String) || value.is_a?(Symbol)
+            invalid_option!(key,
+                            value)
+          end
+
+          value.to_sym
+        end
+
+        def invalid_option!(key, value, expected: nil)
+          raise Plurimath::ConfigurationError.new(
+            :invalid_formatter_option,
+            option: key,
+            value: value,
+            supported: expected,
+          )
         end
 
         def validate_padding_options!

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Structured result of notation formatting (e, scientific, engineering).
+      # Carries the coefficient as a FormattedNumber, the exponent as an
+      # integer, and notation style metadata so output renderers (MathML,
+      # LaTeX, etc.) can produce structured representations instead of flat
+      # strings.
+      class FormattedNotation
+        STYLES = %i[e scientific engineering].freeze
+
+        attr_reader :coefficient, :notation_style, :exponent,
+                    :times_symbol, :exponent_separator, :exponent_sign
+
+        def initialize(
+          coefficient:,
+          notation_style:,
+          exponent:,
+          times_symbol: "×",
+          exponent_separator: "e",
+          exponent_sign: nil
+        )
+          @coefficient = coefficient
+          @notation_style = notation_style
+          @exponent = exponent
+          @times_symbol = times_symbol
+          @exponent_separator = exponent_separator
+          @exponent_sign = exponent_sign
+        end
+
+        def to_s
+          case notation_style
+          when :e
+            "#{coefficient}#{exponent_separator}#{formatted_exponent}"
+          when :scientific, :engineering
+            "#{coefficient} #{times_symbol} 10^#{formatted_exponent}"
+          end
+        end
+
+        def to_str
+          to_s
+        end
+
+        def base_notation?
+          coefficient.base_notation?
+        end
+
+        # The exponent rendered as a string, applying sign conventions.
+        # Public so that output renderers can access it directly.
+        def formatted_exponent
+          return "0" if exponent.zero?
+
+          sign_prefix = exponent_sign == :plus ? "+" : nil
+          abs_exp = exponent.abs.to_s
+          exponent.negative? ? "-#{abs_exp}" : "#{sign_prefix}#{abs_exp}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Structured result of number formatting. Carries sign, digit parts,
+      # decimal separator, and base notation as separate semantic elements
+      # so output renderers (MathML, LaTeX, etc.) can produce structured
+      # representations instead of flat strings.
+      class FormattedNumber
+        attr_reader :sign, :integer_part, :fraction_part,
+                    :decimal_separator, :base_notation, :number_sign
+
+        def initialize(
+          sign:,
+          integer_part:,
+          fraction_part:,
+          decimal_separator:,
+          base_notation:,
+          number_sign: nil
+        )
+          @sign = sign
+          @integer_part = integer_part
+          @fraction_part = fraction_part
+          @decimal_separator = decimal_separator
+          @base_notation = base_notation
+          @number_sign = number_sign
+        end
+
+        def negative?
+          sign == -1
+        end
+
+        def fractional?
+          !fraction_part.empty?
+        end
+
+        def base_notation?
+          !base_notation.default?
+        end
+
+        # The sign as a rendering prefix: "-" for negative, "+" when
+        # number_sign is :plus, nil otherwise. Output renderers use this
+        # to produce format-specific sign elements.
+        def sign_text
+          if negative?
+            "-"
+          elsif number_sign == :plus
+            "+"
+          end
+        end
+
+        def to_s
+          digits = formatted_digits
+          digits = base_notation.wrap(digits) unless base_notation.default?
+          "#{sign_text}#{digits}"
+        end
+
+        def to_str
+          to_s
+        end
+
+        # Digits with decimal separator and optional hex capitalization,
+        # but without sign, prefix, or postfix. Used by structured renderers
+        # that handle sign and base notation as separate elements.
+        def digits_string
+          formatted_digits
+        end
+
+        private
+
+        def formatted_digits
+          digits = assembled_digits
+          base_notation.upcase_hex? ? upcase_hex(digits) : digits
+        end
+
+        def assembled_digits
+          fractional? ? "#{integer_part}#{decimal_separator}#{fraction_part}" : integer_part
+        end
+
+        def upcase_hex(string)
+          string.tr(Base::HEX_DIGITS, Base::HEX_DIGITS.upcase)
+        end
+      end
+    end
+  end
+end

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

@@ -20,7 +20,7 @@ module Plurimath
         end
 
         # Keep fraction preparation on structured parts; localized rendering and
-        # grouping happen later at the PartsRenderer boundary.
+        # grouping happen later at the FormattedNumber boundary.
         def apply_parts(parts, precision: self.precision)
           precision = precision.to_i
           return parts.with_digits(fraction_digits: DEFAULT_STRINGS[:empty]) unless precision.positive?
@@ -28,9 +28,12 @@ module Plurimath
           @integer_digits = parts.integer_digits
 
           fraction = parts.fraction_digits
-          fraction = change_base(fraction, precision) if !base_default? && fraction.match?(/[1-9]/)
+          if !base_default? && fraction.match?(/[1-9]/)
+            fraction = change_base(fraction,
+                                   precision)
+          end
           number = if @digit_count.positive?
-                     digit_count_format(fraction, precision)
+                     digit_count_format(fraction)
                    else
                      format(fraction, precision)
                    end
@@ -67,7 +70,7 @@ module Plurimath
 
         # The digit_count option is a total visible-digit budget, so fraction
         # rounding can carry back into the integer digits.
-        def digit_count_format(fraction, precision)
+        def digit_count_format(fraction)
           integer = integer_digits + DEFAULT_STRINGS[:dot] + fraction
           int_length = integer.length.pred # integer length; excluding the decimal point
           if int_length > @digit_count
@@ -79,24 +82,12 @@ module Plurimath
             end
             round_base_string(fraction)
           elsif int_length < @digit_count
-            fraction + (DEFAULT_STRINGS[:zero] * (update_digit_count(fraction, precision) - int_length))
+            fraction + (DEFAULT_STRINGS[:zero] * (@digit_count - int_length))
           else
             fraction
           end
         end
 
-        def update_digit_count(number, precision)
-          return @digit_count unless zeros_count_in(number) == precision
-
-          @digit_count - precision + 1
-        end
-
-        def zeros_count_in(number)
-          return unless number.chars.all?(DEFAULT_STRINGS[:zero])
-
-          number.length
-        end
-
         def round_base_string(fraction)
           digits = fraction[0..frac_digit_count].chars
           discard_char = digits.pop

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

@@ -24,6 +24,9 @@ module Plurimath
         def format_groups(string)
           string = capitalize_hex_digits(string)
           string = pad_integer(string)
+          # group_digits: 0 disables grouping, mirroring fraction grouping.
+          return string unless groups.positive?
+
           tokens = []
 
           until string.empty?