shopify-money 0.16.0 → 1.0.2.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9919cf2d14833f204c05a9642efb7a48bb23822c70c48cf523ccbc68c3e7491
-  data.tar.gz: d73bd65e6cb49ee8f5be7add57683274bb006fbfd0ec61aec566385fd92d50f6
+  metadata.gz: 23562c524ba9f0d8219d01779505a75309d8825ed8f8839f1efdd71fbf5a1e89
+  data.tar.gz: ca1b6ea90e7a556970d135bbebc74c9cf6eb417cd475607ef58923751e2969b3
 SHA512:
-  metadata.gz: b3dc0c02cee6598d2369ce472a5df01dfb3528cfb45f517394ab7c29b059338b8d65d10c03ae397a4ecdff98a7987a61e0312b894947b728e1ed32078b726086
-  data.tar.gz: 1e7cec90da29c1327fdf64984f34e7b6fa01282eb7a0c2e3eda6482d688b06d148b7b7bff760555e3a7d7302ec8b20079ad468cd7c02dabb83c7e9a0aeb0a1f2
+  metadata.gz: 81f2eb5e04d1cf082cf3eaadd5d609d4abcdef1841d1dde9b2eee68c0b8e570b7c0c72dd0a2a05c7213b0c611a267a2b6fbca044d2a86711765aa91f8e2ea763
+  data.tar.gz: cf7864860eb1fab370902861200b23150d08b1d135f614896a9c32fe20ea9e1edc7070563325c4a102a4af64c986c308892e13aefe9ad2590e4ac75d17f30a22

data/README.md

@@ -18,7 +18,11 @@ money_column expects a DECIMAL(21,3) database field.
 
 ## Installation
 
-    gem 'shopify-money', require: 'money'
+    gem 'shopify-money'
+
+## Upgrading to v1.0
+
+see instructions and breaking changes: https://github.com/Shopify/money/blob/master/UPGRADING.md
 
 ## Usage
 
@@ -77,7 +81,9 @@ By default `Money` defaults to Money::NullCurrency as its currency. This is a
 global variable that can be changed using:
 
 ``` ruby
-Money.default_currency = Money::Currency.new("USD")
+Money.configure do |config|
+  config.default_currency = Money::Currency.new("USD")
+end
 ```
 
 In web apps you might want to set the default currency on a per request basis.

data/UPGRADING.md

@@ -0,0 +1,59 @@
+## Upgrading to v1.0
+
+In an initializer add the following
+```ruby
+Money.configure do |config|
+  config.legacy_default_currency!
+  config.legacy_deprecations!
+  config.legacy_json_format!
+  #...
+end
+```
+
+Remove each legacy setting making sure your app functions as expected.
+
+Replace `Money.parse` with `Money::Parser::Fuzzy.parse`.
+
+### Legacy support
+
+#### legacy_default_currency!
+
+By enabling this setting your app will accept money object that are missing a currency
+
+```ruby
+Money.new(1) #=> value: 1, currency: XXX
+```
+
+#### legacy_deprecations!
+
+invalid money values return zero
+```ruby
+Money.new('a', 'USD') #=> Money.new(0, 'USD')
+```
+
+invalid currency is ignored
+```ruby
+Money.new(1, 'ABCD') #=> Money.new(1)
+```
+
+mathematical operations between objects are allowed
+```ruby
+Money.new(1, 'USD') + Money.new(1, 'CAD') #=> Money.new(2, 'USD')
+```
+
+parsing a string with invalid delimiters
+```ruby
+Money.parse('123*12') #=> Money.new(123)
+```
+
+#### legacy_json_format!
+
+to_json will return only the value (no currency)
+```ruby
+# with legacy_json_format!
+money.to_json #=> "1"
+
+# without
+money.to_json #=> { value: 1, currency: 'USD' }
+```
+

data/config/currency_historic.yml

@@ -73,6 +73,20 @@ mtl:
   thousands_separator: ","
   iso_numeric: '470'
   smallest_denomination: 1
+std:
+  priority: 100
+  iso_code: STD
+  name: São Tomé and Príncipe Dobra
+  symbol: Db
+  alternate_symbols: []
+  subunit: Cêntimo
+  subunit_to_unit: 100
+  symbol_first: false
+  html_entity: ''
+  decimal_mark: "."
+  thousands_separator: ","
+  iso_numeric: '678'
+  smallest_denomination: 10000
 tmm:
   priority: 100
   iso_code: TMM

data/config/currency_iso.yml

@@ -2029,9 +2029,9 @@ ssp:
   thousands_separator: ","
   iso_numeric: '728'
   smallest_denomination: 5
