money2 7.0.0.rc1

data/lib/money/bank/single_currency.rb

@@ -0,0 +1,25 @@
+require 'money/bank/base'
+
+class Money
+  module Bank
+    # Raised when trying to exchange currencies
+    class DifferentCurrencyError < Error; end
+
+    # Class to ensure client code is operating in a single currency
+    # by raising if an exchange attempts to happen.
+    #
+    # This is useful when an application uses multiple currencies but
+    # it usually deals with only one currency at a time so any arithmetic
+    # where exchanges happen are erroneous. Using this as the default bank
+    # means that that these mistakes don't silently do the wrong thing.
+    class SingleCurrency < Base
+
+      # Raises a DifferentCurrencyError to remove possibility of accidentally
+      # exchanging currencies
+      def exchange_with(from, to_currency, &block)
+        raise DifferentCurrencyError,
+          "No exchanging of currencies allowed: #{from.currency} to #{to_currency}"
+      end
+    end
+  end
+end

data/lib/money/bank/variable_exchange.rb

@@ -0,0 +1,252 @@
+require 'money/bank/base'
+require 'money/rates_store/memory'
+require 'json'
+require 'yaml'
+
+class Money
+  module Bank
+    # Thrown when an unknown rate format is requested.
+    class UnknownRateFormat < StandardError; end
+
+    # Class for aiding in exchanging money between different currencies. By
+    # default, the +Money+ class uses an object of this class (accessible
+    # through +Money#bank+) for performing currency exchanges.
+    #
+    # By default, +Money::Bank::VariableExchange+ has no knowledge about
+    # conversion rates. One must manually specify them with +add_rate+, after
+    # which one can perform exchanges with +#exchange_with+.
+    #
+    # Exchange rates are stored in memory using +Money::RatesStore::Memory+ by default.
+    # Pass custom rates stores for other types of storage (file, database, etc)
+    #
+    # @example
+    #   bank = Money::Bank::VariableExchange.new
+    #   bank.add_rate("USD", "CAD", 1.24515)
+    #   bank.add_rate("CAD", "USD", 0.803115)
+    #
+    #   c1 = Money.new(100_00, "USD")
+    #   c2 = Money.new(100_00, "CAD")
+    #
+    #   # Exchange 100 USD to CAD:
+    #   bank.exchange_with(c1, "CAD") #=> #<Money fractional:12451 currency:CAD>
+    #
+    #   # Exchange 100 CAD to USD:
+    #   bank.exchange_with(c2, "USD") #=> #<Money fractional:8031 currency:USD>
+    #
+    #   # With custom exchange rates storage
+    #   redis_store = MyCustomRedisStore.new(host: 'localhost:6379')
+    #   bank = Money::Bank::VariableExchange.new(redis_store)
+    #   # Store rates in redis
+    #   bank.add_rate 'USD', 'CAD', 0.98
+    #   # Get rate from redis
+    #   bank.get_rate 'USD', 'CAD'
+    class VariableExchange < Base
+
+      attr_reader :mutex, :store
+
+      # Available formats for importing/exporting rates.
+      RATE_FORMATS = [:json, :ruby, :yaml].freeze
+      SERIALIZER_SEPARATOR = '_TO_'.freeze
+      FORMAT_SERIALIZERS = {:json => JSON, :ruby => Marshal, :yaml => YAML}.freeze
+
+      # Initializes a new +Money::Bank::VariableExchange+ object.
+      # It defaults to using an in-memory, thread safe store instance for
+      # storing exchange rates.
+      #
+      # @param [RateStore] st An exchange rate store, used to persist exchange rate pairs.
+      # @yield [n] Optional block to use when rounding after exchanging one
+      #  currency for another. See +Money::bank::base+
+      def initialize(st = Money::RatesStore::Memory.new, &block)
+        @store = st
+        super(&block)
+      end
+
+      def marshal_dump
+        [store.marshal_dump, @rounding_method]
+      end
+
+      def marshal_load(arr)
+        store_info = arr[0]
+        @store = store_info.shift.new(*store_info)
+        @rounding_method = arr[1]
+      end
+
+      # Exchanges the given +Money+ object to a new +Money+ object in
+      # +to_currency+.
+      #
+      # @param  [Money] from
+      #         The +Money+ object to exchange.
+      # @param  [Currency, String, Symbol] to_currency
+      #         The currency to exchange to.
+      #
+      # @yield [n] Optional block to use when rounding after exchanging one
+      #  currency for another.
+      # @yieldparam [Float] n The resulting float after exchanging one currency
+      #  for another.
+      # @yieldreturn [Integer]
+      #
+      # @return [Money]
+      #
+      # @raise +Money::Bank::UnknownRate+ if the conversion rate is unknown.
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.add_rate("USD", "CAD", 1.24515)
+      #   bank.add_rate("CAD", "USD", 0.803115)
+      #
+      #   c1 = Money.new(100_00, "USD")
+      #   c2 = Money.new(100_00, "CAD")
+      #
+      #   # Exchange 100 USD to CAD:
+      #   bank.exchange_with(c1, "CAD") #=> #<Money fractional:12451 currency:CAD>
+      #
+      #   # Exchange 100 CAD to USD:
+      #   bank.exchange_with(c2, "USD") #=> #<Money fractional:8031 currency:USD>
+      def exchange_with(from, to_currency, round_mode = nil, &block)
+        to_currency = Currency.wrap(to_currency)
+        return from if from.currency == to_currency
+        rate = get_rate(from.currency, to_currency)
+        unless rate
+          raise UnknownRate, "No conversion rate known for " \
+            "'#{from.currency}' -> '#{to_currency}'"
+        end
+        rate = BigDecimal.new(rate.to_s) unless rate.is_a?(BigDecimal)
+        new_amount = round(from.to_d * rate, to_currency, round_mode, &block)
+        from.send(:build_new, new_amount, to_currency)
+      end
+
+      # Registers a conversion rate and returns it (uses +#set_rate+).
+      # Delegates to +Money::RatesStore::Memory+
+      #
+      # @param [Currency, String, Symbol] from Currency to exchange from.
+      # @param [Currency, String, Symbol] to Currency to exchange to.
+      # @param [Numeric] rate Rate to use when exchanging currencies.
+      #
+      # @return [Numeric]
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.add_rate("USD", "CAD", 1.24515)
+      #   bank.add_rate("CAD", "USD", 0.803115)
+      def add_rate(from, to, rate)
+        set_rate(from, to, rate)
+      end
+
+      # Set the rate for the given currencies.
+      # access.
+      # Delegates to +Money::RatesStore::Memory+
+      #
+      # @param [Currency, String, Symbol] from Currency to exchange from.
+      # @param [Currency, String, Symbol] to Currency to exchange to.
+      # @param [Numeric] rate Rate to use when exchanging currencies.
+      # @param [Hash] opts Options hash to set special parameters. Backwards compatibility only.
+      #
+      # @return [Numeric]
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.set_rate("USD", "CAD", 1.24515)
+      #   bank.set_rate("CAD", "USD", 0.803115)
+      def set_rate(from, to, rate, opts = {})
+        store.add_rate(Currency.wrap(from).code, Currency.wrap(to).code, rate)
+      end
+
+      # Retrieve the rate for the given currencies.
+      # data access.
+      # Delegates to +Money::RatesStore::Memory+
+      #
+      # @param [Currency, String, Symbol] from Currency to exchange from.
+      # @param [Currency, String, Symbol] to Currency to exchange to.
+      # @param [Hash] opts Options hash to set special parameters. Backwards compatibility only.
+      #
+      # @return [Numeric]
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.set_rate("USD", "CAD", 1.24515)
+      #   bank.set_rate("CAD", "USD", 0.803115)
+      #
+      #   bank.get_rate("USD", "CAD") #=> 1.24515
+      #   bank.get_rate("CAD", "USD") #=> 0.803115
+      def get_rate(from, to, opts = {})
+        store.get_rate(Currency.wrap(from).code, Currency.wrap(to).code)
+      end
+
+      # Return the known rates as a string in the format specified. If +file+
+      # is given will also write the string out to the file specified.
+      # Available formats are +:json+, +:ruby+ and +:yaml+.
+      #
+      # @param [Symbol] format Request format for the resulting string.
+      # @param [String] file Optional file location to write the rates to.
+      # @param [Hash] opts Options hash to set special parameters. Backwards compatibility only.
+      #
+      # @return [String]
+      #
+      # @raise +Money::Bank::UnknownRateFormat+ if format is unknown.
+      #
+      # @example
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.set_rate("USD", "CAD", 1.24515)
+      #   bank.set_rate("CAD", "USD", 0.803115)
+      #
+      #   s = bank.export_rates(:json)
+      #   s #=> "{\"USD_TO_CAD\":1.24515,\"CAD_TO_USD\":0.803115}"
+      def export_rates(format, file = nil, opts = {})
+        raise Money::Bank::UnknownRateFormat unless
+          RATE_FORMATS.include? format
+
+        store.transaction do
+          s = FORMAT_SERIALIZERS[format].dump(rates)
+
+          unless file.nil?
+            File.open(file, "w") {|f| f.write(s) }
+          end
+
+          s
+        end
+      end
+
+      # This should be deprecated.
+      def rates
+        store.each_rate.each_with_object({}) do |(from,to,rate),hash|
+          hash[[from, to].join(SERIALIZER_SEPARATOR)] = rate
+        end
+      end
+
+      # Loads rates provided in +s+ given the specified format. Available
+      # formats are +:json+, +:ruby+ and +:yaml+.
+      # Delegates to +Money::RatesStore::Memory+
+      #
+      # @param [Symbol] format The format of +s+.
+      # @param [String] s The rates string.
+      # @param [Hash] opts Options hash to set special parameters. Backwards compatibility only.
+      #
+      # @return [self]
+      #
+      # @raise +Money::Bank::UnknownRateFormat+ if format is unknown.
+      #
+      # @example
+      #   s = "{\"USD_TO_CAD\":1.24515,\"CAD_TO_USD\":0.803115}"
+      #   bank = Money::Bank::VariableExchange.new
+      #   bank.import_rates(:json, s)
+      #
+      #   bank.get_rate("USD", "CAD") #=> 1.24515
+      #   bank.get_rate("CAD", "USD") #=> 0.803115
+      def import_rates(format, s, opts = {})
+        raise Money::Bank::UnknownRateFormat unless
+          RATE_FORMATS.include? format
+
+        store.transaction do
+          data = FORMAT_SERIALIZERS[format].load(s)
+
+          data.each do |key, rate|
+            from, to = key.split(SERIALIZER_SEPARATOR)
+            store.add_rate from, to, rate
+          end
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/money/class_attribute.rb

