fantastic_currency 0.1.0

data/Manifest

@@ -0,0 +1,4 @@
+README.textile
+Rakefile
+lib/fantastic_currency.rb
+Manifest

data/README.textile

@@ -0,0 +1,92 @@
+h1. Fantastic Currency
+
+Currency magic with Active Record & Rails.
+
+h1. Install
+
+<pre><code>
+  gem install fantastic_currency
+
+  config.gem "fantastic_currency" (put in environment.rb)
+</code></pre>
+
+h1. Usage & Examples
+
+Let's imagine you're building an online shop, and you want to manage items which have a price, and a shipping price.
+You operate from the US and the UK, some of your items are for sale in US Dollars, others in British Pounds.
+
+*In your model:*
+<pre><code>
+  class Products < ActiveRecord::Base
+    currency :price
+    currency :shipping_price
+  end
+</code></pre>
+This will ensure your monetary values are stored safely in the database.
+You should store the relevant 3-letter currency code in your table in a column named @currency@.
+If you do not do this, you will have to pass in a :currency => :something whenever you access the field,
+otherwise the default currency, USD is assumed.
+
+You can work with your currencies like this:
+<pre><code>
+  record.price = "42.50"
+  record.price                      # => 42.5 (as BigDecimal)
+  record.price :format => true      # => $42.50
+  record.price :format => true,
+    :convert_to => :GBP             # => £26.80
+    
+  record.price = "12345.67"
+  record.price :format => true,
+    :delimiter => "-",
+    :separator => "_"               # => $12_345-67
+  
+  record.price = 500
+  record.price :format => true      # => $500
+  record.price :format => true,
+    :extra_zeros => true            # => $500.00
+  record.price :format => true,
+    :before_unit => "(",
+    :after_unit => ")"              # => ($)500
+
+  record.price = 0
+  record.price :format => true,
+    :free_as_text => true           # => "free"
+  
+</code></pre>
+
+*No floats are allowed* When setting a currency field, feel free to use a string, an integer, or a bigdecimal.
+Do not use floats, because they are not accurate enough. You'll get told off if you try to! 
+
+You can also manually call the currency formatter from within a model or controller.
+Note that you will need to manually specify the currency in this case.
+<pre><code>
+  format_currency(4280, :format => true, :currency => :GBP)         # => £42.80
+
+  format_currency(4280, :format => true,
+    :currency => :GBP, :precise_input => true)                      # => £4280
+  
+  format_currency("4280.50", :format => true,
+    :currency => :GBP, :precise_input => true)                      # => £4280.50
+  
+  format_currency("42", :currency => :GBP,
+    :convert_to => :USD, :precise_input => true)                    # => 65.70
+</code></pre>
+
+
+h1. Configuration
+
+By default, a few currencies are set up, but you may wish to configure your own.
+If you do, in environment.rb (or anywhere you like) you can do something like this:
+
+<pre><code>
+  FantasticCurrency::Config.define_currencies({
+    :USD => { :symbol => "$", :precision => 2, :name => "US Dollars", :nominal_value => 1 },
+    :GBP => { :symbol => "£", :precision => 2, :name => "British Pounds", :nominal_value => "1.5666" },
+    :CAD => { :symbol => "CA $", :precision => 2, :name => "Canadian Dollars", :nominal_value => "0.95" },
+    :AUD => { :symbol => "AU $", :precision => 2, :name => "Australian Dollars", :nominal_value => "0.8886" }
+  })
+</code></pre>
+
+Nominal value is used for converting between currencies. An easy way to work this out is to make your first currency's nominal value 1, and then work out all the following currencies values, in comparison to the first. E.g. 1 USD = 1 USD. 1 GBP = 1.5666 USD. etc.
+
+You may wish to write an automated system for generating and storing these nominal values based on current market values. That is up to you.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('fantastic_currency', '0.1.0') do |p|
+  p.description     = "Manage currencies with Active Record"
+  p.url             = "http://github.com/iamcalledrob/FantasticCurrency"
+  p.author          = "Rob Mason"
+  p.email           = "info+gems@slightlyfantastic.com"
+  p.ignore_pattern  = ["tmp/*", "script/*"]
+  p.development_dependencies = []
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/fantastic_currency.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{fantastic_currency}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Rob Mason"]
+  s.date = %q{2010-02-14}
+  s.description = %q{Manage currencies with Active Record}
+  s.email = %q{info+gems@slightlyfantastic.com}
+  s.extra_rdoc_files = ["README.textile", "lib/fantastic_currency.rb"]
+  s.files = ["README.textile", "Rakefile", "lib/fantastic_currency.rb", "Manifest", "fantastic_currency.gemspec"]
+  s.homepage = %q{http://github.com/iamcalledrob/FantasticCurrency}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Fantastic_currency", "--main", "README.textile"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{fantastic_currency}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Manage currencies with Active Record}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/lib/fantastic_currency.rb

@@ -0,0 +1,138 @@
+module FantasticCurrency
+  
+  class Helper
+    include Singleton
+    include ActionView::Helpers
+  end
+  
+  class Currency
+    def self.format(value, options={})
+      options = {
+        :currency => nil,
+        :format => false,
+        :extra_zeros => false,
+        :delimiter => ",",
+        :separator => ".",
+        :free_as_text => true,
+        :display_unit => true,
+        :before_unit => "",
+        :after_unit => " ",
+        :convert_to => nil,
+        :precise_input => false,
+      }.merge(options)
+      
+      if options[:precise_input] == true
+        value = BigDecimal.new(value.to_s) * 10**FantasticCurrency::Config.get_currency(options[:currency])[:precision]
+      end
+      
+      if options[:convert_to]
+        source_currency = FantasticCurrency::Config.get_currency(options[:currency])
+        dest_currency = FantasticCurrency::Config.get_currency(options[:convert_to])
+        value = value * BigDecimal.new(source_currency[:nominal_value].to_s) / BigDecimal.new(dest_currency[:nominal_value].to_s)
+        value = value / 10**(source_currency[:precision] - dest_currency[:precision])
+        
+        active_currency = dest_currency
+      else
+        active_currency = FantasticCurrency::Config.get_currency(options[:currency])
+      end
+      
+      precision_factor = 10**active_currency[:precision]
+
+      if options[:format] == true
+        if value == 0 and options[:free_as_text]
+          return "free"
+        end
+        helper = FantasticCurrency::Helper.instance
+        
+        if options[:extra_zeros] == false and (value.to_i / precision_factor * precision_factor) == value.to_i
+          precision = 0
+        else
+          precision = active_currency[:precision]
+        end
+        
+        value_as_string = helper.number_with_precision(BigDecimal.new(value.to_s) / precision_factor,
+          :precision => precision,
+          :delimiter => options[:delimiter],
+          :separator => options[:separator])
+        
+        if options[:display_unit] == true
+          options[:before_unit] + active_currency[:symbol] + options[:after_unit] + value_as_string
+        else
+          value_as_string
+        end
+      else
+        BigDecimal.new(value.to_s) / precision_factor
+      end
+      
+    end
+
+  end
+  
+  class Config
+    # Some initial currencies to have fun with. Exchange rates will be inaccurate.
+    @@currencies = {
+      :USD => { :symbol => "$", :precision => 2, :name => "US Dollars", :nominal_value => 1 },
+      :GBP => { :symbol => "£", :precision => 2, :name => "British Pounds", :nominal_value => "1.5666" },
+      :CAD => { :symbol => "CA $", :precision => 2, :name => "Canadian Dollars", :nominal_value => "0.95" },
+      :AUD => { :symbol => "AU $", :precision => 2, :name => "Australian Dollars", :nominal_value => "0.8886" },
+      :EUR => { :symbol => "€", :precision => 2, :name => "Euro", :nominal_value => "1.3617" },
+      :JPY => { :symbol => "¥", :precision => 0, :name => "Japanese Yen", :nominal_value => "0.011116" },
+      :KRW => { :symbol => "₩", :precision => 0, :name => "South Korean Won", :nominal_value => "0.000869" }
+    }
+    def self.define_currencies currencies
+      @@currencies = currencies
+    end
+    def self.currencies
+      @@currencies
+    end
+    def self.get_currency currency=nil
+      if currency and FantasticCurrency::Config.currencies[currency.to_sym]
+        return FantasticCurrency::Config.currencies[currency.to_sym]
+      else
+        return { :symbol => "$", :precision => 2, :nominal_value => 1 } #default currency.
+      end 
+    end
+  end
+  
+  module ActiveRecord
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    
+    def format_currency(value, options={})
+      FantasticCurrency::Currency.format(value, options)
+    end
+
+    module ClassMethods
+
+      def currency(field_name)
+    
+        define_method "#{field_name.to_s}" do |*args|
+          if self[field_name]
+            format_currency(self[field_name], { :currency => self[:currency] }.merge(args.first || {}))
+          end
+        end
+    
+        define_method "#{field_name.to_s}=" do |value|
+          raise "Money doesn't float!" if value.class.name == "Float"
+          
+          if self[field_name]
+            currency = FantasticCurrency::Config.get_currency(self[:currency])
+            self[field_name] = (BigDecimal.new(value.to_s) * (10**currency[:precision])).to_i
+          end
+        end
+        
+      end
+    end
+  end
+  
+  module ActionController
+    def format_currency(value, options={})
+      FantasticCurrency::Currency.format(value, options)
+    end
+  end
+  
+end
+
+ActiveRecord::Base.send(:include, FantasticCurrency::ActiveRecord)
+ActionController::Base.send(:include, FantasticCurrency::ActionController)

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: fantastic_currency
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Rob Mason
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-14 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: Manage currencies with Active Record
+email: info+gems@slightlyfantastic.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+- lib/fantastic_currency.rb
+files: 
+- README.textile
+- Rakefile
+- lib/fantastic_currency.rb
+- Manifest
+- fantastic_currency.gemspec
+has_rdoc: true
+homepage: http://github.com/iamcalledrob/FantasticCurrency
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Fantastic_currency
+- --main
+- README.textile
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: fantastic_currency
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Manage currencies with Active Record
+test_files: []
+