money-rails 0.2.0 → 0.3.0

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0
+
+- Add support for model-wise currency.
+- Fix conversion of monetized attribute value, whether a currency
+  table column exists or not.
+- Add configuration options for currency exchange (config.add_rate,
+  config.default_bank)
+
 ## 0.2.0
 
 - Add new generator to install money.rb initializer

data/README.md

@@ -10,6 +10,11 @@ Use 'monetize' to specify which fields you want to be backed by
 Money objects and helpers provided by the [money](http://github.com/Rubymoney/money)
 gem.
 
+Currently, this library is in active development mode, so if you would
+like to have a new feature feel free to open a new issue
+[here](https://github.com/RubyMoney/money-rails/issues). You are also
+welcome to contribute to the project.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -64,16 +69,108 @@ Now the model objects will have a ```discount``` attribute which
 is a Money object, wrapping the value of ```discount_subunit``` column to a
 Money instance.
 
-### Field currencies
+### Currencies
+
+Money-rails supports a set of options to handle currencies for your
+monetized fields. The default option for every conversion is to use
+the global default currency of Money library, as given in the configuration
+initializer of money-rails:
+
+```ruby
+# config/initializers/money.rb
+MoneyRails.configure do |config|
+
+  # set the default currency
+  config.default_currency = :usd
+
+end
+```
+
+In many cases this is not enough, so there are some other options to
+satisfy your needs.
+
+#### Model Currency
+
+You can define a specific currency for an activerecord model. This currency is
+used for the creation and conversions of the Money objects referring to
+every monetized attributes of the specific model. This means it overrides
+the global default currency of Money library. To attach a currency to a
+model use the ```register_currency``` macro:
+
+```ruby
+# app/models/product.rb
+class Product < ActiveRecord::Base
+
+  # Use EUR as model level currency
+  register_currency :eur
+
+  monetize :discount_subunit, :as => "discount"
+  monetize :bonus_cents
+
+end
+```
+
+Now ```product.discount``` and ```product.bonus``` will return a Money
+object using EUR as currency, instead of the default USD.
+
+#### Attribute Currency (:with_currency)
 
-You can define a specific currency per monetized field:
+By using the key ```:with_currency``` with a currency symbol value in
+the ```monetize``` macro call, you can define a currency in a more
+granular way. This way you attach a currency only to the specific monetized
+model attribute. It also allows to override both the model level
+and the global default currency:
 
 ```ruby
-monetize :discount_subunit, :as => "discount", :with_currency => :eur
+# app/models/product.rb
+class Product < ActiveRecord::Base
+
+  # Use EUR as model level currency
+  register_currency :eur
+
+  monetize :discount_subunit, :as => "discount"
+  monetize :bonus_cents, :with_currency => :gbp
+
+end
 ```
 
-Now ```discount_subunit``` will give you a Money object using EUR as
-currency.
+In this case the ```product.bonus``` will return a Money object of GBP
+currency, whereas ```product.discount.currency_as_string # => EUR ```
+
+#### Instance Currencies
+
+All the previous options do not require any extra model field to hold
+currency values. If you need to provide differrent currency per model
+instance, then you need to add a column with the name ```currency```
+in your db table. Money-rails will discover this automatically,
+and will use this knowledge to override the model level and global
+default values. Attribute currency cannot be combined with instance
+currency!
+
+```ruby
+class Transaction < ActiveRecord::Base
+
+  # This model has a separate currency column
+  attr_accessible :amount_cents, :currency, :tax_cents
+
+  # Use model level currency
+  register_currency :gbp
+
+  monetize :amount_cents
+  monetize :tax_cents
+
+end
+
+# Now instantiating with a specific currency overrides the
+# the model and global currencies
+t = Transaction.new(:amount_cents => 2500, :currency => "CAD")
+t.amount == Money.new(2500, "CAD") # true
+```
+
+WARNING: In this case :with_currency is not permitted and the usage
+of this parameter will cause an ArgumentError exception.
+
+In general, the use of this strategy is discouraged unless there is a reason.
 
 ### Configuration parameters
 
@@ -86,6 +183,10 @@ MoneyRails.configure do |config|
   #
   config.default_currency = :usd
 
+  # Add custom exchange rates
+  config.add_rate "USD", "CAD", 1.24515
+  config.add_rate "CAD", "USD", 0.803115
+
   # To handle the inclusion of validations for monetized fields
   # The default value is true
   #
@@ -114,6 +215,10 @@ end
   used more than once to set more custom currencies. The value should be
   a hash of all the necessary key/value pairs (important keys: :priority, :iso_code, :name,
   :symbol, :symbol_first, :subunit, :subunit_to_unit, :thousands_separator, :decimal_mark).
+* add_rate: Provide custom exchange rate for currencies in one direction
+  only! This rate is added to the attached bank object.
+* default_bank: The default bank object holding exchange rates etc.
+  (https://github.com/RubyMoney/money#currency-exchange)
 
 ## Maintainers
 

data/lib/generators/templates/money.rb

@@ -6,6 +6,18 @@ MoneyRails.configure do |config|
   #
   #config.default_currency = :usd
 
+  # Set default bank object
+  #
+  # Example:
+  # config.default_bank = EuCentralBank.new
+
+  # Add exchange rates to current money bank object.
+  # (The conversion rate refers to one direction only)
+  #
+  # Example:
+  # config.add_rate "USD", "CAD", 1.24515
+  # config.add_rate "CAD", "USD", 0.803115
+
   # To handle the inclusion of validations for monetized fields
   # The default value is true
   #

data/lib/money-rails/active_record/monetizable.rb

@@ -21,11 +21,14 @@ module MoneyRails
               ":with_currency or :with_model_currency")
           end
 
-          # Model currency field name
+          # Optional table column which holds currency iso_codes
+          # It allows per row currency values
+          # Overrides default currency
           model_currency_name = options[:with_model_currency] ||
             options[:model_currency] || "currency"
 
-          # Override Model and default currency
+          # This attribute allows per column currency values
+          # Overrides row and default currency
           field_currency_name = options[:with_currency] ||
             options[:field_currency] || nil
 
@@ -44,27 +47,44 @@ module MoneyRails
             name = subunit_name << "_money"
           end
 
-          class_eval do
-            composed_of name.to_sym,
-              :class_name => "Money",
-              :mapping => [[subunit_name, "cents"], [model_currency_name, "currency_as_string"]],
-              :constructor => Proc.new { |cents, currency|
-              Money.new(cents || 0, field_currency_name || currency ||
-                        Money.default_currency)
-            },
-              :converter => Proc.new { |value|
-              if  value.respond_to?(:to_money)
-                if field_currency_name
-                  value.to_money(field_currency_name)
-                else
-                  value.to_money
-                end
+          has_currency_table_column = self.attribute_names.include? model_currency_name
+
+          if has_currency_table_column
+            raise(ArgumentError, ":with_currency should not be used with tables" \
+                  " which contain a column for currency values") if field_currency_name
+
+            mappings = [[subunit_name, "cents"], [model_currency_name, "currency_as_string"]]
+            constructor = Proc.new { |cents, currency|
+              Money.new(cents || 0, currency || self.respond_to?(:currency) &&
+                        self.currency || Money.default_currency)
+            }
+            converter = Proc.new { |value|
+              raise(ArgumentError, "Only Money objects are allowed for assignment")
+            }
+          else
+            mappings = [[subunit_name, "cents"]]
+            constructor = Proc.new { |cents|
+              Money.new(cents || 0, field_currency_name || self.respond_to?(:currency) &&
+                        self.currency || Money.default_currency)
+            }
+            converter = Proc.new { |value|
+              if value.respond_to?(:to_money)
+                value.to_money(field_currency_name || self.respond_to?(:currency) &&
+                              self.currency)
               else
                 raise(ArgumentError, "Can't convert #{value.class} to Money")
               end
             }
           end
 
+          class_eval do
+            composed_of name.to_sym,
+              :class_name => "Money",
+              :mapping => mappings,
+              :constructor => constructor,
+              :converter => converter
+          end
+
           # Include numericality validation if needed
           if MoneyRails.include_validations
             class_eval do
@@ -72,6 +92,20 @@ module MoneyRails
             end
           end
         end
+
+        def register_currency(currency_name)
+          # Lookup the given currency_name and raise exception if
+          # no currency is found
+          currency_object = Money::Currency.find currency_name
+          raise(ArgumentError, "Can't find #{currency_name} currency code") unless currency_object
+
+          class_eval do
+            @currency = currency_object
+            class << self
+              attr_reader :currency
+            end
+          end
+        end
       end
     end
   end

data/lib/money-rails/configuration.rb

@@ -26,6 +26,17 @@ module MoneyRails
       Money::Currency.register(currency_options)
     end
 
+    # Set default bank object
+    #
+    # example (given that eu_central_bank is in Gemfile):
+    #   MoneyRails.configure do |config|
+    #     config.default_bank = EuCentralBank.new
+    #   end
+    delegate :default_bank=, :to => :Money
+
+    # Provide exchange rates
+    delegate :add_rate, :to => :Money
+
     # Use (by default) validation of numericality for each monetized field.
     mattr_accessor :include_validations
     @@include_validations = true

data/lib/money-rails/version.rb

@@ -1,3 +1,3 @@
 module MoneyRails
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
 end

data/money-rails.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.email         = ["alup.rubymoney@gmail.com"]
   s.description   = "This library provides integration of RubyMoney - Money gem with Rails"
   s.summary       = "Money gem integration with Rails"
-  s.homepage      = "https://github.com/RubyMoney/money"
+  s.homepage      = "https://github.com/RubyMoney/money-rails"
 
   s.files         =  Dir.glob("{lib,spec}/**/*")
   s.files         += %w(CHANGELOG.md LICENSE README.md)
@@ -28,4 +28,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency "sqlite3",     "~> 1.3.6"
   s.add_development_dependency "rspec",       "~> 2.9.0"
   s.add_development_dependency "rspec-rails", "~> 2.9.0"
+  s.add_development_dependency "guard-rspec", "~> 0.7.2"
 end

data/spec/active_record/monetizable_spec.rb

@@ -0,0 +1,138 @@
+require 'spec_helper'
+
+describe MoneyRails::ActiveRecord::Monetizable do
+
+  describe "monetize" do
+    before :each do
+      @product = Product.create(:price_cents => 3000, :discount => 150,
+                                :bonus_cents => 200)
+      @service = Service.create(:charge_cents => 2000, :discount_cents => 120)
+    end
+
+    it "attaches a Money object to model field" do
+      @product.price.should be_an_instance_of(Money)
+      @product.discount_value.should be_an_instance_of(Money)
+      @product.bonus.should be_an_instance_of(Money)
+    end
+
+    it "returns the expected money amount as a Money object" do
+      @product.price.should == Money.new(3000, "USD")
+    end
+
+    it "assigns the correct value from a Money object" do
+      @product.price = Money.new(3210, "USD")
+      @product.save.should be_true
+      @product.price_cents.should == 3210
+    end
+
+    it "respects :as argument" do
+      @product.discount_value.should == Money.new(150, "USD")
+    end
+
+    it "uses numericality validation" do
+      @product.price_cents = "foo"
+      @product.save.should be_false
+
+      @product.price_cents = 2000
+      @product.save.should be_true
+    end
+
+    it "uses Money default currency if :with_currency has not been used" do
+      @service.discount.currency.should == Money::Currency.find(:eur)
+    end
+
+    it "overrides default currency with the currency registered for the model" do
+      @product.price.currency.should == Money::Currency.find(:usd)
+    end
+
+    it "overrides default currency with the value of :with_currency argument" do
+      @service.charge.currency.should == Money::Currency.find(:usd)
+      @product.bonus.currency.should == Money::Currency.find(:gbp)
+    end
+
+    it "assigns correctly Money objects to the attribute" do
+      @product.price = Money.new(2500, :USD)
+      @product.save.should be_true
+      @product.price.cents.should == 2500
+      @product.price.currency_as_string.should == "USD"
+    end
+
+    it "assigns correctly Fixnum objects to the attribute" do
+      @product.price = 25
+      @product.save.should be_true
+      @product.price.cents.should == 2500
+      @product.price.currency_as_string.should == "USD"
+    end
+
+    it "overrides default, model currency with the value of :with_currency in fixnum assignments" do
+      @product.bonus = 25
+      @product.save.should be_true
+      @product.bonus.cents.should == 2500
+      @product.bonus.currency_as_string.should == "GBP"
+    end
+
+    it "overrides default currency with model currency, in fixnum assignments" do
+      @product.discount_value = 5
+      @product.save.should be_true
+      @product.discount_value.cents.should == 500
+      @product.discount_value.currency_as_string.should == "USD"
+    end
+
+    it "falls back to default currency, in fixnum assignments" do
+      @service.discount = 5
+      @service.save.should be_true
+      @service.discount.cents.should == 500
+      @service.discount.currency_as_string.should == "EUR"
+    end
+
+    context "for model with currency column:" do
+      before :each do
+        @transaction = Transaction.create(:amount_cents => 2400, :tax_cents => 600,
+                                          :currency => :usd)
+        @dummy_product1 = DummyProduct.create(:price_cents => 2400, :currency => :usd)
+        @dummy_product2 = DummyProduct.create(:price_cents => 2600) # nil currency
+      end
+
+      it "overrides default currency with the value of row currency" do
+        @transaction.amount.currency.should == Money::Currency.find(:usd)
+      end
+
+      it "overrides default currency with the currency registered for the model" do
+        @dummy_product2.price.currency.should == Money::Currency.find(:gbp)
+      end
+
+      it "overrides default and model currency with the row currency" do
+        @dummy_product1.price.currency.should == Money::Currency.find(:usd)
+      end
+
+      it "constructs the money attribute from the stored mapped attribute values" do
+        @transaction.amount.should == Money.new(2400, :usd)
+      end
+
+      it "instantiates correctly Money objects from the mapped attributes" do
+        t = Transaction.new(:amount_cents => 2500, :currency => "CAD")
+        t.amount.should == Money.new(2500, "CAD")
+      end
+
+      it "assigns correctly Money objects to the attribute" do
+        @transaction.amount = Money.new(2500, :eur)
+        @transaction.save.should be_true
+        @transaction.amount.cents.should == Money.new(2500, :eur).cents
+        @transaction.amount.currency_as_string.should == "EUR"
+      end
+
+      it "raises exception if a non Money object is assigned to the attribute" do
+        expect { @transaction.amount = "not a Money object" }.to raise_error(ArgumentError)
+        expect { @transaction.amount = 234 }.to raise_error(ArgumentError)
+      end
+
+    end
+  end
+
+  describe "register_currency" do
+    it "attaches currency at model level" do
+      Product.currency.should == Money::Currency.find(:usd)
+      DummyProduct.currency.should == Money::Currency.find(:gbp)
+    end
+  end
+end