spook_and_puff_money 0.5 → 0.5.5

data/README.md

@@ -5,3 +5,92 @@ This is yet another Ruby class made to represent money. This one is dead simple.
 It also provides a few other conveniences like formatting.
 
 It is primarily intended for our own projects, but is offered here as an open sourced project, because.
+
+## Install It
+
+### As a Gem
+
+Install via RubyGems.
+
+```
+$ gem install spook_and_puff_money
+```
+
+Then inside your application, require it like so:
+
+```
+require 'spook_and_puff/money'
+```
+
+### With Bundler
+
+Update your Gemfile with the dependency.
+
+```
+gem 'spook_and_puff_money', '~> 0.5.5', :require => 'spook_and_puff/money'
+```
+
+Then update your bundle like usual.
+
+```
+$ bundle install
+```
+
+## Getting Started
+
+Once you've installed and required the gem, using it is straight forward. It can only be initialized with a BigDecimal or a String. This is to prevent mistakes like passing in a Float.
+
+```
+money = SpookAndPuff::Money.new('10.01')
+```
+
+If you need to print out a formatted currency string, it's simple.
+
+```
+money.to_s #=> '$10.01'
+```
+
+The raw BigDecimal is available via an accessor.
+
+```
+money.raw #=> #<BigDecimal:7feb0c115c70,'0.1001E2',18(18)>
+```
+
+Money can be added together, subtracted and multiplied. Be careful of the order and types of the operands. For the `+` and `-` operators, both operands must be money instances. For most other methods, any numeric can be used, but they will be coerced into BigDecimal in order to preserve the precision.
+
+The argument types of each method is documented, so don't forget to have a look at them.
+
+# SpookAndPuff::MoneyAttributes
+
+This is a module provided as a convenience for working with ActiveRecord models. It is not required by default when using this gem, instead you must require it separately. 
+
+Assuming you have the gem installed:
+
+```
+require 'spook_and_puff/money_attributes'
+```
+
+Or if you are using Bundler:
+
+```
+gem 'spook_and_puff_money', '~> 0.5.5', :require 'spook_and_puff/money_attributes'
+```
+
+The above implicitly requires the `SpookAndPuff::Money` class as well, so you don't have to worry about that.
+
+## Usage
+
+Extend your models with the module and use the ::attr_money method to define which attributes you want to have coerced into Money instances. Currently these attributes _must_ map to DB columns.
+
+```
+class Derp < ActiveRecord::Base
+  extend SpookAndPuff::MoneyAttributes
+  attr_money :foo, :bar
+end
+```
+
+You can now use the `foo` and `bar` attributes like any other, with a few restrictions.
+
+You can only pass the writers instances of `BigDecimal`, `String` and `NilClass`. Anything else will raise a `TypeError`.
+
+Most importantly, you should not access the attributes using the `[]` method, since this will return the raw value, not an instance of `SpookAndPuff::Money`.

data/lib/spook_and_puff/money_attributes.rb

@@ -0,0 +1,44 @@
+require 'spook_and_puff/money'
+
+module SpookAndPuff
+  # A module for extending ActiveRecord::Base subclasses. It provides a macro
+  # for defining money accessors; it produces writers which coerce the input
+  # into SpookAndPuff::Money instances.
+  module MoneyAttributes
+    # A class macro which defines serialization and attribute writers for the
+    # specified attributes. This ensures that the specified attributes will
+    # always be instances of SpookAndPuff::Money.
+    #
+    # @param Array<Symbol>
+    #
+    # @return nil
+    def attr_money(*attrs)
+      attrs.each do |attr|
+        class_eval %{
+          def #{attr}
+            if self[:#{attr}]
+              @#{attr} ||= SpookAndPuff::Money.new(self[:#{attr}]) 
+            end
+          end
+
+          def #{attr}=(value)
+            if value.nil?
+              @#{attr}, self[:#{attr}] = nil
+            else
+              @#{attr} = case value
+              when SpookAndPuff::Money then value
+              else SpookAndPuff::Money.new(value)
+              end
+
+              self[:#{attr}] = @#{attr}.raw
+            end
+
+            @#{attr}
+          end
+        }
+      end
+
+      nil
+    end  
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spook_and_puff_money
 version: !ruby/object:Gem::Version
-  version: '0.5'
+  version: 0.5.5
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-10 00:00:00.000000000 Z
+date: 2013-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -68,6 +68,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/spook_and_puff/money.rb
+- lib/spook_and_puff/money_attributes.rb
 - MIT-LICENSE
 - README.md
 homepage: http://spookandpuff.com