@@ -0,0 +1,26 @@
+class Money
+  module ClassAttribute
+    # Simple version of ActiveSupport's class_attribute. Defines only class-methods,
+    # does not support any options.
+    #
+    # :api: private
+    def class_attribute(*attrs)
+      attrs.each do |name|
+        # singleton_class.class_eval do
+        #   define_method(name) { nil }
+        #   define_method("#{name}=") do |val|
+        #     remove_method(name)
+        #     define_method(name) { val }
+        #   end
+        # end
+        define_singleton_method(name) { nil }
+        define_singleton_method("#{name}=") do |val|
+          singleton_class.class_eval do
+            remove_method(name) if instance_methods(false).include?(name)
+            define_method(name) { val }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/money/currency.rb

@@ -0,0 +1,402 @@
+# encoding: utf-8
+
+require "json"
+require "money/currency/loader"
+
+class Money
+
+  # Represents a specific currency unit.
+  #
+  # @see http://en.wikipedia.org/wiki/Currency
+  # @see http://iso4217.net/
+  class Currency
+    include Comparable
+    extend Enumerable
+
+    autoload :Heuristics, 'money/currency/heuristics'
+
+    # Keeping cached instances in sync between threads
+    @@monitor = Monitor.new
+
+    # Thrown when an unknown currency is requested.
+    class UnknownCurrency < ArgumentError; end
+
+    class << self
+      def new(code)
+        code = prepare_code(code)
+        instances[code] || synchronize { instances[code] ||= super }
+      end
+
+      def instances
+        @instances ||= {}
+      end
+
+      def synchronize(&block)
+        @@monitor.synchronize(&block)
+      end
+
+      # Lookup a currency with given +code+ an returns a +Currency+ instance on
+      # success, +nil+ otherwise.
+      #
+      # @param [String, Symbol, #to_s] code Used to look into +table+ and
+      # retrieve the applicable attributes.
+      #
+      # @return [Money::Currency]
+      #
+      # @example
+      #   Money::Currency.find(:eur) #=> #<Money::Currency id: eur ...>
+      #   Money::Currency.find(:foo) #=> nil
+      def find(code)
+        new(code)
+      rescue UnknownCurrency
+        nil
+      end
+
+      # Bypasses call to Heuristics module, so it can be lazily loaded.
+      def analyze(str)
+        Heuristics.analyze(str, self)
+      end
+
+      # Lookup a currency with given +num+ as an ISO 4217 numeric and returns an
+      # +Currency+ instance on success, +nil+ otherwise.
+      #
+      # @param [#to_s] num used to look into +table+ in +iso_numeric+ and find
+      # the right currency code.
+      #
+      # @return [Money::Currency]
+      #
+      # @example
+      #   Money::Currency.find_by_iso_numeric(978) #=> #<Money::Currency id: eur ...>
+      #   Money::Currency.find_by_iso_numeric('001') #=> nil
+      def find_by_iso_numeric(num)
+        num = num.to_i
+        code, _ = table.find { |_, currency| currency[:iso_numeric] == num }
+        new(code) if code
+      end
+
+      # Wraps the object in a +Currency+ unless it's already a +Currency+
+      # object.
+      #
+      # @param [Object] object The object to attempt and wrap as a +Currency+
+      # object.
+      #
+      # @return [Money::Currency]
+      #
+      # @example
+      #   c1 = Money::Currency.new(:usd)
+      #   Money::Currency.wrap(nil)   #=> nil
+      #   Money::Currency.wrap(c1)    #=> #<Money::Currency id: usd ...>
+      #   Money::Currency.wrap("usd") #=> #<Money::Currency id: usd ...>
+      def wrap(object)
+        if object.is_a?(self)
+          object
+        else
+          object && new(object)
+        end
+      end
+
+      # List of known currencies.
+      #
+      # == monetary unit
+      # The standard unit of value of a currency, as the dollar in the United States or the peso in Mexico.
+      # http://www.answers.com/topic/monetary-unit
+      # == fractional monetary unit, subunit
+      # A monetary unit that is valued at a fraction (usually one hundredth) of the basic monetary unit
+      # http://www.answers.com/topic/fractional-monetary-unit-subunit
+      #
+      # See http://en.wikipedia.org/wiki/List_of_circulating_currencies and
+      # http://search.cpan.org/~tnguyen/Locale-Currency-Format-1.28/Format.pm
+      def table
+        @table ||= synchronize { Loader.load_all }
+      end
+
+      # List the currencies imported and registered
+      # @return [Array]
+      #
+      # @example
+      #   Money::Currency.all()
+      #   [#<Currency ..USD>, #<Currency ..CAD>, #<Currency ..EUR>]...
+      def all
+        table.keys.map do |code|
+          new(code).tap do |x|
+            unless x.priority
+              raise "Can't call Currency.all - currency '#{code}' is missing priority"
+            end
+          end
+        end.sort_by(&:priority)
+      end
+
+      # We need a string-based validator before creating an unbounded number of
+      # symbols.
+      # http://www.randomhacks.net/articles/2007/01/20/13-ways-of-looking-at-a-ruby-symbol#11
+      # https://github.com/RubyMoney/money/issues/132
+      #
+      # @return [Set]
+      def codes
+        @codes ||= Set.new(table.keys)
+      end
+
+      # Register a new currency
+      #
+      # @param data [Hash] information about the currency
+      # @option priority [Numeric] a numerical value you can use to sort/group
+      #   the currency list
+      # @option code [String] the international 3-letter code as defined
+      #   by the ISO 4217 standard
+      # @option iso_numeric [Integer] the international 3-digit code as
+      #   defined by the ISO 4217 standard
+      # @option name [String] the currency name
+      # @option symbol [String] the currency symbol (UTF-8 encoded)
+      # @option subunit [String] the name of the fractional monetary unit
+      # @option subunit_to_unit [Numeric] the proportion between the unit and
+      #   the subunit
+      # @option separator [String] character between the whole and fraction
+      #   amounts
+      # @option delimiter [String] character between each thousands place
+      def register(data)
+        code = prepare_code(data.fetch(:code))
+        synchronize do
+          instances.delete(code)
+          table[code] = data
+        end
+        @codes = nil
+      end
+
+      # Unregister a currency.
+      #
+      # @param [Object] data A Hash with the key `:code`, or the ISO code
+      #   as a String or Symbol.
+      #
+      # @return [Boolean] true if the currency previously existed, false
+      #   if it didn't.
+      def unregister(data)
+        data = data.fetch(:code) if data.is_a?(Hash)
+        code = prepare_code(data)
+        existed = synchronize do
+          instances.delete(code)
+          table.delete(code)
+        end
+        @codes = nil if existed
+        !!existed
+      end
+
+      # Reset all preloaded data, so it will be loaded from config files again.
+      def reset
+        synchronize do
+          @table = nil
+          @instances = nil
+          @codes = nil
+        end
+      end
+
+      # Keeps only given currencies, and clears any data about others.
+      def keep_only(*codes)
+        to_remove = table.keys - codes.map { |x| prepare_code(x) }
+        synchronize do
+          @codes = nil
+          to_remove.each do |code|
+            instances.delete(code)
+            table.delete(code)
+          end
+        end
+      end
+
+      def each(&block)
+        all.each(&block)
+      end
+
+      # Cache decimal places for subunit_to_unit values. Common ones pre-cached.
+      def decimal_places_cache
+        @decimal_places_cache ||= Hash.new { |h, k| h[k] = Math.log10(k).ceil }
+      end
+
+      def prepare_code(code)
+        code.to_s.upcase
+      end
+    end
+
+    # @!attribute [r] id
+    #   @return [Symbol] The symbol used to identify the currency, usually THE
+    #     lowercase +code+ attribute.
+    # @!attribute [r] priority
+    #   @return [Integer] A numerical value you can use to sort/group the
+    #     currency list.
+    # @!attribute [r] code
+    #   @return [String] The international 3-letter code as defined by the ISO
+    #     4217 standard.
+    # @!attribute [r] iso_numeric
+    #   @return [String] The international 3-numeric code as defined by the ISO
+    #     4217 standard.
+    # @!attribute [r] name
+    #   @return [String] The currency name.
+    # @!attribute [r] symbol
+    #   @return [String] The currency symbol (UTF-8 encoded).
+    # @!attribute [r] disambiguate_symbol
+    #   @return [String] Alternative currency used if symbol is ambiguous
+    # @!attribute [r] html_entity
+    #   @return [String] The html entity for the currency symbol
+    # @!attribute [r] subunit
+    #   @return [String] The name of the fractional monetary unit.
+    # @!attribute [r] subunit_to_unit
+    #   @return [Integer] The proportion between the unit and the subunit
+    # @!attribute [r] decimal_mark
+    #   @return [String] The decimal mark, or character used to separate the
+    #     whole unit from the subunit.
+    # @!attribute [r] thousands_separator
+    #   @return [String] The character used to separate thousands grouping of
+    #     the whole unit.
+    # @!attribute [r] symbol_first
+    #   @return [Boolean] Should the currency symbol precede the amount, or
+    #     should it come after?
+    # @!attribute [r] smallest_denomination
+    #   @return [Integer] Smallest amount of cash possible (in the subunit of
+    #     this currency)
+
+    ATTRS = %w(
+      id
+      alternate_symbols
+      code
+      decimal_mark
+      disambiguate_symbol
+      html_entity
+      iso_numeric
+      name
+      priority
+      smallest_denomination
+      subunit
+      subunit_to_unit
+      symbol
+      symbol_first
+      thousands_separator
+    ).map(&:to_sym).freeze
+
+    attr_reader(*ATTRS)
+
+    alias_method :to_sym, :id
+    alias_method :to_s, :code
+    alias_method :to_str, :code
+    alias_method :symbol_first?, :symbol_first
+    alias_method :separator, :decimal_mark
+    alias_method :delimiter, :thousands_separator
+    alias_method :eql?, :==
+
+    # Create a new +Currency+ object.
+    #
+    # @param [String, Symbol, #to_s] id Used to look into +table+ and retrieve
+    #  the applicable attributes.
+    #
+    # @return [Money::Currency]
+    #
+    # @example
+    #   Money::Currency.new(:usd) #=> #<Money::Currency id: usd ...>
+    def initialize(code)
+      data = self.class.table[code]
+      raise UnknownCurrency, "Unknown currency '#{code}'" unless data
+      @id = code.to_sym
+      (ATTRS - [:id]).each do |attr|
+        instance_variable_set("@#{attr}", data[attr])
+      end
+      @alternate_symbols ||= []
+    end
+
+    # Compares +self+ with +other_currency+ against the value of +priority+
+    # attribute.
+    #
+    # @param [Money::Currency] other_currency The currency to compare to.
+    #
+    # @return [-1,0,1] -1 if less than, 0 is equal to, 1 if greater than
+    #
+    # @example
+    #   c1 = Money::Currency.new(:usd)
+    #   c2 = Money::Currency.new(:jpy)
+    #   c1 <=> c2 #=> 1
+    #   c2 <=> c1 #=> -1
+    #   c1 <=> c1 #=> 0
+    def <=>(other_currency)
+      # <=> returns nil when one of the values is nil
+      comparison = priority <=> other_currency.priority || 0
+      if comparison == 0
+        id <=> other_currency.id
+      else
+        comparison
+      end
+    end
+
+    # Compares +self+ with +other_currency+ and returns +true+ if the are the
+    # same or if their +id+ attributes match.
+    #
+    # @param [Money::Currency] other_currency The currency to compare to.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   c1 = Money::Currency.new(:usd)
+    #   c2 = Money::Currency.new(:jpy)
+    #   c1 == c1 #=> true
+    #   c1 == c2 #=> false
+    def ==(other_currency)
+      if other_currency.is_a?(Currency)
+        id == other_currency.id
+      else
+        code == other_currency.to_s.upcase
+      end
+    end
+
+    # Returns a Fixnum hash value based on the +id+ attribute in order to use
+    # functions like & (intersection), group_by, etc.
+    #
+    # @return [Fixnum]
+    #
+    # @example
+    #   Money::Currency.new(:usd).hash #=> 428936
+    def hash
+      id.hash
+    end
+
+    # Returns a human readable representation.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Money::Currency.new(:usd) #=> #<Currency id: usd ...>
+    def inspect
+      vals = ATTRS.map { |field| "#{field}: #{public_send(field).inspect}" }
+      "#<#{self.class.name} #{vals.join(', ')}>"
+    end
+
+    # Conversion to +self+.
+    #
+    # @return [self]
+    def to_currency
+      self
+    end
+
+    # Returns currency symbol or code for currencies with no symbol.
+    #
+    # @return [String]
+    def symbol_or_code
+      symbol || code
+    end
+
+    def iso?
+      !!iso_numeric
+    end
+
+    # Returns the relation between subunit and unit as a base 10 exponent.
+    #
+    # Note that MGA and MRO are exceptions and are rounded to 1
+    # @see https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+    #
+    # @return [Fixnum]
+    def exponent
+      Math.log10(subunit_to_unit).round
+    end
+
+    # The number of decimal places needed.
+    #
+    # @return [Integer]
+    def decimal_places
+      self.class.decimal_places_cache[subunit_to_unit]
+    end
+  end
+end