money 3.1.0.pre3 → 3.1.0

data/CHANGELOG.md

@@ -0,0 +1,196 @@
+Money 3.1.0
+===========
+
+Features
+--------
+ - Implemented `Money::Bank::Base`.
+   ([#issue/14](http://github.com/RubyMoney/money/issues/14))
+ - Added `Money::Bank::Base#exchange_with`.
+ - Deprecated `Money::Bank::Base#exchange`. Deprecation target set to Money
+   3.2.0.
+ - Implented `Money::Bank::VariableExchange`
+ - Deprecated `Money::VariableExchangeBank`. Deprecation target set to Money
+   3.2.0.
+ - Deprecate `Money::SYMBOLS`, `Money::SEPARATORS` and `Money::DELIMITERS`.
+   Deprecation target set to Money 3.2.0.
+   ([#issue/16](http://github.com/RubyMoney/money/issues/16))
+ - Implemented `#has` for `Money` and `Money::Currency`.
+ - Refactored test suite to conform to RSpec conventions.
+ - Moved project from [FooBarWidget](http://github.com/FooBarWidget) to
+   [RubyMoney](http://github.com/RubyMoney)
+ - Added Simone Carletti to list of authors.
+ - Moved `@rounding_method` from `Money::Bank::VariableExchange` to
+   `Money::Bank::Base`.
+   ([#issue/18](http://github.com/RubyMoney/money/issues/18))
+ - Added `#setup` to `Money::Bank::Base`. Called from `#initialize`.
+   ([#issue/19](http://github.com/RubyMoney/money/issues/19))
+ - Added [google_currency](http://github.com/RubyMoney/google_currency) to list
+   of Currency Exchange Implementations.
+ - Added `#export_rates` to `Money::Bank::VariableExchange`.
+   ([#issue/21](http://github.com/RubyMoney/money/issues/21))
+ - Added `#import_rates` to `Money::Bank::VariableExchange`.
+   ([#issue/21](http://github.com/RubyMoney/money/issues/21))
+ - Removed dependency on Jeweler.
+ - Replaced usage of hanna with yardoc.
+ - Rewrote/reformatted all documentation.
+
+Bugfixes
+--------
+ - Fixed incorrect URLs in documentation.
+   ([#issue/17](http://github.com/RubyMoney/money/issues/17))
+ - Updated `:subunit_to_unit` for HKD from 10 to 100.
+   ([#issue/20](http://github.com/RubyMoney/money/issues/20))
+ - Updated Ghanaian Cedi to use correct ISO Code, GHS.
+   ([#issue/22](http://github.com/RubyMoney/money/issues/22))
+ - Make `default` rake task call `spec`.
+   ([#issue/23](http://github.com/RubyMoney/money/issues/23))
+
+Money 3.1.0.pre3
+================
+
+Features
+--------
+ - Added [google_currency](http://github.com/RubyMoney/google_currency) to list
+   of Currency Exchange Implementations.
+ - Added `#export_rates` to `Money::Bank::VariableExchange`.
+   ([#issue/21](http://github.com/RubyMoney/money/issues/21))
+ - Added `#import_rates` to `Money::Bank::VariableExchange`.
+   ([#issue/21](http://github.com/RubyMoney/money/issues/21))
+
+Bugfixes
+--------
+ - Updated `:subunit_to_unit` for HKD from 10 to 100.
+   ([#issue/20](http://github.com/RubyMoney/money/issues/20))
+
+Money 3.1.0.pre2
+================
+
+Features
+--------
+ - Moved `@rounding_method` from `Money::Bank::VariableExchange` to
+   `Money::Bank::Base`.
+   ([#issue/18](http://github.com/RubyMoney/money/issues/18))
+ - Added `#setup` to `Money::Bank::Base`. Called from `#initialize`.
+   ([#issue/19](http://github.com/RubyMoney/money/issues/19))
+
+Bugfixes
+--------
+ - Fixed incorrect URLs in documentation.
+   ([#issue/17](http://github.com/RubyMoney/money/issues/17))
+
+Money 3.1.0.pre1
+================
+
+Features
+--------
+ - Implemented `Money::Bank::Base`.
+   ([#issue/14](http://github.com/RubyMoney/money/issues/14))
+ - Added `Money::Bank::Base#exchange_with`.
+ - Deprecated `Money::Bank::Base#exchange`. Deprecation target set to Money
+   3.2.0.
+ - Implented `Money::Bank::VariableExchange`
+ - Deprecated `Money::VariableExchangeBank`. Deprecation target set to Money
+   3.2.0.
+ - Deprecate `Money::SYMBOLS`, `Money::SEPARATORS` and `Money::DELIMITERS`.
+   Deprecation target set to Money 3.2.0.
+   ([#issue/16](http://github.com/RubyMoney/money/issues/16))
+ - Implemented `#has` for `Money` and `Money::Currency`.
+ - Refactored test suite to conform to RSpec conventions.
+ - Moved project from [FooBarWidget](http://github.com/FooBarWidget) to
+   [RubyMoney](http://github.com/RubyMoney)
+ - Added Simone Carletti to list of authors.
+
+Bugfixes
+--------
+ - Fixed rounding error in `Numeric#to_money`.
+   ([#issue/15](http://github.com/RubyMoney/money/issues/15))
+
+Money 3.0.5
+===========
+
+Features
+--------
+ - Added `Money#abs`.
+ - Added ability to pass a block to `VariableExchangeBank#new` or `#exchange`,
+   specifying a custom truncation method
+ - Added optional `currency` argument to` Numeric#to_money`.
+   ([#issue/11](http://github.com/RubyMoney/money/issues/11))
+ - Added optional `currency` argument to `String#to_money`.
+   ([#issue/11](http://github.com/RubyMoney/money/issues/11))
+ - Use '¤' as the default currency symbol.
+   ([#issue/10](http://github.com/RubyMoney/money/issues/10))
+
+Bugfixes
+--------
+ - Updated `Currency#subunit_to_unit` documentation (it's an integer not a
+   string).
+ - Fixed issue when exchanging currencies with different `:subunit_to_unit`
+   values.
+ - `Numeric#to_money` now respects `:subunit_to_unit`.
+   ([#issue/12](http://github.com/RubyMoney/money/issues/12))
+
+Money 3.0.4
+===========
+
+Features
+--------
+ - Use `:subunit_to_unit` in `#to_s`, `#to_f` and `#format`.
+ - Deprecated `Money#SEPARATORS` and `Money#DELIMITERS`.
+
+Bugfixes
+--------
+ - Updated `#exchange` to avoid floating point rounding errors.
+ - Added `:separator` and `:delimiter` to `Currency`
+ - Updated the attributes of the Chilean Peso.
+
+Money 3.0.3
+===========
+
+Features
+--------
+ - Added `#currency_as_string` and `#currency_as_string=` for easier
+   integration with ActiveRecord/Rails
+
+Money 3.0.2
+===========
+
+Features
+--------
+ - Added `#div`, `#divmod`, `#modulo`, `#%` and `#remainder` to `Money`.
+
+Money 3.0.1
+===========
+
+Features
+--------
+ - Added `#eql?` to `Money`
+ - Updated `Numeric#to_money` to work with all children of `Numeric` (i.e.
+   `BigDecimal`, `Integer`, `Fixnum`, `Float`, etc)
+
+Money 3.0.0
+===========
+
+Features
+--------
+ - Version Bump due to compatibility changes with ActiveRecord. See
+   conversation
+   [here](http://github.com/RubyMoney/money/issues#issue/4/comment/224880)
+   for more information.
+
+Money 2.3.0
+===========
+
+Features
+--------
+ - Currency is now represented by a `Currency` Object instead of a `String`.
+
+Money 2.2.0
+===========
+
+Features
+--------
+ - Can now divide two Money objects by one another using `#/`.
+ - Can now convert a Money object to a float using `#to_f`.
+ - Users can now specify Separators and Delimiters when using `#format`.
+ - Support for Brazilian Real `Money.new(1_00, :BRL)`
+ - Migrated to Jeweler

data/README.md

@@ -0,0 +1,217 @@
+# RubyMoney - Money
+
+## Introduction
+
+This library aids one in handling money and different currencies.
+
+### Features
+
+- Provides a `Money` class which encapsulates all information about an certain
+  amount of money, such as its value and its currency.
+- Provides a `Money::Currency` class which encapsulates all information about
+  a monetary unit.
+- Represents monetary values as integers, in cents. This avoids floating point
+  rounding errors.
+- Represents currency as `Money::Currency` instances providing an high level of
+  flexibility.
+- Provides APIs for exchanging money from one currency to another.
+- Has the ability to parse a money and currency strings
+  into the corresponding Money/Currency object.
+
+### Resources
+
+- [Website](http://money.rubyforge.org)
+- [API Documentation](http://money.rubyforge.org)
+- [Git Repository](http://github.com/RubyMoney/money)
+
+## Downloading
+
+Install stable releases with the following command:
+
+    gem install money
+
+The development version (hosted on Github) can be installed with:
+
+    git clone git://github.com/RubyMoney/money.git
+    cd money
+    rake install
+
+## Usage
+
+    require 'money'
+
+    # 10.00 USD
+    money = Money.new(1000, "USD")
+    money.cents     #=> 1000
+    money.currency  #=> Currency.new("USD")
+
+    # Comparisons
+    Money.new(1000, "USD") == Money.new(1000, "USD")   #=> true
+    Money.new(1000, "USD") == Money.new(100, "USD")    #=> false
+    Money.new(1000, "USD") == Money.new(1000, "EUR")   #=> false
+    Money.new(1000, "USD") != Money.new(1000, "EUR")   #=> true
+
+    # Arithmetic
+    Money.new(1000, "USD") + Money.new(500, "USD") == Money.new(1500, "USD")
+    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")
+
+    # Currency conversions
+    some_code_to_setup_exchange_rates
+    Money.new(1000, "USD").exchange_to("EUR") == Money.new(some_value, "EUR")
+
+## Currency
+
+Currencies are consistently represented as instances of `Money::Currency`.
+The most part of `Money` APIs allows you to supply either a `String` or a
+`Money::Currency`.
+
+    Money.new(1000, "USD") == Money.new(900, Currency.new("USD"))
+    Money.new(1000, "EUR").currency == Currency.new("EUR")
+
+A `Money::Currency` instance holds all the information about the currency,
+including the currency symbol, name and much more.
+
+    currency = Money.new(1000, "USD").currency
+    currency.iso_code #=> "USD"
+    currency.name     #=> "United States Dollar"
+
+To define a new `Money::Currency` simply add a new item to the
+`Money::Currency::TABLE` hash, where the key is the identifier for the currency
+object and the value is a hash containing all the currency attributes.
+
+     Money::Currency::TABLE[:USD] = {
+      :priority        => 1,
+      :iso_code        => "USD",
+      :name            => "United States Dollar",
+      :symbol          => "$",
+      :subunit         => "Cent"
+      :subunit_to_unit => 100,
+      :separator       => ".",
+      :delimiter       => ","
+    }
+
+The pre-defined set of attributes includes:
+
+- `:priority` a numerical value you can use to sort/group the currency list
+- `:iso_code` the international 3-letter code as defined by the ISO 4217 standard
+- `:name` the currency name
+- `:symbol` the currency symbol (UTF-8 encoded)
+- `:subunit` the name of the fractional monetary unit
+- `:subunit_to_unit` the proportion between the unit and the subunit
+- `:separator` character between the whole and fraction amounts
+- `:delimiter` character between each thousands place
+
+All attributes are optional. Some attributes, such as `:symbol`, are used by
+the Money class to print out a representation of the object. Other attributes,
+such as `:name` or `:priority`, exist to provide a basic API you can take
+advantage of to build your application.
+
+### :priority
+
+The priority attribute is an arbitrary numerical value you can assign to the
+`Money::Currency` and use in sorting/grouping operation.
+
+For instance, let's assume your Rails application needs to render a currency
+selector like the one available
+[here](http://finance.yahoo.com/currency-converter/). You can create a couple of
+custom methods to return the list of major currencies and all currencies as
+follows:
+
+    # Returns an array of currency id where
+    # priority < 10
+    def major_currencies(hash)
+      hash.inject([]) do |array, (id, attributes)|
+        priority = attributes[:priority]
+        if priority && priority < 10
+          array[priority] ||= []
+          array[priority] << id
+        end
+        array
+      end.compact.flatten
+    end
+
+    # Returns an array of all currency id
+    def all_currencies(hash)
+      hash.keys
+    end
+
+    major_currencies(Money::Currency::TABLE)
+    # => [ :usd, :eur, :bgp, :cad ]
+
+    all_currencies(Money::Currency::TABLE)
+    # => [ :aed, :afn, all, ... ]
+
+### Default Currency
+
+By default `Money` defaults to USD as its currency. This can be overwritten
+using:
+
+    Money.default_currency = Money::Currency.new("CAD")
+
+If you use Rails, then `environment.rb` is a very good place to put this.
+
+## Currency Exchange
+
+Exchanging money is performed through an exchange bank object. The default
+exchange bank object requires one to manually specify the exchange rate. Here's
+an example of how it works:
+
+    Money.add_rate("USD", "CAD", 1.24515)
+    Money.add_rate("CAD", "USD", 0.803115)
+
+    Money.us_dollar(100).exchange_to("CAD")  # => Money.new(124, "CAD")
+    Money.ca_dollar(100).exchange_to("USD")  # => Money.new(80, "USD")
+
+Comparison and arithmetic operations work as expected:
+
+    Money.new(1000, "USD") <=> Money.new(900, "USD")   # => 1; 9.00 USD is smaller
+    Money.new(1000, "EUR") + Money.new(10, "EUR") == Money.new(1010, "EUR")
+
+    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
+[XE](http://www.xe.com) for the current rates or just returns `rand(2)`:
+
+    Money.default_bank = ExchangeBankWhichScrapesXeDotCom.new
+
+### Upcoming Changes
+
+Starting in v3.1.0 we will be making two changes to the exchange process. First
+a new `Bank::Base` class will be available. This will allow users to more
+easily create custom `Bank` classes. Secondly the default `#exchange` method
+will be depreciated and a new `#exchange_with` method will be used. Currently
+`#exchange` passes the `cents` attribute. `#exchange_with` will pass the
+actual `Money` object instead.
+
+### Implementations
+
+The following is a list of Money.gem compatible currency exchange rate
+implementations.
+
+- [eu_central_bank](http://github.com/RubyMoney/eu_central_bank)
+- [google_currency](http://github.com/RubyMoney/google_currency)
+
+## Ruby on Rails
+
+Use the `compose_of` helper to let Active Record deal with embedding the money
+object in your models. The following example requires a `cents` and a
+`currency` field.
+
+    composed_of :price,
+      :class_name => "Money",
+      :mapping => [%w(cents cents), %w(currency currency_as_string)],
+      :constructor => Proc.new { |cents, currency| Money.new(cents || 0, currency || Money.default_currency) }
+
+For Money 2.2.x and previous versions, simply use the following `composed_of`
+definition:
+
+    composed_of :price,
+      :class_name => "Money",
+      :mapping => [%w(cents cents), %w(currency currency)],
+      :constructor => Proc.new { |cents, currency| Money.new(cents || 0, currency || Money.default_currency) }
+
+For further details read the full discussion
+[here](http://github.com/RubyMoney/money/issues/4#comment_224880).

data/lib/money/bank/base.rb

@@ -1,6 +1,8 @@
 require 'thread'
 
 class Money
+  # Provides classes that aid in the ability of exchange one currency with
+  # another.
   module Bank
 
     # The lowest Money::Bank error class.
@@ -14,37 +16,59 @@ class Money
     end
 
 
+    # Money::Bank::Base is the basic interface for creating a money exchange
+    # object, also called Bank.
     #
-    # Money::Bank::Base is the basic interface for creating a money exchange object,
-    # also called Bank.
+    # A Bank is responsible for storing exchange rates, take a Money object as
+    # input and returns the corresponding Money object converted into an other
+    # currency.
     #
-    # A Bank is responsible for storing exchange rates,
-    # take a Money object as input and returns the corresponding Money object
-    # converted into an other currency.
+    # This class exists for aiding in the creating of other classes to exchange
+    # money between different currencies. When creating a subclass you will
+    # need to implement the following methods to exchange money between
+    # currencies:
     #
-    # This class exists for aiding in the creating of other classes to exchange money between
-    # different currencies. When creating a subclass you will need to implement
-    # the following  methods to exchange money between currencies:
-    #
-    # * #exchange_with(Money) # => Money
+    # - #exchange_with(Money) #=> Money
     #
     # See Money::Bank::VariableExchange for a real example.
     #
-    # Also, you can extend Money::Bank::VariableExchange
-    # instead of Money::Bank::Base if your bank implementation
-    # needs to store rates internally.
+    # Also, you can extend +Money::Bank::VariableExchange+ instead of
+    # +Money::Bank::Base+ if your bank implementation needs to store rates
+    # internally.
     #
+    # @abstract Subclass and override +#exchange_with+ to implement a custom
+    #  +Money::Bank+ class. You can also override +#setup+ instead of
+    #  +#initialize+ to setup initial variables, etc.
     class Base
 
       # Returns the singleton instance of the Base bank.
+      #
+      # @return [Money::Bank::Base]
       def self.instance
         @@singleton ||= self.new
       end
 
+      # The rounding method to use when exchanging rates.
+      #
+      # @return [Proc]
       attr_reader :rounding_method
 
-      # Initializes a new Money::Bank::Base object. An optional block can be
-      # passed to dictate the rounding method that +exchange_with+ can use.
+      # Initializes a new +Money::Bank::Base+ object. An optional block can be
+      # passed to dictate the rounding method that +#exchange_with+ can use.
+      #
+      # @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::Bank::Base]
+      #
+      # @example
+      #   Money::Bank::Base.new #=> #<Money::Bank::Base @rounding_method=nil>
+      #   Money::Bank::Base.new {|n|
+      #     n.floor
+      #   } #=> #<Money::Bank::Base @round_method=#<Proc>>
       def initialize(&block)
         @rounding_method = block
         setup
@@ -52,14 +76,16 @@ class Money
 
       # Called after initialize. Subclasses can use this method to setup
       # variables, etc that they normally would in +#initialize+.
+      #
+      # @abstract Subclass and override +#setup+ to implement a custom
+      #  +Money::Bank+ class.
+      #
+      # @return [self]
       def setup
       end
 
       # @deprecated +#exchange+ will be removed in v3.2.0, use +#exchange_with+
-      #
-      # Exchanges the given amount of cents in +from_currency+ to +to_currency+.
-      #
-      # Returns the amount of cents in +to_currency+ as an integer, rounded down.
+      # @see Money::Bank::Base#exchange_with
       def exchange(cents, from_currency, to_currency, &block)
         Money.deprecate "`Money::Bank::Base#exchange' will be removed in v3.2.0, use #exchange_with instead"
         exchange_with(Money.new(cents, from_currency), to_currency, &block).cents
@@ -68,30 +94,45 @@ class Money
       # Exchanges the given +Money+ object to a new +Money+ object in
       # +to_currency+.
       #
-      # You should implement this in a subclass,
-      # otherwise it will throw a NotImplementedError as a reminder.
+      # @abstract Subclass and override +#exchange_with+ to implement a custom
+      #  +Money::Bank+ class.
+      #
+      # @raise NotImplementedError
+      #
+      # @param [Money] from The +Money+ object to exchange from.
+      # @param [Money::Currency, String, Symbol] to_currency The currency
+      #  string or object to exchange to.
+      # @yield [n] Optional block to use to round the result after making
+      #  the exchange.
+      # @yieldparam [Float] n The result after exchanging from one currency to
+      #  the other.
+      # @yieldreturn [Integer]
       #
-      # Returns a new +Money+ object.
-      # Raises <tt>NotImplementedError</tt>.
+      # @return [Money]
       def exchange_with(from, to_currency, &block)
         raise NotImplementedError, "#exchange_with must be implemented"
       end
 
 
-      # Given two currency strings or object,
-      # checks whether they're both the same currency.
+      # Given two currency strings or object, checks whether they're both the
+      # same currency. Return +true+ if the currencies are the same, +false+
+      # otherwise.
       #
-      #   same_currency?("usd", "USD")                # => true
-      #   same_currency?("usd", "EUR")                # => false
-      #   same_currency?("usd", Currency.new("USD")   # => true
-      #   same_currency?("usd", "USD")   # => true
+      # @param [Money::Currency, String, Symbol] currency1 The first currency
+      #  to compare.
+      # @param [Money::Currency, String, Symbol] currency2 The second currency
+      #  to compare.
       #
-      # Return +true+ if the currencies are the same, +false+ otherwise.
+      # @return [Boolean]
+      #
+      # @example
+      #   same_currency?("usd", "USD")                #=> true
+      #   same_currency?("usd", "EUR")                #=> false
+      #   same_currency?("usd", Currency.new("USD")   #=> true
+      #   same_currency?("usd", "USD")                #=> true
       def same_currency?(currency1, currency2)
         Currency.wrap(currency1) == Currency.wrap(currency2)
       end
-
     end
-
   end
 end