plurimath 0.10.7 → 0.11.0

data/lib/plurimath/deprecation.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Deprecation
+    BEHAVIORS = %i[collect raise silence].freeze
+    DEFAULT_BEHAVIOR = :collect
+
+    class << self
+      def warn(feature:, message: nil, replacement: nil, since: nil, remove_in: nil)
+        feature = validate_feature(feature)
+        return if behavior == :collect && emitted_features[feature]
+
+        notice = build_notice(
+          feature: feature,
+          message: message,
+          replacement: replacement,
+          since: since,
+          remove_in: remove_in,
+        )
+
+        case behavior
+        when :silence
+          nil
+        when :raise
+          raise notice
+        when :collect
+          emitted_features[feature] = notice
+        end
+      end
+
+      def behavior
+        @behavior ||= DEFAULT_BEHAVIOR
+      end
+
+      def behavior=(behavior)
+        @behavior = validate_behavior(behavior)
+      end
+
+      def notices
+        emitted_features.values
+      end
+
+      def clear!
+        @emitted_features = {}
+      end
+
+      private
+
+      def build_notice(feature:, message:, replacement:, since:, remove_in:)
+        DeprecationError.new(
+          feature: feature,
+          message: message,
+          replacement: replacement,
+          since: since,
+          remove_in: remove_in,
+        )
+      end
+
+      def emitted_features
+        @emitted_features ||= {}
+      end
+
+      def validate_behavior(behavior)
+        return behavior if BEHAVIORS.include?(behavior)
+
+        raise ConfigurationError.new(
+          :unsupported_deprecation_behavior,
+          value: behavior,
+          supported: BEHAVIORS,
+        )
+      end
+
+      def validate_feature(feature)
+        feature = feature.to_s
+        return feature unless feature.empty?
+
+        raise ConfigurationError.new(:missing_deprecation_feature)
+      end
+    end
+  end
+end

data/lib/plurimath/errors/configuration_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Plurimath
+  class ConfigurationError < Error
+    def initialize(type, value: nil, supported: nil)
+      @type = type
+      @value = value
+      @supported = supported
+      super(message)
+    end
+
+    def message
+      case @type
+      when :unsupported_deprecation_behavior
+        "unsupported deprecation behavior: #{@value.inspect}; " \
+        "expected one of #{@supported.inspect}"
+      when :missing_deprecation_feature
+        "deprecation feature must be provided"
+      when :conflicting_formatter_options
+        "formatter options cannot be used together: choose either " \
+        ":padding_digits or :padding_group_digits"
+      else
+        "invalid Plurimath configuration"
+      end
+    end
+  end
+end

data/lib/plurimath/errors/deprecation_error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Plurimath
+  class DeprecationError < Error
+    SEVERITY = :warning
+
+    attr_reader :feature, :replacement, :since, :remove_in
+
+    def initialize(feature:, message: nil, replacement: nil, since: nil, remove_in: nil)
+      @feature = feature
+      @replacement = replacement
+      @since = since
+      @remove_in = remove_in
+      @user_message = message
+      super(to_s)
+    end
+
+    def severity
+      SEVERITY
+    end
+
+    def to_s
+      deprecation = "[plurimath][DEPRECATION] #{feature} is deprecated"
+      deprecation = "#{deprecation} since #{since}" if since
+      deprecation = "#{deprecation} and will be removed in #{remove_in}" if remove_in
+
+      parts = [deprecation]
+      parts << "Use #{replacement} instead" if replacement
+      parts << @user_message if @user_message
+      "#{parts.join('. ')}."
+    end
+  end
+end

data/lib/plurimath/errors/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Plurimath
+  class Error < StandardError
+  end
+end

data/lib/plurimath/errors/formatter/unsupported_base.rb

@@ -2,7 +2,7 @@
 
 module Plurimath
   module Formatter
-    class UnsupportedBase < StandardError
+    class UnsupportedBase < Plurimath::Error
       def initialize(base, supported_bases)
         @base = base
         @supported = supported_bases.keys.map do |key|

data/lib/plurimath/errors/formatter/unsupported_locale.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    class UnsupportedLocale < Plurimath::Error
+      def initialize(locale, supported_locales)
+        @locale = locale
+        @supported = supported_locales.map(&:inspect).join(", ")
+        super(message)
+      end
+
+      def message
+        "[plurimath] Unsupported locale #{@locale.inspect}. " \
+          "Supported locales are: #{@supported}."
+      end
+    end
+  end
+end

data/lib/plurimath/errors/omml/unsupported_node_error.rb

@@ -2,7 +2,7 @@
 
 module Plurimath
   class Omml
-    class UnsupportedNodeError < StandardError
+    class UnsupportedNodeError < Plurimath::Error
       def initialize(node)
         @node = node
         super(message)

