numerals 0.0.0 → 0.1.0

data/lib/numerals/format/format.rb

@@ -0,0 +1,257 @@
+module Numerals
+
+  # A Format object holds formatting options and performs
+  # formatted input/output operations on numbers.
+  #
+  # Formatting options are grouped into aspects:
+  #
+  # * Exact input
+  # * Rounding
+  # * Mode
+  # * Symbols
+  # * Input rounding
+  #
+  # Some aspects (Rounding, Mode & Symbols) are handled with aspect-definining
+  # classes Rounding, Format::Mode and Format::Symbols.
+  #
+  # Exact input applies only to numeric types that can hold limited
+  # precision values such as Float, Flt::Num or BigDecimal. It specifies
+  # that the numeric value is to be taken as an exact quantity. Otherwise,
+  # the numeric value is interpreted as a rounded approximation of some
+  # original exact value (so it represents a range of exact number which
+  # would all be rounded to the same approximation). Rational and Integer
+  # types are always exact and not affected by this option.
+  #
+  # Rounding defines how numbers are rounded into text form or how
+  # values represented in text round to numeric values. So it specifies
+  # the precision of the result and whether the result is an approximation
+  # or an exact quantity.
+  #
+  # Mode defines de formatting style.
+  #
+  # Symbols contains the details of how digits and other symbols are
+  # represented in text form and the final text notation used.
+  #
+  # The input-rounding property can set to either a Rounding object
+  # or just a rounding mode symbol (:half_even, etc.).
+  # It is used to define which rounding mode is implied when reading textual
+  # numeric expressions into approximate numeric values. It affects how
+  # approximate numbers are written to text because the text representation
+  # of approximate values should be read back into the original value.
+  # If a Rounding object is assigned only the mode is used, and it is ignored
+  # if the rounding is exact.  #
+  #
+  class Format < FormattingAspect
+
+    def initialize(*args)
+      @exact_input = false
+      @rounding = Rounding[:short]
+      @mode = Mode[]
+      @symbols = Symbols[]
+      @notation = :text
+      @input_rounding = nil
+      set! *args
+    end
+
+    attr_reader :rounding, :exact_input, :mode, :symbols, :notation,
+                :input_rounding
+
+    def base
+      @rounding.base
+    end
+
+    # Presentation base for the significand
+    def significand_base
+      base**@mode.base_scale
+    end
+
+    include ModalSupport::StateEquivalent
+
+    def input_rounding?
+      !@input_rounding.nil?
+    end
+
+    def input_rounding_mode
+      input_rounding? ? @input_rounding.mode : nil
+    end
+
+    set do |*args|
+      options = extract_options(*args)
+      @exact_input = options[:exact_input] if options.has_key?(:exact_input)
+      @rounding.set! options[:rounding] if options[:rounding]
+      @mode.set! options[:mode] if options[:mode] # :format ?
+      @symbols.set! options[:symbols] if options[:symbols]
+      @notation = options[:notation] if options[:notation]
+      if options.has_key?(:input_rounding)
+        set_input_rounding! options[:input_rounding]
+      end
+
+      # shortcuts
+      @rounding.set! base: options[:base] if options[:base]
+      @symbols.set! digits: options[:digits] if options[:digits]
+      @rounding.set! mode: options[:rounding_mode] if options[:rounding_mode]
+      @rounding.set! precision: options[:precision] if options[:precision]
+      @rounding.set! places: options[:places] if options[:places]
+      @symbols.set! repeating: options[:repeating] if options.has_key?(:repeating)
+      @symbols.set! case_sensitive: options[:case_sensitive] if options.has_key?(:case_sensitive)
+    end
+
+    def parameters
+      {
+        rounding: @rounding,
+        exact_input: @exact_input,
+        mode: @mode,
+        symbols: @symbols,
+        notation: @notation,
+        input_rounding: input_rounding? ? @input_rounding : nil
+      }
+    end
+
+    def to_s
+      args = []
+      args << "exact_input: true" if @exact_input
+      args << "rounding: #{@rounding}"
+      args << "mode: #{@mode}"
+      args << "symbols: #{@symbols}"
+      args << "notation: #{@notation.inspect}" if @notation != :text
+      args << "input_rounding: #{input_rounding_mode.inspect}" if input_rounding?
+      "Format[#{args.join(', ')}]"
+    end
+
+    def inspect
+      to_s
+    end
+
+    def case_sensitive?
+      @symbols.case_sensitive?
+    end
+
+    aspect :rounding do |*args|
+      set! rounding: args
+    end
+
+    aspect :base do |base|
+      set! base: base
+    end
+
+    aspect :exact_input do |value|
+      @exact_input = value
+    end
+
+    aspect :mode do |*args|
+      set! mode: args
+    end
+
+    aspect :symbols do |*args|
+      set symbols: args
+    end
+
+    aspect :notation do |notation|
+      set! notation: notation
+    end
+
+    aspect :digits do |digits|
+      set! digits: digits
+    end
+
+    aspect :input_rounding do |input_roundig|
+      if input_roundig.nil?
+        @input_rounding = nil
+      else
+        if @input_rounding.nil?
+          @input_rounding = Rounding[input_roundig]
+        else
+          @input_rounding.set! input_roundig
+        end
+      end
+    end
+
+    def dup
+      # we need deep copy
+      Format[parameters]
+    end
+
+    include Output
+    include Input
+
+    # Shortcuts to Symbols sub-aspects
+
+    aspect :repeat do |*args|
+      @symbols.set_repeat!(*args)
+    end
+
+    aspect :grouping do |*args|
+      @symbols.set_grouping!(*args)
+    end
+
+    aspect :group_thousands do |sep = nil|
+      @symbols.set_grouping!(sep)
+    end
+
+    aspect :signs do |plus, minus|
+      @symbols.set_signs!(plus, minus)
+    end
+
+    aspect :plus do |plus, which = nil|
+      @symbols.set_plus!(plus, which)
+    end
+
+    aspect :minus do |minus|
+      @symbols.set_minus!(minus)
+    end
+
+    private
+
+    def extract_options(*args)
+      options = {}
+      args = args.first if args.size == 1 && args.first.kind_of?(Array)
+      args.each do |arg|
+        case arg
+        when Hash
+          options.merge! arg
+        when Rounding
+          options[:rounding] = arg
+        when Mode
+          options[:mode] = arg
+        when Symbols
+          options[:symbols] = arg
+        when Symbols::Digits
+          options[:digits] = arg
+        when Format
+          options.merge! arg.parameters
+        when :exact_input
+          options[:exact_input] = true
+        when :hexbin
+          options.merge!(
+            base: 2,
+            mode: {
+              base_scale: 4,
+              mode: :scientific,
+              sci_int_digits: 1
+            },
+            symbols: {
+              exponent: 'p'
+            }
+          )
+        when :gen, :general, :sci, :scientific, :fix; :fixed
+          options[:mode] = Mode[arg]
+        when :short, :free, :simplify, :preserve
+          options[:precision] = arg
+        when  :half_even, :half_down, :half_up, :down, :up, :ceiling, :floor, :up05
+          options[:rounding_mode] = arg
+        when :case_sensitive
+          options[:case_sensitive] = true
+        when Symbol
+          options[:notation] = arg
+        when Integer
+          options[:base] = arg
+        else
+          raise "Invalid Format definition"
+        end
+      end
+      options
+    end
+
+  end
+
+end

