money 6.5.1 → 6.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e625dd2f1daa9df7fbe2c8c5ed8972c5bf69f9a
-  data.tar.gz: 50addb5ca7123aff716961c6e782d43846d90c55
+  metadata.gz: c65fe09cbae38c4022a53cdc0c6b5cba47e72930
+  data.tar.gz: 5de5a0732f90ab4af46ef801378a7a6161b5324d
 SHA512:
-  metadata.gz: 51736bea340dca0e23da25018aad574380bdfea0281e20aaf0af90c306f50d48be15ffb15136daff9caac4c5c6a5f563042c6703dc6403c83ce32fee85d42e30
-  data.tar.gz: 2b32b72aa148550d672ae639b0c9c96a13c5d3c35676fdf7649f130bd79a4d41880444d2d1b0fdbe3d442d840518fcf2e35bdb3156ddd46a8f1490f68e6ada24
+  metadata.gz: bba3d4bc1dfc26c28ed9e4720a815c0bf36c6dd0376c17a664cb70d066d5c436c29da795abade5bd61c0797808f5969f52fa696d7bfeb874333ad11411745583
+  data.tar.gz: 1a38008c4890e953e1002485fd1098c935ed370cf4e05648846327302d2202fed8adf96df22b37cb98abf7de5b36a8cc87bc7d168d7ab606f2d87a28d87e4f32

data/.travis.yml

@@ -1,4 +1,5 @@
 language: ruby
+sudo: false
 rvm:
   - 1.9.3
   - 2.0.0

data/AUTHORS

@@ -16,6 +16,7 @@ Bill DeRusha
 Bodaniel Jeanes
 Brian Jones
 bUg.
+Cade Truitt
 Casper Thomsen
 Chad Boyd
 Choongmin Lee
@@ -30,6 +31,7 @@ Edwin Vlieg
 Eloy
 Evan Alter
 Exoth
+Filipe Goncalves
 François Beausoleil
 François Klingler
 Francisco Trindade
@@ -68,10 +70,13 @@ Mateusz Wolsza
 Matias Korhonen
 Matt Jankowski
 Matthew McEachen
+Max Melentiev
 Michael J. Cohen
 Michael Irwin
 Michael Reinsch
+Michael Rodrigues
 Mikael Wikman
+Mike Herrera
 Mike Połétyn
 Musannif Zahir
 Neil Middleton
@@ -111,6 +116,8 @@ Tobias Schmidt
 Tom Lianza
 tommeier
 Troels Knak-Nielsen
+Tsyren Ochirov
 Wei Zhu
 Zubin Henner
 Бродяной Александр
+Douglas Miller

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Next release
 
+ - Fixed VariableExchange#exchange_with for big numbers.
+ - Add Currency symbol translation support
+ - `Currency.all` raises a more helpful error message
+   (`Currency::MissingAttributeError`)if a currency has no priority
  - `Currency` implements `Enumerable`.
  - `Currency#<=>` sorts alphabetically by `id` if the `priority`s are the same,
    and no longer raises an error if one of the priorities is missing.
@@ -16,6 +20,17 @@
    `.ca_dollar`, and `.euro`.
  - Add helper methods for British pounds: `Money.pound_sterling` and
    `Money.gbp`.
+ - Add `Money.from_amount` to create money from a value in units instead of
+   fractional units.
+ - Changed CHF symbol from 'Fr' to 'CHF'
+ - Changed CLF exponent from 0 to 4
+ - Changed CLP subunit_to_unit from 1 to 100
+ - Minor fixes to prevent warnings on unused variables and the redefinition of
+   `Money.default_currency`
+ - `Money#==` changed to acknowledge that 0 in one currency is equal to 0 in any currency.
+ - Changed KRW subunit_to_unit from 100 to 1
+ - Decouple exchange rates storage from bank objects and formalize storage public API. Default is `Money::RatesStore::Memory`.
+ - `Currency.new` now a singleton by its id
 
 ## 6.5.1
  - Fix format for BYR currency

data/README.md