data/lib/plurimath/errors/parse_error.rb

@@ -2,7 +2,7 @@
 
 module Plurimath
   module Math
-    class ParseError < StandardError
+    class ParseError < Plurimath::Error
       def initialize(text, type)
         @text = text
         @type = type.to_sym

data/lib/plurimath/errors/parse_option_error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Math
+    class ParseOptionError < Plurimath::Error
+      def self.unknown_options(options, supported_options:)
+        new(
+          "unknown parse #{option_label(options)}: #{format_options(options)}; " \
+          "supported parse options are #{format_options(supported_options)}",
+        )
+      end
+
+      def self.unsupported_options(type, options, supported_types:)
+        new(
+          "parse #{option_label(options)} #{format_options(options)} " \
+          "#{be_verb(options)} not supported for #{type.inspect}; " \
+          "supported input types are #{format_options(supported_types)}",
+        )
+      end
+
+      def self.option_label(options)
+        options.one? ? "option" : "options"
+      end
+
+      def self.be_verb(options)
+        options.one? ? "is" : "are"
+      end
+
+      def self.format_options(options)
+        options.map(&:inspect).join(", ")
+      end
+    end
+  end
+end

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

@@ -3,22 +3,25 @@
 module Plurimath
   module Formatter
     module Numbers
+      # Shared base for formatter helpers that need resolved options, target
+      # base state, and common digit operations.
       class Base
+        HEX_DIGITS = "abcdef"
         HEX_ALPHANUMERIC = %w[0 1 2 3 4 5 6 7 8 9 a b c d e f].freeze
         DEFAULT_BASE = 10
         DIGIT_VALUE = HEX_ALPHANUMERIC.each_with_index.to_h
 
-        attr_accessor :base, :symbols
+        attr_accessor :base, :options
 
-        def initialize(symbols = {})
-          @symbols = symbols
-          @base = symbols[:base] || DEFAULT_BASE
+        def initialize(options)
+          @options = options
+          @base = @options.base
         end
 
         protected
 
         def threshold
-          @threshold ||= base.div(2)
+          digit_sequence.threshold
         end
 
         def base_default?
@@ -26,10 +29,17 @@ module Plurimath
         end
 
         def next_mapping_char(char)
-          current_idx = DIGIT_VALUE[char]
-          return nil unless current_idx
+          digit_sequence.next_digit(char)
+        end
+
+        def capitalize_hex_digits(string)
+          return string unless base == 16 && options.hex_capital == :numbers_only
+
+          string.tr(HEX_DIGITS, HEX_DIGITS.upcase)
+        end
 
-          HEX_ALPHANUMERIC[current_idx + 1]
+        def digit_sequence
+          @digit_sequence ||= DigitSequence.new(base: base)
         end
       end
     end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Applies base prefix/postfix notation after numeric digits have already