data/lib/numerals/format/input.rb

@@ -0,0 +1,140 @@
+module Numerals
+
+  # Formatted input implementation
+  module Format::Input
+
+    def read(text, options={})
+      # 1. Obtain destination type
+      selector = options[:context] || options[:type]
+      conversion = Conversions[selector, options[:type_options]]
+      if conversion
+        type = conversion.type
+      else
+        type = options[:type]
+        if type != Numeral
+          raise Format::InvalidNumericType, "Invalid type #{selector.inspect}"
+        end
+      end
+
+      # if conversion.is_a?(ContextConversion)
+      #   context = conversion.context
+      # end
+
+      # 2. dissassemble (parse notation): text notation => text parts
+      text_parts = Format.disassemble(@notation, self, text)
+
+      # 3. Convert text parts to values and generate a Numeral
+      numeral = partition_in(text_parts)
+
+      # 4. Convert to requested type:
+      if type == Numeral
+        return numeral
+      else
+        conversion_in(numeral, options)
+      end
+    end
+
+    def partition_in(text_parts)
+      if text_parts.special?
+        # Read special number
+        nan = /#{@symbols.regexp(:nan, case_sensitivity: true)}/
+        inf = /
+          #{@symbols.regexp(:plus, :minus, case_sensitivity: true)}?
+          \s*
+          #{@symbols.regexp(:infinity, case_sensitivity: true)}
+        /x
+        minus = /#{@symbols.regexp(:minus, case_sensitivity: true)}/
+        if nan.match(text_parts.special)
+          numeral = Numeral[:nan]
+        elsif match = inf.match(text_parts.special)
+          if match[1] && match[1] =~ minus
+            sign = -1
+          else
+            sign = +1
+          end
+          numeral = Numeral[:infinity, sign: sign]
+        else
+          raise Format::InvaludNumberFormat, "Invalid number"
+        end
+      else
+        # Parse and convert text parts to values
+        input_rounding = @input_rounding || @rounding
+        input_base = significand_base
+
+        if !@symbols.repeating && (text_parts.repeat || text_parts.detect_repeat)
+          raise Format::InvalidRepeatingNumeral, "Invalid format: unexpected repeating numeral"
+        end
+
+        minus = /#{@symbols.regexp(:minus, case_sensitivity: true)}/
+        if text_parts.sign? && text_parts.sign =~ minus
+          sign = -1
+        else
+          sign = +1
+        end
+
+        integer_digits = []
+        if text_parts.integer?
+          integer_digits = @symbols.digits_values(text_parts.integer, base: input_base)
+        end
+
+        fractional_digits = []
+        if text_parts.fractional?
+          fractional_digits = @symbols.digits_values(text_parts.fractional, base: input_base)
+        end
+
+        exponent_value = 0
+        if text_parts.exponent?
+          exponent_value = text_parts.exponent.to_i
+        end
+
+        point = integer_digits.size
+
+        if text_parts.detect_repeat? # repeat_suffix found
+          digits = integer_digits + fractional_digits
+          digits, repeat = RepeatDetector.detect(digits, @symbols.repeat_count - 1)
+        elsif text_parts.repeat?
+          repeat_digits = @symbols.digits_values(text_parts.repeat, base: input_base)
+          digits = integer_digits + fractional_digits
+          repeat = digits.size
+          digits += repeat_digits
+        else
+          digits = integer_digits + fractional_digits
+          repeat = nil
+        end
+
+        if @mode.base_scale > 1
+          # De-scale the significand base
+          digits = Format::BaseScaler.ugrouped_digits(digits, base, @mode.base_scale)
+          point  *= @mode.base_scale
+          repeat *= @mode.base_scale if repeat
+        end
+
+        point += exponent_value
+
+        # Generate Numeral
+        if repeat || @exact_input
+          normalization = :exact
+        else
+          normalization = :approximate
+        end
+        numeral = Numeral[digits, sign: sign, point: point, repeat: repeat, base: base, normalize: normalization]
+      end
+    end
+
+    def conversion_in(numeral, options)
+      options = options.merge(
+        exact: numeral.exact?, # @exact_input, Also: if we want to force :fixed format
+        simplify: @rounding.simplifying?, # applies to approx input only => :short
+      )
+      type_options = { input_rounding: @input_rounding || @rounding }
+      if options[:type_options]
+        options[:type_options] = type_options.merge(options[:type_options])
+      else
+        options[:type_options] = type_options
+      end
+      Conversions.read(numeral, options)
+    end
+
+  end
+
+end

