coinage 0.2.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Chris Lloyd
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,140 @@
+Handle and convert your Money!
+
+Think of Coinage as a weedy, overworked guy. Amongst other things, this man enjoys exercising Biro's so that his collection's ink levels, when ordered,  form a sine wave. So yeah, he also likes the finer points of money. So does Coinage.
+
+Here's what you want to know. Coinage allows for: simple conversion between currencies; reliable monetary arithmetic; multi-national input parsing; easy Rails & Merb money handling.
+
+This is _not_ meant as a replacement for "ActiveMerchant":http://www.activemerchant.org/, it _is_, however, meant as a replacement for "Money":http://dist.leetsoft.com/api/money/.
+
+*WARNING:* To quote 1998, this software is still very much "under construction". I really wouldn't recommend using it in production until it reaches 1.0.
+
+
+h2. Install
+
+  sudo gem install coinage
+
+
+h2. Usage
+
+  require 'coinage'
+  
+  a = 5.dollars
+  
+  b = Money.new(5, :aud)
+  
+  a + b
+
+Ok, lets work through this example. First off, you have to require Coinage. @a@ is then created as a new @Money@ instance with the value of $5. Whenever new @Money@ instances are created without specifying a currency (like in the second line) the currency defaults to United States Dollars. This can be changed as follows:
+
+  Money.default_currency = :aud
+
+The third line creates a new @Money@ instance but this time in Australian Dollars. Note that @a@ does not necessarily equal @b@ as it is unlikely that the two currencies will ever reach parity.
+
+Finally, @a + b@ adds the two variables together. Out of the box this should return a new @Money@ object with value USD$10. It is in US Dollars as any arithmetic operator sets the result's currency to the first operand's currency. The result has a value of 10 dollars because by default, Coinage uses the @Coinage::Exchange::None@ exchange, which always provides an exchange rate of 1. This default will change as the other exchanges become more stable.
+
+The default exchange can be changed:
+
+  Money.default_exchange = Coinage::Exchange::Xurrency.new
+
+h3. ActiveRecord
+
+For the moment, its not nat pretty integrating Coinage with money, but its quite easy:
+
+  composed_of :price, :class_name => 'Money', :mapping => %w(price_in_cents currency) do |price|
+    price.to_money
+  end
+
+That creates a virtual property, @value@, which maps to the database columns @price_in_cents@ and @currency@. Coinage stores all values as cents. It also creates a setter method, @value=@ which can accept a string so in your view you can have something like:
+
+  <%= f.text_field :value %>
+
+That will work with mass assignment (read: out of the box) and deal with storing all monetary values. Automagic!
+
+h3. Defining Custom Exchanges
+
+Say you have MaiSpecialAPI giving you currency rates and you want to use that instead of Xurrency or Yahoo. Just create a new exchange like the one below and put all your code in the @rate@ method.
+
+  class MaiSpecialExchange
+    
+    include Coinage::Exchange::Base
+    
+    def rate(current, target)
+      super(current, target) # Verifies that both currencies are supported by your exchange
+      
+      MaiSpecial.get(current, target)
+    
+    end
+    
+    def supported_currencies
+      [ :lolz, :catz ]
+    end
+    
+  end
+
+Then just set
+
+  Money.default_exchange = MaiSpecialExchange.new
+
+and Wallah! Your all set.
+
+
+h2. Notes
+
+* _Namespaces_: While all of Coinage's internal classes are defined in the @Coinage@ namespace, the @Money@ class is defined in the global namespace.
+* _Class Extension_: @Numeric@ and @String@ are given methods such as @:to_money@ and @:cents@.
+* _Commutativity_: With two Money instances, @a + b != b + a@ if @a@ and @b@ have different currencies. This is because currencies are not quantitative and favors the instance acted upon (@a@) rather than the passed instance (@b@).
+* _Supported Currencies_: Are currently hard coded. Not the friendliest interface to work with, but it should work for the most part.
+
+
+h2. Plans
+
+* _Cache exchange calls_: This will provide a major speed-up. Cache to a few different back-ends (flat file, memcached, db) so that calls only have to be made at a defined frequency, rather than every time a conversion is needed. Rake tasks will also be provided if you want to update this cache externally.
+* _More exchange APIs_: At the moment it only supports the Xurrency API. I plan on adding support for Yahoo and XE Premium (when I get a sample response). It is very easy to add your own API back-ends.
+* _Use libxml-ruby_: By far the fastest XML parser out there, it currently is fairly undocumented. Definitely switch to it for parsing exchange data.
+* _Rails 2.2 Integration_: When 2.2 comes out Coinage will be there supporting the new i18n & L10n features in Rails core.
+* _ActiveRecord & DataMapper support_: Provide a class method which will make it easier to transform ordinary fields into Money objects.
+* _String Parsing_: Be able to parse a wide variety of user input such as: 'AUD$50', '$50 AUD', '€50', '€50,99', '50,000.00' and '50.000,00'.
+
+
+h2. Authors
+
+* "Chris Lloyd":http://chrislloyd.com.au
+* You
+
+
+h2. Contribute
+
+You can checkout the source or fork it yourself from Github.
+
+  git clone git://github.com/chrislloyd/coinage.git
+
+If you submit a successful patch then you'll be given full commit rights to the project.
+
+
+h2. Bugs
+
+Bug tracking is handled by "Ditz":http://ditz.rubyforge.org.
+
+
+h2. License
+
+Copyright (c) 2008 Chris Lloyd.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rubygems/specification'
+require 'spec/rake/spectask'
+require 'date'
+
+GEM = "coinage"
+GEM_VERSION = "0.2.0"
+AUTHOR = "Chris Lloyd"
+EMAIL = "christopher.lloyd@gmail.com"
+HOMEPAGE = "http://github.com/chrislloyd/coinage"
+SUMMARY = "Handle and convert your Money!"
+
+spec = Gem::Specification.new do |s|
+  s.name = GEM
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.rubyforge_project = GEM
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README.textile', 'LICENSE']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  
+  # Uncomment this to add a dependency
+  # s.add_dependency "foo"
+  s.add_dependency 'hpricot'
+  
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README.textile Rakefile) + Dir.glob("{lib,specs}/**/*")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+task :default => :spec
+task :specs => :spec
+
+desc "Run all examples"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_opts = ['--options', 'spec/spec.opts']
+  t.spec_files = FileList['spec/**/**/*.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude',"#{GEM}\\.rb,spec/,rspec-*,rcov-*"]
+end
+
+desc "install the gem locally"
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION}}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{GEM}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+task :bugs do
+  sh %{ditz html ; open html/index.html} if PLATFORM == 'universal-darwin9.0'
+end