@@ -79,9 +79,19 @@ Money.new(1000, "USD") - Money.new(200, "USD") == Money.new(800, "USD")
 Money.new(1000, "USD") / 5                     == Money.new(200, "USD")
 Money.new(1000, "USD") * 5                     == Money.new(5000, "USD")
 
+# Unit to subunit conversions
+Money.from_amount(5, "USD") == Money.new(500, "USD")  # 5 USD
+Money.from_amount(5, "JPY") == Money.new(5, "JPY")    # 5 JPY
+Money.from_amount(5, "TND") == Money.new(5000, "TND") # 5 TND
+
 # Currency conversions
 some_code_to_setup_exchange_rates
 Money.new(1000, "USD").exchange_to("EUR") == Money.new(some_value, "EUR")
+
+# Formatting (see Formatting section for more options)
+Money.new(100, "USD").format #=> "$1.00"
+Money.new(100, "GBP").format #=> "£1.00"
+Money.new(100, "EUR").format #=> "€1.00"
 ```
 
 ## Currency
@@ -233,11 +243,116 @@ Money.add_rate("USD", "EUR", 0.5)
 Money.new(1000, "EUR") + Money.new(1000, "USD") == Money.new(1500, "EUR")
 ```
 
-There is nothing stopping you from creating bank objects which scrapes
+### Exchange rate stores
+
+The default bank is initialized with an in-memory store for exchange rates.
+
+```ruby
+Money.default_bank = Money::Bank::VariableExchange.new(Money::RatesStore::Memory.new)
+```
+
+You can pass you own store implementation, ie. for storing and retrieving rates off a database, file, cache, etc.
+
+```ruby
+Money.default_bank = Money::Bank::VariableExchange.new(MyCustomStore.new)
+```
+
+Stores must implement the following interface:
+
+```ruby
+# Add new exchange rate.
+# @param [String] iso_from Currency ISO code. ex. 'USD'
+# @param [String] iso_to Currency ISO code. ex. 'CAD'
+# @param [Numeric] rate Exchange rate. ex. 0.0016
+#
+# @return [Numeric] rate.
+def add_rate(iso_from, iso_to, rate); end
+
+# Get rate. Must be idempotent. ie. adding the same rate must not produce duplicates.
+# @param [String] iso_from Currency ISO code. ex. 'USD'
+# @param [String] iso_to Currency ISO code. ex. 'CAD'
+#
+# @return [Numeric] rate.
+def get_rate(iso_from, iso_to); end
+
+# Iterate over rate tuples (iso_from, iso_to, rate)
+#
+# @yieldparam iso_from [String] Currency ISO string.
+# @yieldparam iso_to [String] Currency ISO string.
+# @yieldparam rate [Numeric] Exchange rate.
+#
+# @return [Enumerator]
+#
+# @example
+#   store.each_rate do |iso_from, iso_to, rate|
+#     puts [iso_from, iso_to, rate].join
+#   end
+def each_rate(&block); end
+
+# Wrap store operations in a thread-safe transaction
+# (or IO or Database transaction, depending on your implementation)
+#
+# @yield [n] Block that will be wrapped in transaction.
+#
+# @example
+#   store.transaction do
+#     store.add_rate('USD', 'CAD', 0.9)
+#     store.add_rate('USD', 'CLP', 0.0016)
+#   end
+def transaction(&block); end
+
+# Serialize store and its content to make Marshal.dump work.
+#
+# Returns an array with store class and any arguments needed to initialize the store in the current state.
+
+# @return [Array] [class, arg1, arg2]
+def marshal_dump; end
+```
+
+The following example implements an `ActiveRecord` store to save exchange rates to a database.
+
+```ruby
+# DB columns :from[String], :to[String], :rate[Float]
+
+class ExchangeRate < ActiveRecord::Base
+  def self.get_rate(from_iso_code, to_iso_code)
+    rate = find_by_from_and_to(from_iso_code, to_iso_code)
+    rate.present? ? rate.rate : nil
+  end
+
+  def self.add_rate(from_iso_code, to_iso_code, rate)
+    exrate = find_or_initialize_by_from_and_to(from_iso_code, to_iso_code)
+    exrate.rate = rate
+    exrate.save!
+  end
+end
+```
+
+Now you can use it with the default bank.
+
+```ruby
+Money.default_bank = Money::Bank::VariableExchange.new(ExchangeRate)
+
+# Add to the underlying store
+Money.default_bank.add_rate('USD', 'CAD', 0.9)
+# Retrieve from the underlying store
+Money.default_bank.get_rate('USD', 'CAD') # => 0.9
+# Exchanging amounts just works.
+Money.new(1000, 'USD').exchange_to('CAD') #=> #<Money fractional:900 currency:CAD>
+```
+
+There is nothing stopping you from creating store objects which scrapes
 [XE](http://www.xe.com) for the current rates or just returns `rand(2)`:
 
 ``` ruby
-Money.default_bank = ExchangeBankWhichScrapesXeDotCom.new
+Money.default_bank = Money::Bank::VariableExchange.new(StoreWhichScrapesXeDotCom.new)
+```
+
+You can also implement your own Bank to calculate exchanges differently.
+Different banks can share Stores.
+
+```ruby
+Money.default_bank = MyCustomBank.new(Money::RatesStore::Memory.new)
 ```
 
 If you wish to disable automatic currency conversion to prevent arithmetic when
@@ -254,6 +369,7 @@ implementations.
 
 - [eu_central_bank](http://github.com/RubyMoney/eu_central_bank)
 - [google_currency](http://github.com/RubyMoney/google_currency)
+- [money-json-rates](https://github.com/askuratovsky/money-json-rates)
 - [nordea](https://github.com/k33l0r/nordea)
 - [nbrb_currency](https://github.com/slbug/nbrb_currency)
 - [money-open-exchange-rates](https://github.com/spk/money-open-exchange-rates)
@@ -296,7 +412,9 @@ If you wish to disable this feature:
 Money.use_i18n = false
 ```
 
-*Note: There are several formatting rules for when `Money#format` is called. For more information, check out the [formatting module](https://github.com/RubyMoney/money/blob/master/lib/money/money/formatting.rb).*
+## Formatting
+
+There are several formatting rules for when `Money#format` is called. For more information, check out the [formatting module](https://github.com/RubyMoney/money/blob/master/lib/money/money/formatting.rb).*
 
 ## Migration Notes
 

data/Rakefile

@@ -1,4 +1,3 @@
-require "rubygems"
 require "bundler/gem_tasks"
 require "rake/clean"
 require "rspec/core/rake_task"

data/config/currency_iso.json

@@ -419,8 +419,8 @@
     "priority": 100,
     "iso_code": "CHF",
     "name": "Swiss Franc",
-    "symbol": "Fr",
-    "alternate_symbols": ["SFr", "CHF"],
+    "symbol": "CHF",
+    "alternate_symbols": ["SFr", "Fr"],
     "subunit": "Rappen",
     "subunit_to_unit": 100,
     "symbol_first": true,
@@ -437,7 +437,7 @@
     "symbol": "UF",
     "alternate_symbols": [],
     "subunit": "Peso",
-    "subunit_to_unit": 1,
+    "subunit_to_unit": 10000,
     "symbol_first": true,
     "html_entity": "₱",
     "decimal_mark": ",",
@@ -452,7 +452,7 @@
     "disambiguate_symbol": "CLP",
     "alternate_symbols": [],
     "subunit": "Peso",
-    "subunit_to_unit": 100,
+    "subunit_to_unit": 1,
     "symbol_first": true,
     "html_entity": "$",
     "decimal_mark": ",",
@@ -1036,14 +1036,14 @@
     "name": "Jordanian Dinar",
     "symbol": "د.ا",
     "alternate_symbols": ["JD"],
-    "subunit": "Piastre",
-    "subunit_to_unit": 100,
+    "subunit": "Fils",
+    "subunit_to_unit": 1000,
     "symbol_first": true,
     "html_entity": "",
     "decimal_mark": ".",
     "thousands_separator": ",",
     "iso_numeric": "400",
-    "smallest_denomination": 0.5
+    "smallest_denomination": 5
   },
   "jpy": {
     "priority": 6,
@@ -1142,7 +1142,7 @@
     "name": "South Korean Won",
     "symbol": "₩",
     "subunit": null,
-    "subunit_to_unit": 100,
+    "subunit_to_unit": 1,
     "alternate_symbols": [],
     "symbol_first": true,
     "html_entity": "₩",

data/lib/money/bank/base.rb

@@ -1,5 +1,3 @@
-require 'thread'
-
 class Money
   # Provides classes that aid in the ability of exchange one currency with
   # another.

data/lib/money/bank/variable_exchange.rb

@@ -1,4 +1,5 @@
 require 'money/bank/base'
+require 'money/rates_store/memory'
 require 'json'
 require 'yaml'
 
@@ -15,42 +16,58 @@ class Money
     # 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 = 100_00.to_money("USD")
-    #   c2 = 100_00.to_money("CAD")
+    #   c1 = Money.new(100_00, "USD")
+    #   c2 = Money.new(100_00, "CAD")
     #
     #   # Exchange 100 USD to CAD:
-    #   bank.exchange_with(c1, "CAD") #=> #<Money @fractional=1245150>
+    #   bank.exchange_with(c1, "CAD") #=> #<Money fractional:12451 currency:CAD>
     #
     #   # Exchange 100 CAD to USD:
-    #   bank.exchange_with(c2, "USD") #=> #<Money @fractional=803115>
+    #   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 :rates, :mutex
+      attr_reader :mutex, :store
 
       # Available formats for importing/exporting rates.
       RATE_FORMATS = [:json, :ruby, :yaml]
+      SERIALIZER_SEPARATOR = '_TO_'.freeze
 
-      # Setup rates hash and mutex for rates locking
+      # Initializes a new +Money::Bank::VariableExchange+ object.
+      # It defaults to using an in-memory, thread safe store instance for
+      # storing exchange rates.
       #
-      # @return [self]
-      def setup
-        @rates = {}
-        @mutex = Mutex.new
-        self
+      # @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
-        [@rates, @rounding_method]
+        [store.marshal_dump, @rounding_method]
       end
 
       def marshal_load(arr)
-        @rates, @rounding_method = arr
-        @mutex = Mutex.new
+        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
@@ -76,14 +93,14 @@ class Money
       #   bank.add_rate("USD", "CAD", 1.24515)
       #   bank.add_rate("CAD", "USD", 0.803115)
       #
-      #   c1 = 100_00.to_money("USD")
-      #   c2 = 100_00.to_money("CAD")
+      #   c1 = Money.new(100_00, "USD")
+      #   c2 = Money.new(100_00, "CAD")
       #
       #   # Exchange 100 USD to CAD:
-      #   bank.exchange_with(c1, "CAD") #=> #<Money @fractional=1245150>
+      #   bank.exchange_with(c1, "CAD") #=> #<Money fractional:12451 currency:CAD>
       #
       #   # Exchange 100 CAD to USD:
-      #   bank.exchange_with(c2, "USD") #=> #<Money @fractional=803115>
+      #   bank.exchange_with(c2, "USD") #=> #<Money fractional:8031 currency:USD>
       def exchange_with(from, to_currency, &block)
         to_currency = Currency.wrap(to_currency)
         if from.currency == to_currency
@@ -114,11 +131,12 @@ class Money
         elsif @rounding_method
           @rounding_method.call(ex)
         else
-          ex.to_s.to_i
+          ex.to_s.to_d
         end
       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.
@@ -134,14 +152,14 @@ class Money
         set_rate(from, to, rate)
       end
 
-      # Set the rate for the given currencies. Uses +Mutex+ to synchronize data
+      # 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
-      # @option opts [Boolean] :without_mutex disables the usage of a mutex
+      # @param [Hash] opts Options hash to set special parameters. Backwards compatibility only.
       #
       # @return [Numeric]
       #
@@ -150,21 +168,16 @@ class Money
       #   bank.set_rate("USD", "CAD", 1.24515)
       #   bank.set_rate("CAD", "USD", 0.803115)
       def set_rate(from, to, rate, opts = {})
-        fn = -> { @rates[rate_key_for(from, to)] = rate }
-        if opts[:without_mutex]
-          fn.call
-        else
-          @mutex.synchronize { fn.call }
-        end
+        store.add_rate(Currency.wrap(from).iso_code, Currency.wrap(to).iso_code, rate)
       end
 
-      # Retrieve the rate for the given currencies. Uses +Mutex+ to synchronize
+      # 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
-      # @option opts [Boolean] :without_mutex disables the usage of a mutex
+      # @param [Hash] opts Options hash to set special parameters. Backwards compatibility only.
       #
       # @return [Numeric]
       #
@@ -176,12 +189,7 @@ class Money
       #   bank.get_rate("USD", "CAD") #=> 1.24515
       #   bank.get_rate("CAD", "USD") #=> 0.803115
       def get_rate(from, to, opts = {})
-        fn = -> { @rates[rate_key_for(from, to)] }
-        if opts[:without_mutex]
-          fn.call
-        else
-          @mutex.synchronize { fn.call }
-        end
+        store.get_rate(Currency.wrap(from).iso_code, Currency.wrap(to).iso_code)
       end
 
       # Return the known rates as a string in the format specified. If +file+
@@ -190,8 +198,7 @@ class Money
       #
       # @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
-      # @option opts [Boolean] :without_mutex disables the usage of a mutex
+      # @param [Hash] opts Options hash to set special parameters. Backwards compatibility only.
       #
       # @return [String]
       #
@@ -208,36 +215,38 @@ class Money
         raise Money::Bank::UnknownRateFormat unless
           RATE_FORMATS.include? format
 
-        s = ""
-        fn = -> {
+        store.transaction do
           s = case format
-              when :json
-                JSON.dump(@rates)
-              when :ruby
-                Marshal.dump(@rates)
-              when :yaml
-                YAML.dump(@rates)
-              end
+          when :json
+            JSON.dump(rates)
+          when :ruby
+            Marshal.dump(rates)
+          when :yaml
+            YAML.dump(rates)
+          end
 
           unless file.nil?
             File.open(file, "w") {|f| f.write(s) }
           end
-        }
-        if opts[:without_mutex]
-          fn.call
-        else
-          @mutex.synchronize { fn.call }
+
+          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
-        s
       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
-      # @option opts [Boolean] :without_mutex disables the usage of a mutex
+      # @param [Hash] opts Options hash to set special parameters. Backwards compatibility only.
       #
       # @return [self]
       #
@@ -254,37 +263,23 @@ class Money
         raise Money::Bank::UnknownRateFormat unless
           RATE_FORMATS.include? format
 
-        fn = -> {
-          @rates = case format
-                   when :json
-                     JSON.load(s)
-                   when :ruby
-                     Marshal.load(s)
-                   when :yaml
-                     YAML.load(s)
-                   end
-        }
-        if opts[:without_mutex]
-          fn.call
-        else
-          @mutex.synchronize { fn.call }
-        end
-        self
-      end
+        store.transaction do
+          data = case format
+           when :json
+             JSON.load(s)
+           when :ruby
+             Marshal.load(s)
+           when :yaml
+             YAML.load(s)
+           end
 
-      private
+          data.each do |key, rate|
+            from, to = key.split(SERIALIZER_SEPARATOR)
+            store.add_rate from, to, rate
+          end
+        end
 
-      # Return the rate hashkey for the given currencies.
-      #
-      # @param [Currency, String, Symbol] from The currency to exchange from.
-      # @param [Currency, String, Symbol] to The currency to exchange to.
-      #
-      # @return [String]
-      #
-      # @example
-      #   rate_key_for("USD", "CAD") #=> "USD_TO_CAD"
-      def rate_key_for(from, to)
-        "#{Currency.wrap(from).iso_code}_TO_#{Currency.wrap(to).iso_code}".upcase
+        self
       end
     end
   end