data/lib/numerals/format/mode.rb

@@ -0,0 +1,157 @@
+module Numerals
+
+  # Formatting mode
+  #
+  # * :scientific use scientific notation.
+  # * :fixed used fixed notation.
+  # * :general (the default) uses :fixed notation unless
+  #   it would produce trailing zeros in the integer part
+  #   or too many leading zeros in the fractional part.
+  #   The intent is to produced the simplest or more natural
+  #   output and it's regulated by the :max_leading and
+  #  :max_trailing parameters.
+  #
+  # The special value :engineering can be used as a shortcut
+  # for :scientific mode with :engineering :sci_int_digits.
+  #
+  # The modes can be abbreviated as :sci, :fix, :gen and :end.
+  #
+  # * :sci_int_digits numbe of digits to the left of the point
+  #   in scientific notation. By default 1. The special value
+  #   :engineering can be used for engineering notation, i.e.
+  #   the number of digits will be between one and 3 so that the
+  #   exponent is a multiple of 3.
+  #   The special value :all is used to make the significand an
+  #   integer value.
+  #
+  # * :max_leading (maximum number of leading zeros) determines
+  #   when :scientific is chosen instead of :fixed when the mode is
+  #   :general.
+  #   The default value, 5 is that of the General Decimal Arithmetic
+  #   'to-scientific-string' number to text conversion, and also used
+  #   by the .NET General ("G") format specifier. To reproduce the
+  #   behaviour of the C %g format specifier the value should be 3.
+  #   The special value :all can be used to reproduce the behaviour
+  #   of some calculators, where scientific notation is used when
+  #   more digits than the specified precision would be needed.
+  #
+  class Format::Mode < FormattingAspect
+
+    DEFAULTS = {
+      mode: :general,
+      sci_int_digits: 1,
+      max_leading: 5,
+      max_trailing: 0,
+      base_scale: 1
+    }
+
+    def initialize(*args)
+      DEFAULTS.each do |param, value|
+        instance_variable_set "@#{param}", value
+      end
+      set! *args
+    end
+
+    attr_reader :mode, :sci_int_digits, :max_leading, :max_trailing, :base_scale
+
+    include ModalSupport::StateEquivalent
+
+    set do |*args|
+      options = extract_options(*args)
+      options.each do |option, value|
+        send :"#{option}=", value
+      end
+    end
+
+    MODE_SHORTCUTS = {
+      gen: :general,
+      sci: :scientific,
+      fix: :fixed,
+      eng: :engineering
+    }
+
+    def mode=(mode)
+      @mode = MODE_SHORTCUTS[mode] || mode
+      if @mode == :engineering
+        @mode = :scientific
+        @sci_int_digits = :engineering
+      end
+    end
+
+    def sci_int_digits=(v)
+      @sci_int_digits = v
+      if @sci_int_digits == :eng
+        @sci_int_digits = :engineering
+      end
+    end
+
+    attr_writer :max_leading, :max_trailing, :base_scale
+
+    def engineering?
+      @mode == :scientific && @sci_int_digits == :engineering
+    end
+
+    def scientific?
+      @mode == :scientific
+    end
+
+    def fixed?
+      @mode == :fixed
+    end
+
+    def general?
+      @mode == :general
+    end
+
+    def parameters(abbreviated=false)
+      params = {}
+      DEFAULTS.each do |param, default|
+        value = instance_variable_get("@#{param}")
+        if !abbreviated || value != default
+          params[param] = value
+        end
+      end
+      if abbreviated && engineering?
+        params[:mode] = :engineering
+        params.delete :sci_int_digits
+      end
+      params
+    end
+
+    def to_s
+      "Mode[#{parameters(true).inspect.unwrap('{}')}]"
+    end
+
+    def inspect
+      "Format::#{self}"
+    end
+
+    # Note: since Mode has no mutable attributes, default dup is OK
+    # otherwise we'd need to redefine it:
+    # def dup
+    #   Mode[parameters]
+    # end
+
+    private
+
+    def extract_options(*args)
+      options = {}
+      args = args.first if args.size == 1 && args.first.kind_of?(Array)
+      args.each do |arg|
+        case arg
+        when Hash
+          options.merge! arg
+        when Symbol
+          options[:mode] = arg
+        when Format::Mode
+          options.merge! arg.parameters
+        else
+          raise "Invalid Mode definition"
+        end
+      end
+      options
+    end
+
+  end
+
+end