data/lib/coinage.rb

@@ -0,0 +1,6 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'coinage/core_ext'
+require 'coinage/exchange'
+require 'coinage/money'

data/lib/coinage/core_ext.rb

@@ -0,0 +1,4 @@
+require 'coinage/core_ext/array'
+require 'coinage/core_ext/class'
+require 'coinage/core_ext/numeric'
+require 'coinage/core_ext/string'

data/lib/coinage/core_ext/array.rb

@@ -0,0 +1,16 @@
+class Array
+  
+  # Extracts options from a set of arguments. Removes and returns the last
+  # element in the array if it's a hash, otherwise returns a blank hash.
+  #
+  #   def options(*args)
+  #     args.extract_options!
+  #   end
+  #
+  #   options(1, 2)           # => {}
+  #   options(1, 2, :a => :b) # => {:a=>:b}
+  def extract_options!
+    last.is_a?(::Hash) ? pop : {}
+  end
+  
+end

data/lib/coinage/core_ext/class.rb

@@ -0,0 +1,54 @@
+# Extends the class object with class and instance accessors for class attributes,
+# just like the native attr* accessors for instance attributes.
+#
+#  class Person
+#    cattr_accessor :hair_colors
+#  end
+#
+#  Person.hair_colors = [:brown, :black, :blonde, :red]
+class Class
+  def cattr_reader(*syms)
+    syms.flatten.each do |sym|
+      next if sym.is_a?(Hash)
+      class_eval(<<-EOS, __FILE__, __LINE__)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+
+        def self.#{sym}
+          @@#{sym}
+        end
+
+        def #{sym}
+          @@#{sym}
+        end
+      EOS
+    end
+  end
+
+  def cattr_writer(*syms)
+    options = syms.extract_options!
+    syms.flatten.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+
+        def self.#{sym}=(obj)
+          @@#{sym} = obj
+        end
+
+        #{"
+        def #{sym}=(obj)
+          @@#{sym} = obj
+        end
+        " unless options[:instance_writer] == false }
+      EOS
+    end
+  end
+
+  def cattr_accessor(*syms)
+    cattr_reader(*syms)
+    cattr_writer(*syms)
+  end
+end