-std:
+stn:
   priority: 100
-  iso_code: STD
+  iso_code: STN
   name: São Tomé and Príncipe Dobra
   symbol: Db
   alternate_symbols: []
@@ -2041,8 +2041,8 @@ std:
   html_entity: ''
   decimal_mark: "."
   thousands_separator: ","
-  iso_numeric: '678'
-  smallest_denomination: 10000
+  iso_numeric: '930'
+  smallest_denomination: 1
 svc:
   priority: 100
   iso_code: SVC
@@ -2304,6 +2304,24 @@ uzs:
   thousands_separator: ","
   iso_numeric: '860'
   smallest_denomination: 100
+ved:
+  priority: 100
+  iso_code: VED
+  name: Venezuelan Bolívar soberano
+  symbol: Bs.D.
+  alternate_symbols: []
+  subunit: Céntimo
+  subunit_to_unit: 100
+  symbol_first: true
+  html_entity: ''
+  decimal_mark: ","
+  thousands_separator: "."
+  iso_numeric: '926'
+  # "On 1 Oct 2021, [...] another (redenomination) happened, but called 'Nueva expresión monetaria', 
+  # or new monetary expression, which removed 6 zeroes from the currency without affecting its denomination."
+  # The VED has banknotes in denominations of 5, 10, 20, 50, and 100, and coins in 50 céntimos and 1 Bs.D.
+  # Source: https://en.wikipedia.org/wiki/Venezuelan_bol%C3%ADvar
+  smallest_denomination: 1
 ves:
   priority: 100
   iso_code: VES

data/lib/money/allocator.rb

@@ -7,6 +7,8 @@ class Money
       super
     end
 
+    ONE = BigDecimal("1")
+
     # Allocates money between different parties without losing pennies.
     # After the mathematically split has been performed, left over pennies will
     # be distributed round-robin amongst the parties. This means that parties
@@ -43,7 +45,7 @@ class Money
       splits.map!(&:to_r)
       allocations = splits.inject(0, :+)
 
-      if (allocations - BigDecimal("1")) > Float::EPSILON
+      if (allocations - ONE) > Float::EPSILON
         raise ArgumentError, "splits add to more than 100%"
       end
 

data/lib/money/config.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class Money
+  class Config
+    attr_accessor :default_currency, :legacy_json_format, :legacy_deprecations
+
+    def legacy_default_currency!
+      @default_currency ||= Money::NULL_CURRENCY
+    end
+
+    def legacy_deprecations!
+      @legacy_deprecations = true
+    end
+
+    def legacy_json_format!
+      @legacy_json_format = true
+    end
+
+    def initialize
+      @default_currency = nil
+      @legacy_json_format = false
+      @legacy_deprecations = false
+    end
+  end
+end

data/lib/money/core_extensions.rb

@@ -14,6 +14,6 @@ end
 #   '100.37'.to_money => #<Money @cents=10037>
 class String
   def to_money(currency = nil)
-    Money.parse(self, currency)
+    Money::Parser::Fuzzy.parse(self, currency)
   end
 end

data/lib/money/helpers.rb

@@ -28,7 +28,7 @@ class Money
         when Rational
           BigDecimal(num, MAX_DECIMAL)
         when String
-          decimal = BigDecimal(num, exception: false)
+          decimal = BigDecimal(num, exception: !Money.config.legacy_deprecations)
           return decimal if decimal
 
           Money.deprecate("using Money.new('#{num}') is deprecated and will raise an ArgumentError in the next major release")
@@ -46,7 +46,7 @@ class Money
         currency
       when nil, ''
         default = Money.current_currency || Money.default_currency
-        raise(ArgumentError, 'missing currency') if default.nil? || default == ''
+        raise(Money::Currency::UnknownCurrency, 'missing currency') if default.nil? || default == ''
         value_to_currency(default)
       when 'xxx', 'XXX'
         Money::NULL_CURRENCY
@@ -54,8 +54,12 @@ class Money
         begin
           Currency.find!(currency)
         rescue Money::Currency::UnknownCurrency => error
-          Money.deprecate(error.message)
-          Money::NULL_CURRENCY
+          if Money.config.legacy_deprecations
+            Money.deprecate(error.message)
+            Money::NULL_CURRENCY
+          else
+            raise error
+          end
         end
       else
         raise ArgumentError, "could not parse as currency #{currency.inspect}"

data/lib/money/money.rb

@@ -11,7 +11,14 @@ class Money
   def_delegators :@value, :zero?, :nonzero?, :positive?, :negative?, :to_i, :to_f, :hash
 
   class << self