+      # been rendered.
+      class BaseNotation
+        DEFAULT_PREFIXES = {
+          2 => "0b",
+          8 => "0o",
+          10 => "",
+          16 => "0x",
+        }.freeze
+
+        attr_reader :base
+
+        def initialize(options)
+          @options = options
+          @base = @options.base
+          validate_base!
+        end
+
+        def apply(string)
+          rendered = upcase_hex? ? string.tr(Base::HEX_DIGITS, Base::HEX_DIGITS.upcase) : string
+          return rendered if default?
+
+          "#{base_prefix}#{rendered}#{base_postfix}"
+        end
+
+        def default?
+          base == Base::DEFAULT_BASE
+        end
+
+        def self.supported?(base)
+          DEFAULT_PREFIXES.key?(base)
+        end
+
+        private
+
+        attr_reader :options
+
+        def base_prefix
+          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
+
+        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)
+
+          raise UnsupportedBase.new(base, DEFAULT_PREFIXES)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Shared base-digit helper for counting, rounding thresholds, next-digit
+      # lookup, and carry propagation.
+      class DigitSequence
+        attr_reader :base
+
+        ZERO = "0"
+
+        def initialize(base:)
+          @base = base
+        end
+
+        def digit?(char)
+          Base::DIGIT_VALUE.key?(char)
+        end
+
+        def significant?(char)
+          Base::DIGIT_VALUE[char]&.positive?
+        end
+
+        def digit_count(chars, stop_at: nil)
+          count = 0
+          each_countable_digit(chars, stop_at: stop_at) { count += 1 }
+          count
+        end
+
+        def significant_digit_count(chars)
+          start_counting = false
+          count = 0
+
+          each_countable_digit(chars) do |char|
+            start_counting = true if significant?(char)
+            count += 1 if start_counting
+          end
+
+          count
+        end
+
+        def max_digit?(char)
+          Base::DIGIT_VALUE[char] == base.pred
+        end
+
+        def next_digit(char)
+          current_index = Base::DIGIT_VALUE[char]
+          return unless current_index
+
+          Base::HEX_ALPHANUMERIC[current_index + 1]
+        end
+
+        def round_up?(char)
+          value = Base::DIGIT_VALUE[char]
+          !!(value && value >= threshold)
+        end
+
+        def threshold
+          @threshold ||= base.div(2)
+        end
+
+        def increment_reversed(digits, carry: 1, skip: [], overflow: ZERO)
+          digits = digits.dup
+          return [digits, carry] unless carry.positive?
+
+          digits.each_with_index do |digit, index|
+            next if skip.include?(digit)
+            next unless digit?(digit)
+
+            if max_digit?(digit)
+              digits[index] = overflow
+            else
+              digits[index] = next_digit(digit)
+              carry = 0
+              break
+            end
+          end
+
+          [digits, carry]
+        end
+
+        private
+
+        def each_countable_digit(chars, stop_at: nil)
+          chars.each do |char|
+            break if stop_at && char == stop_at
+            next unless digit?(char)
+
+            yield(char)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Plurimath
+  module Formatter
+    module Numbers
+      # Per-render view of merged formatter symbols and resolved precision.
+      class FormatOptions
+        DEFAULT_EXPONENT_SEPARATOR = :e
+        DEFAULT_DECIMAL = "."
+        DEFAULT_FRACTION_PRECISION = 3
+        DEFAULT_GROUP = ","
+        DEFAULT_GROUP_DIGITS = 3
+        DEFAULT_PADDING = "0"
+        DEFAULT_TIMES = "\u{d7}"
+
+        attr_reader :exponent_separator, :exponent_sign, :notation, :symbols,
+                    :precision, :times
+
+        def initialize(
+          source = nil,
+          symbols: {},
+          precision: nil,
+          precision_resolver: nil
+        )
+          @symbols = symbols.dup
+          @notation = symbol_option(:notation)
+          @exponent_separator = symbol_option(:e) || DEFAULT_EXPONENT_SEPARATOR
+          @times = symbol_option(:times) || DEFAULT_TIMES
+          @precision = resolve_precision(source, precision, precision_resolver)
+          @exponent_sign = symbol_option(:exponent_sign)
+          validate_padding_options!
+        end
+
+        def base
+          symbols[:base] || Base::DEFAULT_BASE
+        end
+
+        def base_prefix
+          symbols[:base_prefix].to_s
+        end
+
+        def base_prefix?
+          symbols.key?(:base_prefix)
+        end
+
+        def base_postfix
+          symbols[:base_postfix]
+        end
+
+        def base_postfix?
+          symbols.key?(:base_postfix)
+        end
+
+        def decimal
+          symbols.fetch(:decimal, DEFAULT_DECIMAL)
+        end
+
+        def digit_count
+          symbols[:digit_count].to_i
+        end
+
+        def fraction_group
+          symbols[:fraction_group].to_s
+        end
+
+        def fraction_group_digits
+          symbols[:fraction_group_digits]
+        end
+
+        def group
+          symbols[:group] || DEFAULT_GROUP
+        end
+
+        def group_digits
+          symbols[:group_digits] || DEFAULT_GROUP_DIGITS
+        end
+
+        def hex_capital
+          symbols[:hex_capital]
+        end
+
+        def number_sign
+          symbols[:number_sign]
+        end
+
+        def padding
+          value = symbols.fetch(:padding, DEFAULT_PADDING).to_s
+          value.empty? ? DEFAULT_PADDING : value[0]
+        end
+
+        def padding_digits
+          symbols[:padding_digits].to_i
+        end
+
+        def padding_group_digits
+          symbols[:padding_group_digits].to_i
+        end
+
+        def notation_supported?
+          NotationRenderer.supported?(notation)
+        end
+
+        def significant
+          symbols[:significant].to_i
+        end
+
+        def to_h
+          symbols.dup
+        end
+
+        private
+
+        def resolve_precision(source, precision, precision_resolver)
+          effective_precision = precision || symbols[:precision]
+          return effective_precision unless precision_resolver
+
+          precision_resolver.resolve(
+            source,
+            precision: effective_precision,
+            base: base,
+            significant: significant,
+            notation_supported: notation_supported?,
+          )
+        end
+
+        def symbol_option(key)
+          symbols[key]&.to_sym
+        end
+
+        def validate_padding_options!
+          return unless symbols.key?(:padding_digits) && symbols.key?(:padding_group_digits)
+
+          raise Plurimath::ConfigurationError.new(
+            :conflicting_formatter_options,
+            supported: %i[padding_digits padding_group_digits],
+          )
+        end
+      end
+    end
+  end
+end