data/lib/coinage/core_ext/numeric.rb

@@ -0,0 +1,16 @@
+class Numeric
+  
+  def to_money
+    Money.new(self)
+  end
+  
+  alias :cents :to_money
+  alias :cent  :to_money
+  
+  def dollars
+    Money.new(self*100)
+  end
+  
+  alias :dollar :dollars
+  
+end

data/lib/coinage/core_ext/string.rb

@@ -0,0 +1,7 @@
+class String
+  
+  def to_money
+    Money.new(self)
+  end
+  
+end

data/lib/coinage/exchange.rb

@@ -0,0 +1,5 @@
+require 'coinage/exchange/base'
+require 'coinage/exchange/none'
+require 'coinage/exchange/variable'
+require 'coinage/exchange/yahoo'
+require 'coinage/exchange/xurrency'

data/lib/coinage/exchange/base.rb

@@ -0,0 +1,23 @@
+module Coinage
+  module Exchange
+    module Base
+      
+      def rate(current, target)
+        validate_currencies(current, target)
+      end
+      
+      def supported_currencies
+        [:usd, :aud, :sgd]
+      end
+      
+      def validate_currency(*currencies)
+        currencies.each do |currency|
+          raise ArgumentError unless supported_currencies.include?(currency)
+        end
+      end
+      
+      alias :validate_currencies :validate_currency
+      
+    end
+  end
+end

data/lib/coinage/exchange/none.rb

@@ -0,0 +1,14 @@
+module Coinage
+  module Exchange
+    class None
+      
+      include Base
+      
+      def rate(current, target)
+        super(current, target)
+        1
+      end
+      
+    end
+  end
+end

data/lib/coinage/exchange/variable.rb

@@ -0,0 +1,14 @@
+module Coinage
+  module Exchange
+    class Variable
+      
+      include Base
+      
+      def rate(current, target)
+        validate_currencies(current, target)
+        2*rand
+      end
+      
+    end
+  end
+end

data/lib/coinage/exchange/xurrency.rb

@@ -0,0 +1,30 @@
+require 'rubygems'
+# Would use this, but it only reads in from a file!
+# require 'libxml' 
+require 'open-uri'
+require 'hpricot'
+
+module Coinage
+  module Exchange
+    class Xurrency
+      
+      include Base
+      
+      def rate(current, target)
+        super(current, target)
+        uri = "http://xurrency.com/1/#{current}/#{target}/feed"
+        
+        (Hpricot(open(uri).read)/'dc:value').inner_html
+      end
+      
+      # From:
+      # http://xurrency.com/currencies
+      def supported_currencies
+        [ :ars, :aud, :brl, :bgn, :cad, :cny, :cop, :hrk, :czk, :dkk, :eek, :eur, :hkd, :huf, :isk, :inr,
+        :jpy, :krw, :lvl, :ltl, :myr, :mxn, :ron, :try, :nzd, :nok, :php, :pln, :gbp, :rub, :sgd, :skk,
+        :zar, :lkr, :sek, :chf, :twd, :thb, :usd, :vef ]
+      end
+      
+    end
+  end
+end

data/lib/coinage/exchange/yahoo.rb

@@ -0,0 +1,9 @@
+module Coinage
+  module Exchange
+    class Yahoo
+      
+      include Base
+      
+    end
+  end
+end

data/lib/coinage/money.rb