data/lib/numerals/format/notation.rb

@@ -0,0 +1,51 @@
+module Numerals
+
+  class Format
+
+    class Notation
+
+      def initialize(format)
+        @format = format
+      end
+
+      attr_reader :format
+
+      def assemble(output, text_parts)
+        raise "assemble must be implemented in Notation derived class #{self.class}"
+      end
+
+      def disassemble(text)
+        raise "disassemble must be implemented in Notation derived class #{self.class}"
+      end
+
+    end
+
+    @notations = {}
+
+    def self.define_notation(id, notation_class)
+      unless notation_class.class == Class && notation_class.superclass == Notation
+        raise "Notation class must be derived from Format::Notation"
+      end
+      @notations[id] = notation_class
+    end
+
+    def self.notation(id, format)
+      @notations[id].new(format) || raise("Unknown notation #{id.inspect}")
+    end
+
+
+    def self.assemble(id, output, format, text_parts)
+      notation(id, format).assemble(output, text_parts)
+    end
+
+    def self.disassemble(id, format, text)
+      notation(id, format).disassemble(text)
+    end
+
+  end
+
+end
+
+require 'numerals/format/notations/text'
+require 'numerals/format/notations/latex'
+require 'numerals/format/notations/html'

data/lib/numerals/format/notations/html.rb

