easy_rails_money 0.0.2 → 0.0.3

data/.gitignore

@@ -19,3 +19,4 @@ tmp
 
 .rvmrc
 NOTES
+.rspec

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.0.1
+- Add a README listing the rationale and rough draft of the migration
+  DSL to be implemented
+- Added migration DSL to add two columns to persist a money object.
+  An Interger column to persist the money amount and a String column
+  to persist the currency name
+
+## 0.0.2
+- Modify migration DSL to support multiple money amount columns and a
+  single currency column
+- add travis, codeclimate and gemnasium gem-dependency badges
+- has a dependency on ActiveRecord and removed the dependency on Rails
+
+## 0.0.3
+- add missing cases for supporting a single currency
+- refactor tests
+- add simplecov coverage report
+- Add yard docs and update README
+
+

data/README.md

@@ -2,14 +2,20 @@
 [![Dependency Status](https://gemnasium.com/deepak/easy_rails_money.png)](https://gemnasium.com/deepak/easy_rails_money)
 [![Code Climate](https://codeclimate.com/github/deepak/easy_rails_money.png)](https://codeclimate.com/github/deepak/easy_rails_money)
 
-### Under Development. Only the migration part is done now
+### Under Development
+
+The migration helpers are functionally complete.
+Working on integrating with Rails' ActiveModel
 
 # EasyRailsMoney
 
-This library provides integration of [money](http://github.com/Rubymoney/money) gem with Rails.
+> “Young people, nowadays, imagine that money is everything.
+> 
+> Yes, murmured Lord Henry, settling his button-hole in his coat; 
+> and when they grow older they know it.”  
+> ― Oscar Wilde, The Picture of Dorian Gray and Other Writings
 
-Use 'money' to specify which fields you want to be backed by a Money
-object
+This library provides integration of [money](http://github.com/Rubymoney/money) gem with [Rails](https://github.com/rails/rails).
 
 [money-rails](https://github.com/RubyMoney/money-rails) is much more
 popular and full-featured. Definately try it out. I have actually
@@ -19,10 +25,37 @@ I have tried to create a simpler version of [money-rails](https://github.com/Rub
 With a better API and database schema, in my opinion
 I created this project to scratch my itch.
 
-Have stolen lots of code from [money-rails](https://github.com/RubyMoney/money-rails)
-API and tests are written from scratch
+Please open a new issue [in the github project issues tracker](http://github.com/deepak/easy_rails_money/issues). You are also
+more than welcome to contribute to the project :-)  
+
+## Credits
+
+Have stolen lots of code from [money-rails](https://github.com/RubyMoney/money-rails)  
+But database schema, API and tests are written from scratch  
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'easy_rails_money'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install easy_rails_money
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
 
-## How it works
+## Rationale
 
 Let us say you want to store a Rupee Money object in the database
 
@@ -30,6 +63,7 @@ Let us say you want to store a Rupee Money object in the database
 principal = Money.new(100, "inr")
 ```  
 
+To serialize the values in the database
 Option 1:
 ```ruby
 class CreateLoan < ActiveRecord::Migration
@@ -58,8 +92,12 @@ Note that we are storing the base unit in the database. If the amount
 is in dollars we store in cents or if the amount is in Indian Rupees
 we store in paise and so on. This is done because FLoats do not have a
 accurate representation but Integers do. Can store BigDecimal as well
-but it is slower. This is why the Money gem stores amounts as integer
+but it is slower. This is why the Money gem stores amounts as integer  
+
 Watch [Rubyconf 2011 Float-is-legacy](http://www.confreaks.com/videos/698-rubyconf2011-float-is-legacy) for more details
+and read [What Every Computer Scientist Should Know About
+Floating-Point Arithmetic, by David Goldberg, published in March,
+1991](http://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html)  
 
 We have encoded the currency in the column name. I like it because
 there is no need to define another column and it is simple. But the
@@ -114,56 +152,118 @@ end
 It might be possible that we set a currency once for the whole app and
 never change it. But this seems like a nice tradeoff api-wise
 
-### TODO's
-1. currency is stored as a string. Integer might be better for storing in the database
-2. store a snapshot of the exchange rate as well when the record was
-   inserted or if we want to "freeze" the exchange rate per-record
+## Usage
 
-## Installation
+### ActiveRecord
 
-Add this line to your application's Gemfile:
+Only ActiveRecord is supported for now. And has been tested on
+ActiveRecord 3.x
 
-    gem 'easy_rails_money'
+#### Migration helpers
 
-And then execute:
+If you want to create a table which has some money columns, then you can use the ```money``` migration helper
 
-    $ bundle
+```ruby
+class CreateLoanWithCurrency < ActiveRecord::Migration
+  def change
+    create_table :loans, force: true do |t|
+      t.string :name
+      t.money  :principal
+      t.money  :repaid
+      t.money  :npa
+      t.currency
+    end
+  end
+end
+```
 
-Or install it yourself as:
+If you want to add a money column to an existing table then you can
+again use the ```money``` migration helper
 
-    $ gem install easy_rails_money
+```ruby
+class AddPrincipalToLoan < ActiveRecord::Migration
+  def change
+    change_table :loans do |t|
+      t.money :principal
+    end
+  end
+end
+```
 
-## Usage
+Another option is to use ```add_money``` migration helper
+It is a different DSL style, similar to ```create_table```
 
-### ActiveRecord
+```ruby
+class AddPrincipalToLoan < ActiveRecord::Migration
+  def up
+    add_money :loans, :principal, :repaid, :npa
+  end
 
-Only ActiveRecord is supported for now
+  def down
+    remove_money :loans, :principal, :repaid, :npa
+  end
+end
+```
 
-#### Migration helpers
+```add_money``` helper is revertable, so you may use it inside ```change``` migrations.
+If you writing separate ```up``` and ```down``` methods, you may use
+the ```remove_money``` migration helper.
 
-If you want to add money field to product model you may use ```add_money``` helper
+The above statements for ```money``` and ```add_money``` will create
+two columns. An integer column to store the lower denomination as an
+integer and a string column to store the currency name. 
 
-```ruby
-class MonetizeLoan < ActiveRecord::Migration
-  def change
-    add_money :loans, :principal
+eg. if we say ```add_money :loans, :principal``` Then the following two
+columns will be created:
+1. integer column called ```principal_money```
+2. string column called ```principal_currency```
 
-    # OR
+If we want to store ```$ 100``` in this column then:
+1. column ```principal_money``` will contain the unit in the lower denomination
+   ie. cents in this case. So for ```$100``` it will store ```100 * 100 => 100_000 cents```
+2. column ```principal_currency``` will store the currency name ie. ```usd```
 
-    change_table :products do |t|
-      t.money :principal
+Both the amount and currency is needed to create a ```Money``` object
+
+Now if we have multiple money columns, then you can choose to have a
+single currency column
+
+```ruby
+class CreateLoanWithCurrency < ActiveRecord::Migration
+  def change
+    create_table :loans, force: true do |t|
+      t.string :name
+      t.money  :principal
+      t.money  :repaid
+      t.money  :npa
+      t.currency
     end
   end
 end
 ```
 
-```add_money``` helper is revertable, so you may use it inside ```change``` migrations.
-If you writing separate ```up``` and ```down``` methods, you may use ```remove_money``` helper.
+This will create a single column for currency:
+1. It creates three columns for each of the money columns
+   ```principal_money```, ```repaid_money``` and ```npa_money```
+2. note that it does not create a currency column for each of the
+   money columns. But a common currency column is created. 
+   It is boringly enough called ```currency```
 
-## Contributing
+Note that columns are prefixed with ```_money``` and ```_currency``` 
+And the common currency column is called ```currency```. 
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+It is used to reflect on the database schema ie. to find out the
+money and currency columns defined.  
+Right now, none of these choices are customizable.
+
+## TODO's
+1. Proof-read docs
+2. currency is stored as a string. Integer might be better for storing in the database
+3. store a snapshot of the exchange rate as well when the record was
+   inserted or if we want to "freeze" the exchange rate per-record
+4. specs for migration test the same thing in multiple ways. have a
+   spec helper
+5. add Gemfil to test on ActiveRecord 4.x ie. with Rails4 . Add to travis.yml as well
+6. configure the ```_money``` and ```_currency``` prefix and the name
+   of the common ```currency``` column
+7. check specs tagged as "fixme"

data/Rakefile

@@ -5,3 +5,12 @@ RSpec::Core::RakeTask.new('spec')
 
 # If you want to make this the default task
 task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb']   # optional
+    t.options = ['--one-file']
+  end
+rescue LoadError
+end

data/easy_rails_money.gemspec

@@ -21,8 +21,19 @@ Gem::Specification.new do |gem|
   gem.add_dependency "activesupport", "~> 3.2"
 
   gem.add_development_dependency "rake",         "~> 10.0.4"
+
+  # for running tests
   gem.add_development_dependency "rspec",        "~> 2.12"
-  gem.add_development_dependency "activerecord", "~> 3.2"
+  # we use an in-memory sqlite database for speed
   gem.add_development_dependency "sqlite3",      "~> 1.3.7"
+  # testing against the ActiveRecord interface
+  gem.add_development_dependency "activerecord", "~> 3.2"
+  
   gem.add_development_dependency "debugger",     "~> 1.5.0"
+  gem.add_development_dependency "simplecov",    "~> 0.7.1"
+
+  # for generating docs
+  gem.add_development_dependency "yard",         "~> 0.8.5.2"
+  # needed by YARD to read markdown files
+  gem.add_development_dependency "redcarpet",    "~> 2.2.2"
 end

data/lib/easy_rails_money.rb

@@ -1,7 +1,15 @@
+# -*- coding: utf-8 -*-
+
 require "money"
 require "easy_rails_money/version"
 require "easy_rails_money/configuration"
 
+# @author Deepak Kannan
+# “Young people, nowadays, imagine that money is everything.  
+#   
+# Yes, murmured Lord Henry, settling his button-hole in his coat; and when they grow older they know it.”  
+# ― Oscar Wilde, The Picture of Dorian Gray and Other Writings  
+# This library provides integration of [money](http://github.com/Rubymoney/money) gem with [Rails](https://github.com/rails/rails).
 module EasyRailsMoney
   extend Configuration
 end

data/lib/easy_rails_money/active_record/migration/schema_statements.rb

@@ -2,18 +2,104 @@ module EasyRailsMoney
   module ActiveRecord
     module Migration
       module SchemaStatements
-        def add_money(table_name, *columns)
-          columns.each do |name|
+        # Creates one or two columns to represent a Money object in the named table
+        #
+        # An integer column for storing Money in its base unit
+        # eg. cents for a Dollar denomination and a string for storing
+        # its currency name. Can think of it as a persisted or serialized
+        # Money object in the database. The integer column is suffixed
+        # with '_money' to aid in reflection ie. to find all money
+        # columns. Likewise the currency column is suffixed with '_currency'
+        # If does not create an individual currency column if a
+        # common currency column is defined
+        #
+        # @param table_name [Symbol|String]
+        # @param column_names [Array|Symbol|String] List of money columns to add
+        # @return is not important and can change
+        #
+        # @note If we have defined a currency column for a record then only the integer column is defined.
+        # @see EasyRailsMoney::ActiveRecord::Migration::TableDefinition#money
+        # @see EasyRailsMoney::ActiveRecord::Migration::Table#money
+        # @see EasyRailsMoney::ActiveRecord::Migration::TableDefinition#currency
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#remove_money
+        def add_money table_name, *column_names
+          column_names.each do |name|
             add_column table_name, "#{name}_money",    :integer
-            add_column table_name, "#{name}_currency", :string
+            add_column table_name, "#{name}_currency", :string unless has_currency_column?(table_name)
           end
         end
 
-        def remove_money(table_name, *columns)
-          columns.each do |name|
+        # Removes the columns which represent the Money object
+        #
+        # Removes the two columns added by add_money. The money amount and
+        # the currency column. If there are no remaining money amount columns
+        # and a common currency column exists. then it is also removed
+        #
+        # @param table_name [Symbol|String]
+        # @param column_names [Array|Symbol|String] List of money columns to remove
+        # @return is not important and can change
+        # @note If we have defined a currency column for a record then currency column is removed only if no other money column are there
+        #
+        # @see EasyRailsMoney::ActiveRecord::Migration::Table#remove_money
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#add_money
+        # @see EasyRailsMoney::ActiveRecord::Migration::TableDefinition#currency
+        # @note multiple remove_money calls are not supported in one migration. because at this point the schema is different from the migration defined
+        def remove_money table_name, *column_names
+          column_names.each do |name|
             remove_column table_name, "#{name}_money"
             remove_column table_name, "#{name}_currency"
           end
+          remove_currency table_name unless has_money_columns?(table_name)
+        end
+
+        # Removes the common currency column
+        #
+        # Usually we create an currency column for each money
+        # columns. We can have multiple money columns in the same
+        # record, in which case we can have a single currency
+        # column. This helper removes that common curremcy column. For
+        # the existing money column it adds back their currency
+        # columns as well. It reflects on the database schema by
+        # looking at the column name. By convention the money amount
+        # column is prefixed by '_money' and the currency column by '_currency'
+        #
+        # @param table_name [Symbol|String]
+        #
+        # @see EasyRailsMoney::ActiveRecord::Migration::Table#remove_currency
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#remove_money
+        # @see EasyRailsMoney::ActiveRecord::Migration::TableDefinition#currency
+        def remove_currency table_name
+          remove_column table_name, :currency
+          money_columns(table_name) do |money_column|
+            add_column table_name, "#{money_column}_currency", :string
+          end
+        end
+
+        protected
+        def has_currency_column? table_name
+          connection.schema_cache.clear_table_cache! table_name
+          connection.schema_cache.columns[table_name].select {|x| x.name == "currency" }.any?
+        end
+
+        def money_columns table_name
+          # FIXME: see specs tagged
+          # fixme_need_to_clear_table_cache. for that test needed to
+          # clear the cache
+          connection.schema_cache.clear_table_cache! table_name
+          connection.schema_cache.columns[table_name].select { |col|
+            col.name =~ /_money/
+          }.map { |col|
+            name = col.name.match(/(.+)_money/)[1]
+            if block_given?
+              yield name
+            else
+              name
+            end
+          }
+        end
+
+        def has_money_columns? table_name
+          money_columns(table_name).any?
         end
       end
     end

data/lib/easy_rails_money/active_record/migration/table.rb

@@ -5,27 +5,80 @@ module EasyRailsMoney
         # called for change_table
         # currency and #money defined in TableDefinition
 
+        # Creates one or two columns to represent a Money object in the named table
+        #
+        # An integer column for storing Money in its base unit
+        # eg. cents for a Dollar denomination and a string for storing
+        # its currency name. Can think of it as a persisted or serialized
+        # Money object in the database. The integer column is suffixed
+        # with '_money' to aid in reflection ie. to find all money
+        # columns. Likewise the currency column is suffixed with '_currency'
+        # If does not create an individual currency column if a
+        # common currency column is defined
+        #
+        # @param column_names [Array|Symbol|String] List of money columns to add
+        # @return is not important and can change
+        #
+        # @note If we have defined a currency column for a record then only the integer column is defined.
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#add_money
+        # @see EasyRailsMoney::ActiveRecord::Migration::TableDefinition#money
+        # @see EasyRailsMoney::ActiveRecord::Migration::TableDefinition#currency
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#remove_money
         def money(*column_names)
           column_names.each do |name|
-            column "#{name}_money",      :integer
-            unless columns.select { |x| x.name == "currency" }.any?
-              column "#{name}_currency", :string
-            end
+            column "#{name}_money",    :integer
+            column "#{name}_currency", :string unless has_currency_column?
           end
         end
 
-        def currency
-          remove_currency_columns
-          column :currency, :string
-        end
-
+        # Removes the columns which represent the Money object
+        #
+        # Removes the two columns added by money. The money amount and
+        # the currency column. If there are no remaining money amount columns
+        # and a common currency column exists. then it is also removed
+        #
+        # @param column_names [Array|Symbol|String] List of money columns to remove
+        # @return is not important and can change
+        #
+        # @note If we have defined a currency column for a record then currency column is removed only if no other money column are there
+        #
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#remove_money
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#add_money
+        # @see EasyRailsMoney::ActiveRecord::Migration::TableDefinition#currency
+        # @note multiple remove_money calls are not supported in one migration. because at this point the schema is different from the migration defined
         def remove_money(*column_names)
           column_names.each do |name|
             remove "#{name}_money"
             remove "#{name}_currency"
           end
+          remove_currency unless has_money_columns?
         end
 
+        # Add a common currency column
+        #
+        # @return is not important and can change
+        #
+        # Add a common currency column and remove the individual
+        # currrency columns if they exist
+        def currency
+          remove_currency_columns
+          column :currency, :string
+        end
+
+        # Removes the common currency column
+        #
+        # Usually we create an currency column for each money
+        # columns. We can have multiple money columns in the same
+        # record, in which case we can have a single currency
+        # column. This helper removes that common curremcy column. For
+        # the existing money column it adds back their currency
+        # columns as well. It reflects on the database schema by
+        # looking at the column name. By convention the money amount
+        # column is prefixed by '_money' and the currency column by '_currency'
+        #
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#remove_currency
+        # @see EasyRailsMoney::ActiveRecord::Migration::SchemaStatements#remove_money
+        # @see EasyRailsMoney::ActiveRecord::Migration::TableDefinition#currency
         def remove_currency
           remove :currency
           money_columns do |money_column|
@@ -33,26 +86,38 @@ module EasyRailsMoney
           end
         end
 
+        protected
         def remove_currency_columns
           money_columns do |money_column|
             remove "#{money_column}_currency"
           end
         end
-
-        protected
+                
         def columns
-          @base.schema_cache.columns[@table_name]
+          # @base.schema_cache.clear_table_cache! @table_name
+          @base.schema_cache.columns[@table_name].map { |x| x.name }
+        end
+
+        def has_currency_column?
+          columns.select { |x| x == "currency" }.any?
         end
 
         def money_columns
-          columns.select do |col|
-            col.name =~ /_money/
-          end.map do |col|
-            money_column = col.name.match(/(.+)_money/)[1]
-            yield money_column
-          end
+          columns.select { |col|
+            col =~ /_money/
+          }.map { |col|
+            name = col.match(/(.+)_money/)[1]
+            if block_given?
+              yield name
+            else
+              name
+            end
+          }
         end
 
+        def has_money_columns?
+          money_columns.any?
+        end
       end
     end
   end