-    attr_accessor :parser, :default_currency
+    extend Forwardable
+    attr_accessor :config
+    def_delegators :@config, :default_currency, :default_currency=
+
+    def configure
+      self.config ||= Config.new
+      yield(config) if block_given?
+    end
 
     def new(value = 0, currency = nil)
       value = Helpers.value_to_decimal(value)
@@ -26,10 +33,6 @@ class Money
     end
     alias_method :from_amount, :new
 
-    def parse(*args, **kwargs)
-      parser.parse(*args, **kwargs)
-    end
-
     def from_subunits(subunits, currency_iso, format: :iso4217)
       currency = Helpers.value_to_currency(currency_iso)
 
@@ -73,13 +76,8 @@ class Money
         Money.current_currency = old_currency
       end
     end
-
-    def default_settings
-      self.parser = MoneyParser
-      self.default_currency = Money::NULL_CURRENCY
-    end
   end
-  default_settings
+  configure
 
   def initialize(value, currency)
     raise ArgumentError if value.nan?
@@ -126,20 +124,27 @@ class Money
 
   def +(other)
     arithmetic(other) do |money|
+      return self if money.value == 0 && !no_currency?
       Money.new(value + money.value, calculated_currency(money.currency))
     end
   end
 
   def -(other)
     arithmetic(other) do |money|
+      return self if money.value == 0 && !no_currency?
       Money.new(value - money.value, calculated_currency(money.currency))
     end
   end
 
   def *(numeric)
     unless numeric.is_a?(Numeric)
-      Money.deprecate("Multiplying Money with #{numeric.class.name} is deprecated and will be removed in the next major release.")
+      if Money.config.legacy_deprecations
+        Money.deprecate("Multiplying Money with #{numeric.class.name} is deprecated and will be removed in the next major release.")
+      else
+        raise ArgumentError, "Money objects can only be multiplied by a Numeric"
+      end
     end
+    return self if numeric == 1
     Money.new(value.to_r * numeric, currency)
   end
 
@@ -198,8 +203,12 @@ class Money
 
     curr = Helpers.value_to_currency(curr)
     unless currency.compatible?(curr)
-      Money.deprecate("mathematical operation not permitted for Money objects with different currencies #{curr} and #{currency}. " \
-        "A Money::IncompatibleCurrencyError will raise in the next major release")
+      msg = "mathematical operation not permitted for Money objects with different currencies #{curr} and #{currency}"
+      if Money.config.legacy_deprecations
+        Money.deprecate("#{msg}. A Money::IncompatibleCurrencyError will raise in the next major release")
+      else
+        raise Money::IncompatibleCurrencyError, msg
+      end
     end
 
     self
@@ -209,14 +218,14 @@ class Money
     value
   end
 
-  def to_s(style = nil)
+  def to_fs(style = nil)
     units = case style
     when :legacy_dollars
       2
     when :amount, nil
       currency.minor_units
     else
-      raise ArgumentError, "Unexpected style: #{style}"
+      raise ArgumentError, "Unexpected format: #{style}"
     end
 
     rounded_value = value.round(units)
@@ -228,25 +237,41 @@ class Money
       sprintf("%s%d.%0#{units}d", sign, rounded_value.truncate, rounded_value.frac * (10 ** units))
     end
   end
+  alias_method :to_s, :to_fs
+  alias_method :to_formatted_s, :to_fs
 
-  def to_json(options = {})
-    to_s
+  def to_json(options = nil)
+    if (options.is_a?(Hash) && options.delete(:legacy_format)) || Money.config.legacy_json_format
+      to_s
+    else
+      as_json(options).to_json
+    end
   end
 
-  def as_json(*args)
-    to_s
+  def as_json(options = nil)
+    if (options.is_a?(Hash) && options.delete(:legacy_format)) || Money.config.legacy_json_format
+      to_s
+    else
+      { value: to_s(:amount), currency: currency.to_s }
+    end
   end
 
   def abs
-    Money.new(value.abs, currency)
+    abs = value.abs
+    return self if value == abs
+    Money.new(abs, currency)
   end
 
   def floor
-    Money.new(value.floor, currency)
+    floor = value.floor
+    return self if floor == value
+    Money.new(floor, currency)
   end
 
   def round(ndigits=0)
-    Money.new(value.round(ndigits), currency)
+    round = value.round(ndigits)
+    return self if round == value
+    Money.new(round, currency)
   end
 
   def fraction(rate)