@@ -0,0 +1,168 @@
+class Money
+  
+  @@default_currency = :usd
+  cattr_accessor :default_currency
+  
+  @@default_exchange = Coinage::Exchange::None.new
+  cattr_accessor :default_exchange
+  
+  attr_accessor :cents, :currency
+  attr_writer :exchange
+  
+  def initialize(cents=0, currency=self.class.default_currency)
+    @currency = currency
+    
+    case cents
+    when Float
+      @cents = cents_from_float(cents)
+    when String
+      @cents = cents_from_string(cents)
+    else
+      @cents = cents.to_i
+    end
+    
+  end
+  
+  def zero?
+    cents.zero?
+  end
+  
+  def to_money
+    self
+  end
+  
+  def to_i
+    cents
+  end
+  
+  def to_f
+    cents.to_f/100
+  end
+  
+  def dollars
+    (cents/100).round
+  end
+  
+  def round
+    (cents.to_f/100).round
+  end
+  
+  def exchange
+    @exchange || self.class.default_exchange
+  end
+  
+  def exchange_to!(target)
+    raise ArgumentError, "#{exchange.class} does not support conversions from #{currency.to_s.upcase}" unless exchange.supported_currencies.include?(currency)
+    raise ArgumentError, "#{exchange.class} does not support conversions to #{target.to_s.upcase}" unless exchange.supported_currencies.include?(target)
+    unless currency == target
+      self.cents, self.currency = cents * exchange.rate(currency, target), target
+    end
+    self
+  end
+  
+  def exchange_to(target)
+    dup.exchange_to!(target)
+  end
+  
+  def *(target)
+    case target
+    when Numeric
+      self.class.new( cents * target, currency )
+    when Money
+      self.class.new( cents * target.exchange_to(currency).cents, currency )
+    else
+      raise ArgumentError
+    end
+  end
+  
+  def /(target)
+    case target
+    when Numeric
+      self.class.new( cents / target, currency )
+    when Money
+      self.class.new( cents / target.exchange_to(currency).cents, currency )
+    else
+      raise ArgumentError
+    end
+  end
+  
+  def +(target)
+    case target
+    when Numeric
+      self.class.new( cents + target, currency )
+    when Money
+      self.class.new( cents + target.exchange_to(currency).cents, currency )
+    else
+      raise ArgumentError
+    end
+  end
+  
+  def -(target)
+    case target
+    when Numeric
+      self.class.new( cents - target, currency )
+    when Money
+      self.class.new( cents - target.exchange_to(currency).cents, currency )
+    else
+      raise ArgumentError
+    end
+  end
+  
+  # Uses == instead of .eql? to perform a type conversion between Float and Fixnum
+  def eql?(target)
+    case target
+    when Numeric
+      cents == target
+    when Money
+      if currency == target.currency
+        cents == target.cents
+      else
+        cents == target.exchange_to(currency).cents
+      end
+    else
+      false
+    end
+  end
+  
+  alias :== :eql?
+  alias :equal? :eql?
+  
+  def method_missing(method, *arguments)
+    if new_currency = extract_currency_from_method(method)
+      return exchange_to(new_currency)
+    else
+      super
+    end
+  end
+  
+  def coerce(other)
+    return self, other
+  end
+  
+  def to_s
+    to_f.to_s
+  end
+  
+  # def <=>
+  
+private
+  
+  def cents_from_float(cents)
+    cents.round.to_i
+  end
+  
+  def cents_from_string(cents, seperator='.')
+    if cents.include?(seperator)
+      cents.delete(seperator).to_i
+    else
+      cents.to_i*100
+    end
+  end
+  
+  def extract_currency_from_method(method)
+    return nil unless method = method.to_s.match(/^to_[[:lower:]]+$/)
+    expected_currency = method[0].delete('to_').to_sym
+    exchange.supported_currencies.include?(expected_currency) ? expected_currency : nil
+  end
+  
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification 
+name: coinage
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Chris Lloyd
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-09-02 00:00:00 +10:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Handle and convert your Money!
+email: christopher.lloyd@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+- LICENSE
+files: 
+- LICENSE
+- README.textile
+- Rakefile
+- lib/coinage
+- lib/coinage/core_ext
+- lib/coinage/core_ext/array.rb
+- lib/coinage/core_ext/class.rb
+- lib/coinage/core_ext/numeric.rb
+- lib/coinage/core_ext/string.rb
+- lib/coinage/core_ext.rb
+- lib/coinage/exchange
+- lib/coinage/exchange/base.rb
+- lib/coinage/exchange/none.rb
+- lib/coinage/exchange/variable.rb
+- lib/coinage/exchange/xurrency.rb
+- lib/coinage/exchange/yahoo.rb
+- lib/coinage/exchange.rb
+- lib/coinage/money.rb
+- lib/coinage.rb
+has_rdoc: true
+homepage: http://github.com/chrislloyd/coinage
+post_install_message: 
+rdoc_options: []
+
+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: "0"
+  version: 
+requirements: []
+
+rubyforge_project: coinage
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Handle and convert your Money!
+test_files: []
+