@@ -0,0 +1,53 @@
+require 'cgi'
+
+module Numerals
+
+  class Format
+
+    class HtmlNotation < Notation
+
+      def assemble(output, text_parts)
+        # 1.23<span style="text-decoration: overline">456</span> &times;10<sup>9</sup>
+        # Or alternative: use classes
+        # <span class=”numerals-num”>1.23<span class="numerals-rep">456</span> &times;10<span class="numerals-sup">9</span></span>
+        # .numerals-rep { text-decoration: overline; }
+        # .numerals-sup { vertical-align: super; }
+        if text_parts.special?
+          output << escape(text_parts.special)
+        else
+          output << escape(text_parts.sign)
+          output << escape(text_parts.integer) # or decide here if empty integer part is show as 0?
+          unless !text_parts.fractional? &&
+                 !text_parts.repeat? &&
+                 !format.symbols.show_point
+            output << escape(format.symbols.point)
+          end
+          output << escape(text_parts.fractional)
+          if text_parts.repeat
+            output << %(<span style="text-decoration: overline">#{escape(text_parts.repeat)}</span>)
+          end
+          if text_parts.exponent_value != 0 || format.mode.mode == :scientific
+            output << "&times;"
+            output << escape(text_parts.exponent_base)
+            output << "<sup>#{escape(text_parts.exponent)}</sup>"
+          end
+        end
+      end
+
+      private
+
+      def escape(text)
+        CGI.escapeHTML(text)
+      end
+
+      def unescape(text)
+        CGI.unescapeHTML(text)
+      end
+
+    end
+
+    define_notation :html, HtmlNotation
+
+  end
+
+end

data/lib/numerals/format/notations/latex.rb

@@ -0,0 +1,48 @@
+module Numerals
+
+  class Format
+
+    class LatexNotation < Notation
+
+      def assemble(output, text_parts)
+        # 1.23\overline{456}\times10^{9}
+        if text_parts.special?
+          output << text_parts.special
+        else
+          output << text_parts.sign
+          output << text_parts.integer # or decide here if empty integer part is shown as 0?
+          unless !text_parts.fractional? &&
+                 !text_parts.repeat? &&
+                 !format.symbols.show_point
+            output << format.symbols.point
+          end
+          output << text_parts.fractional
+          if text_parts.repeat?
+            output << "\\overline{#{text_parts.repeat}}"
+          end
+          if text_parts.exponent_value != 0 || format.mode.mode == :scientific
+            output << "\\times"
+            output << text_parts.exponent_base
+            output << "^"
+            output << "{#{text_parts.exponent}}"
+          end
+        end
+      end
+
+      private
+
+      def escape(text)
+        text.gsub('\\', '\\\\')
+      end
+
+      def unescape(text)
+        text.gsub('\\\\', '\\')
+      end
+
+    end
+
+    define_notation :latex, LatexNotation
+
+  end
+
+end