data/lib/money/parser/accounting.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+class Money
+  module Parser
+    class Accounting < Fuzzy
+      def parse(input, currency = nil, **options)
+        # set () to mean negativity. ignore $
+        super(input.gsub(/\(\$?(.*?)\)/, '-\1'), currency, **options)
+      end
+    end
+  end
+end

data/lib/money/parser/fuzzy.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+class Money
+  module Parser
+    class Fuzzy
+      class MoneyFormatError < ArgumentError; end
+
+      MARKS = %w[. , · ’ ˙ '] + [' ']
+
+      ESCAPED_MARKS = Regexp.escape(MARKS.join)
+      ESCAPED_NON_SPACE_MARKS = Regexp.escape((MARKS - [' ']).join)
+      ESCAPED_NON_DOT_MARKS = Regexp.escape((MARKS - ['.']).join)
+      ESCAPED_NON_COMMA_MARKS = Regexp.escape((MARKS - [',']).join)
+
+      NUMERIC_REGEX = /(
+        [\+\-]?
+        [\d#{ESCAPED_NON_SPACE_MARKS}][\d#{ESCAPED_MARKS}]*
+      )/ix
+
+      # 1,234,567.89
+      DOT_DECIMAL_REGEX = /\A
+        [\+\-]?
+        (?:
+          (?:\d+)
+          (?:[#{ESCAPED_NON_DOT_MARKS}]\d{3})+
+          (?:\.\d{2,})?
+        )
+      \z/ix
+
+      # 1.234.567,89
+      COMMA_DECIMAL_REGEX = /\A
+        [\+\-]?
+        (?:
+          (?:\d+)
+          (?:[#{ESCAPED_NON_COMMA_MARKS}]\d{3})+
+          (?:\,\d{2,})?
+        )
+      \z/ix
+
+      # 12,34,567.89
+      INDIAN_NUMERIC_REGEX = /\A
+        [\+\-]?
+        (?:
+          (?:\d+)
+          (?:\,\d{2})+
+          (?:\,\d{3})
+          (?:\.\d{2})?
+        )
+      \z/ix
+
+      # 1,1123,4567.89
+      CHINESE_NUMERIC_REGEX = /\A
+        [\+\-]?
+        (?:
+          (?:\d+)
+          (?:\,\d{4})+
+          (?:\.\d{2})?
+        )
+      \z/ix
+
+      def self.parse(input, currency = nil, **options)
+        new.parse(input, currency, **options)
+      end
+
+      # Parses an input string and attempts to find the decimal separator based on certain heuristics, like the amount
+      # decimals for the fractional part a currency has or the incorrect notion a currency has a defined decimal
+      # separator (this is a property of the locale). While these heuristics can lead to the expected result for some
+      # cases, the other cases can lead to surprising results such as parsed amounts being 1000x larger than intended.
+      # @deprecated Use {LocaleAware.parse} or {Simple.parse} instead.
+      # @param input [String]
+      # @param currency [String, Money::Currency, nil]
+      # @param strict [Boolean]
+      # @return [Money]
+      # @raise [MoneyFormatError]
+      def parse(input, currency = nil, strict: false)
+        currency = Money::Helpers.value_to_currency(currency)
+        amount = extract_amount_from_string(input, currency, strict)
+        Money.new(amount, currency)
+      end
+
+      private
+
+      def extract_amount_from_string(input, currency, strict)
+        unless input.is_a?(String)
+          return input
+        end
+
+        if input.strip.empty?
+          return '0'
+        end
+
+        number = input.scan(NUMERIC_REGEX).flatten.first
+        number = number.to_s.strip
+
+        if number.empty?
+          if Money.config.legacy_deprecations && !strict
+            Money.deprecate("invalid money strings will raise in the next major release \"#{input}\"")
+            return '0'
+          else
+            raise MoneyFormatError, "invalid money string: #{input}"
+          end
+        end
+
+        marks = number.scan(/[#{ESCAPED_MARKS}]/).flatten
+        if marks.empty?
+          return number
+        end
+
+        if marks.size == 1
+          return normalize_number(number, marks, currency)
+        end
+
+        # remove end of string mark
+        number.sub!(/[#{ESCAPED_MARKS}]\z/, '')
+
+        if amount = number[DOT_DECIMAL_REGEX] || number[INDIAN_NUMERIC_REGEX] || number[CHINESE_NUMERIC_REGEX]
+          return amount.tr(ESCAPED_NON_DOT_MARKS, '')
+        end
+
+        if amount = number[COMMA_DECIMAL_REGEX]
+          return amount.tr(ESCAPED_NON_COMMA_MARKS, '').sub(',', '.')
+        end
+
+        if Money.config.legacy_deprecations && !strict
+          Money.deprecate("invalid money strings will raise in the next major release \"#{input}\"")
+        else
+          raise MoneyFormatError, "invalid money string: #{input}"
+        end
+
+        normalize_number(number, marks, currency)
+      end
+
+      def normalize_number(number, marks, currency)
+        digits = number.rpartition(marks.last)
+        digits.first.tr!(ESCAPED_MARKS, '')
+
+        if last_digits_decimals?(digits, marks, currency)
+          "#{digits.first}.#{digits.last}"
+        else
+          "#{digits.first}#{digits.last}"
+        end
+      end
+
+      def last_digits_decimals?(digits, marks, currency)
+        # Grouping marks are always different from decimal marks
+        # Example: 1,234,456
+        *other_marks, last_mark = marks
+        other_marks.uniq!
+        if other_marks.size == 1
+          return other_marks.first != last_mark
+        end
+
+        # Thousands always have more than 2 digits
+        # Example: 1,23 must be 1 dollar and 23 cents
+        if digits.last.size < 3
+          return !digits.last.empty?
+        end
+
+        # 0 before the final mark indicates last digits are decimals
+        # Example: 0,23
+        if digits.first.to_i.zero?
+          return true
+        end
+
+        # legacy support for 1.000 USD
+        if digits.last.size == 3 && digits.first.size <= 3 && currency.minor_units < 3
+          return false
+        end
+
+        # The last mark matches the one used by the provided currency to delimiter decimals
+        currency.decimal_mark == last_mark
+      end
+    end
+  end
+end

data/lib/money/parser/locale_aware.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+class Money
+  module Parser
+    class LocaleAware
+      @decimal_separator_resolver = nil
+
+      class << self
+        # The +Proc+ called to get the current locale decimal separator. In Rails apps this defaults to the same lookup
+        # ActionView's +number_to_currency+ helper will use to format the monetary amount for display.
+        def decimal_separator_resolver
+          @decimal_separator_resolver
+        end
+
+        # Set the default +Proc+ to determine the current locale decimal separator.
+        #
+        # @example
+        #   Money::Parser::LocaleAware.decimal_separator_resolver =
+        #     ->() { MyFormattingLibrary.current_locale.decimal.separator }
+        def decimal_separator_resolver=(proc)
+          @decimal_separator_resolver = proc
+        end
+
+        # Parses an input string, normalizing some non-ASCII characters to their equivalent ASCII, then discarding any
+        # character that is not a digit, hyphen-minus or the decimal separator. To prevent user confusion, make sure
+        # that formatted Money strings can be parsed back into equivalent Money objects.
+        #
+        # @param input [String]
+        # @param currency [String, Money::Currency]
+        # @param strict [Boolean]
+        # @param decimal_separator [String]
+        # @return [Money, nil]
+        def parse(input, currency, strict: false, decimal_separator: decimal_separator_resolver&.call)
+          raise ArgumentError, "decimal separator cannot be nil" unless decimal_separator
+
+          currency = Money::Helpers.value_to_currency(currency)
+          return unless currency
+
+          normalized_input = input
+            .tr('－０-９．，、､', '-0-9.,,,')
+            .gsub(/[^\d\-#{Regexp.escape(decimal_separator)}]/, '')
+            .gsub(decimal_separator, '.')
+          amount = BigDecimal(normalized_input, exception: false)
+          if amount
+            Money.new(amount, currency)
+          elsif strict
+            raise ArgumentError, "unable to parse input=\"#{input}\" currency=\"#{currency}\""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/money/parser/simple.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+class Money
+  module Parser
+    class Simple
+      SIGNED_DECIMAL_MATCHER = /\A-?\d*(?:\.\d*)?\z/.freeze
+
+      class << self
+        # Parses an input string using BigDecimal, it always expects a dot character as a decimal separator and
+        # generally does not accept other characters other than minus-hyphen and digits. It is useful for APIs, interop
+        # with other languages and other use cases where you expect well-formatted input and do not need to take user
+        # locale into consideration.
+        # @param input [String]
+        # @param currency [String, Money::Currency]
+        # @param strict [Boolean]
+        # @return [Money, nil]
+        def parse(input, currency, strict: false)
+          currency = Money::Helpers.value_to_currency(currency)
+          return unless currency
+
+          coerced = input.to_s
+          if SIGNED_DECIMAL_MATCHER.match?(coerced) && (amount = BigDecimal(coerced, exception: false))
+            Money.new(amount, currency)
+          elsif strict
+            raise ArgumentError, "unable to parse input=\"#{input}\" currency=\"#{currency}\""
+          end
+        end
+      end
+    end
+  end
+end