easy_money 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Allen Fair
+
+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.rdoc

@@ -0,0 +1,108 @@
+= Easy Money!
+
+A Ruby mixin library to add simple money display and editing using data stored as an integer in 
+cents or other precision or currency.
+Easy Money is a simpler alternative to the "money" gem, and easier to use, hence the name.
+
+Float types are not good for storing and computing financial data because of rounding and conversion
+between floats and decimal precision and slower performance compared to integer arithmetic. Integers
+are preferred in this case, with a dollar amount ($1.00) stored as cents (100) internally.
+
+
+Easy Money will also handle any float data stored as integer in the database for this reason, such
+as FM Radio Frequencies (88.1 FM) or an NTRP Tennis Rating (4.5).
+
+== Quick Start
+Easy Money works in any Ruby class, it does not require Active Record or other ORM. 
+Its default setting allow it to work on US Dollar amounts stored in cents, but is easily configured.
+
+First, install this from gemcutter
+ gem install easy_money
+
+Next, you need to configure your app to use it, by either:
+ require 'rubygems'                 # Rails application, no framework
+ require 'easy_money'               # 
+ 
+ config.gem 'easy_money'            # Rails 2.x, in your ./config/environment.rb
+
+ gem 'easy_money'                   # Rails 3.x, in your ./Gemfile
+
+Mixin the EasyMoney module into the (model) class you need, and declare the 
+attributes (columns) you wish you have the easy_money helpers
+
+ class Ledger
+   include EasyMoney
+   attr_accessor :amount, :euro     # Integer value of cents
+   easy_money :amount               # Creates amount_money() and amount_money=() methods
+   easy_money :amount, :units=>"dollars", :unit=>'$', :negative=>'%.2f CR'
+                                    # Creates amount_dollars() and amount_dollars=() methods
+ end
+
+ ledger = Ledger.new
+ ledger.amount = 100                # 100 cents = $1.00
+ ledger.amount_money                #=> "1.00"
+ ledger.amount_money = "-123.45"
+ ledger.amount                      #=> -12345 (cents)
+ ledger.amount_money(:negative=>'%.2f CR', :zero=>'Free') # Uses these formats 
+ ledger.amount_dollars              #=> "$123.45 CR"
+
+ # Track the bets of the Gamesters of Triskelion on their drill thrall competitions.
+ class ProviderWagers < ActiveRecord::Base
+   include EasyMoney
+   easy_money :quatloos, :units=>'quatloos', :precision=>3, 
+     :zero=>'even', :nil=>'no bet', :negative=>'%.3f Loss', :unit=>'Q',
+     :negative_regex=>/^(-?)(.+\d)\s*Loss/i
+                                    # creates amount_quatloos(), amount_quatloos=()
+ end
+
+ # in your views
+ <%= f.text_field :amount_quatloos %>  # -12000 => "Q12.000 Loss"
+
+Options for Easy Money calls:
+* :money_method - Use this as the alternative name to the money-access methods
+* :units - Use this as an alternative suffix name to the money methods ('dollars' gives 'xx_dollars')
+* :precision - The number of digits implied after the decimal, default is 2
+* :separator - The character to use after the integer part, default is '.'
+* :delimiter - The character to use between every 3 digits of the integer part, default none
+* :positive - The sprintf format to use for positive numbers, default is based on precision
+* :negative - The sprintf format to use for negative numbers, default is same as :positive
+* :zero - The sprintf format to use for zero, default is same as :positive
+* :nil - The sprintf format to use for nil values, default none
+* :unit - Prepend this to the front of the money value, say '$', default none
+* :blank - Return this value when the money string is empty or has no digits on assignment
+* :negative_regex - A Regular Expression used to determine if a number is negative (and without a - sign), defaults to having a "CR" after the number
+
+== Easy Money Formatters
+You can also call or build your own custom conversions. Ensure that
+you can convert between the integer and money forms if you need to.
+
+The "money" type is a string, sutitable for human editing, and will convert back into 
+integer type. If you override the formatting options, test that your money result 
+string will convert properly back to the original integer value.
+
+  include EasyMoney
+  ...
+  puts EasyMoney.money_to_integer( money_string, :option=>value, ... )
+  puts EasyMoney.integer_to_money( cents_integer, :option=>value, ... )
+  puts EasyMoney.integer_to_float( cents_integer, :option=>value, ... )
+  puts EasyMoney.float_to_integer( money_float, :option=>value, ... )
+
+  EasyMoney.integer_to_float( nil, blank:0.0 ) #=> 0.0  [Ruby 1.9.1 Syntax]
+  EasyMoney.integer_to_float( 12345, :precision=>3 ) #=> 12.345
+  EasyMoney.float_to_integer(12.345111, :precision=>3 ) #=> 12345
+
+The options to these methods are the same as the #easy_money declarations
+
+
+== To Do
+ 
+* Validate Money string format
+* Global configuration for currency settings
+* Explore rounding vs. truncation issues
+* Use a Locale and I18n on money formatting, without introducing dependencies (perhaps by injection)?
+* Explore inegration of Rails' NumberHelper methods, but not require ActionView
+* Custom converters (useful for say, converting bytes to Gigabytes)?
+
+== Copyright
+
+Copyright (c) 2010 Allen Fair. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "easy_money"
+    gem.summary = %Q{Easy Money handling for Rails/ActiveRecord}
+    gem.description = %Q{Easy Money handling for Rails/ActiveRecord}
+    gem.email = "allen.fair@gmail.com"
+    gem.homepage = "http://github.com/afair/easy_money"
+    gem.authors = ["Allen Fair"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "easy_money #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/easy_money.gemspec

@@ -0,0 +1,51 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{easy_money}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Allen Fair"]
+  s.date = %q{2010-02-23}
+  s.description = %q{Easy Money handling for Rails/ActiveRecord}
+  s.email = %q{allen.fair@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "easy_money.gemspec",
+     "lib/easy_money.rb",
+     "test/helper.rb",
+     "test/test_easy_money.rb"
+  ]
+  s.homepage = %q{http://github.com/afair/easy_money}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Easy Money handling for Rails/ActiveRecord}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_easy_money.rb"
+  ]
+
+  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/easy_money.rb

@@ -0,0 +1,124 @@
+# EasyMoney - Ruby class mixin library to add money helpers to attribute/methods
+module EasyMoney
+
+  def self.included(base) #:nodoc:
+    base.extend( ClassMethods )
+  end
+
+  module ClassMethods
+
+    # Creates an money instance method for the given method, named "#{method}_money" which returns
+    # a formatted money string, and a #{method}_money= method used to set an edited money string.
+    # The original method stores the value as integer (cents, or other precision/currency setting). Options:
+    # * :money_method - Use this as the alternative name to the money-access methods
+    # * :units - Use this as an alternative suffix name to the money methods ('dollars' gives 'xx_dollars')
+    # * :precision - The number of digits implied after the decimal, default is 2
+    # * :separator - The character to use after the integer part, default is '.'
+    # * :delimiter - The character to use between every 3 digits of the integer part, default none
+    # * :positive - The sprintf format to use for positive numbers, default is based on precision
+    # * :negative - The sprintf format to use for negative numbers, default is same as :positive
+    # * :zero - The sprintf format to use for zero, default is same as :positive
+    # * :nil - The sprintf format to use for nil values, default none
+    # * :unit - Prepend this to the front of the money value, say '$', default none
+    # * :blank - Return this value when the money string is empty or has no digits on assignment
+    # * :negative_regex - A Regular Expression used to determine if a number is negative (and without a - sign)
+    #
+    def easy_money(method, *args)
+      opt = args.last.is_a?(Hash) ? args.pop : {}
+      money_method = opt.delete(:money_method) || "#{method}_#{opt.delete(:units)||'money'}"
+
+      class_eval %Q(
+      def #{money_method}(*args)
+        opt = args.last.is_a?(Hash) ? args.pop : {}
+        EasyMoney.integer_to_money( #{method}, #{opt.inspect}.merge(opt))
+      end
+
+      def #{money_method}=(v, *args)
+        opt = args.last.is_a?(Hash) ? args.pop : {}
+        self.#{method} = EasyMoney.money_to_integer( v, #{opt.inspect}.merge(opt))
+      end
+      )
+    end
+  end
+
+  # Returns the money string of the given integer value. Uses relevant options from #easy_money
+  def self.integer_to_money(value, *args)
+    opt = args.last.is_a?(Hash) ? args.pop : {}
+    opt[:positive] ||= "%.#{opt[:precision]||2}f"
+    pattern = 
+      if value.nil?
+        value = 0
+        opt[:nil] || opt[:positive]
+      else
+        case value <=> 0
+        when 1 then opt[:positive]
+        when 0 then opt[:zero] || opt[:positive]
+        else  
+          value = -value if opt[:negative] && opt[:negative] != opt[:positive]
+          opt[:negative] || opt[:positive]
+        end
+      end
+    value = self.format_money( value, pattern, opt)
+    value = opt[:unit]+value if opt[:unit]
+    value.gsub!(/\./,opt[:separator]) if opt[:separator]
+    if opt[:delimiter] && (m = value.match(/^(\D*)(\d+)(.*)/))
+      # Adapted From Rails' ActionView::Helpers::NumberHelper
+      n = m[2].gsub(/(\d)(?=(\d\d\d)+(?!\d))/, "\\1#{opt[:delimiter]}")
+      value=m[1]+n+m[3]
+    end
+    value
+  end
+
+  def self.integer_to_float(value, *args)
+    opt = args.last.is_a?(Hash) ? args.pop : {}
+    return (opt[:blank]||nil) if value.nil?
+    value = 1.0 * value / (10**(opt[:precision]||2)) 
+  end
+
+  # Returns the integer of the given money string. Uses relevant options from #easy_money
+  def self.money_to_integer(value, *args)
+    opt = args.last.is_a?(Hash) ? args.pop : {}
+    value.gsub!(opt[:delimiter],'') if opt[:delimiter]
+    value.gsub!(opt[:separator],'.') if opt[:separator]
+    value.gsub!(/^[^\d\.\-\,]+/,'')
+    return (opt[:blank]||nil) unless value =~ /\d/
+    m = value.to_s.match(opt[:negative_regex]||/^(-?)(.+\d)\s*cr/i)
+    value = value.match(/^-/) ? m[2] : "-#{m[2]}" if m && m[2]
+
+    # Money string ("123.45") to proper integer withough passing through the float transformation
+    match = value.match(/(-?\d*)\.?(\d*)/)
+    return 0 unless match
+    value = match[1].to_i * (10 ** (opt[:precision]||2))
+    cents = match[2]
+    cents = cents + '0' while cents.length < (opt[:precision]||2)
+    cents = cents.to_s[0,opt[:precision]||2]
+    value += cents.to_i * (value<0 ? -1 : 1)
+    value
+  end
+
+  # Returns the integer (cents) value from a Float
+  def self.float_to_integer(value, *args)
+    opt = args.last.is_a?(Hash) ? args.pop : {}
+    return (opt[:blank]||nil) if value.nil?
+    value = (value.to_f*(10**((opt[:precision]||2)+1))).to_i/10 # helps rounding 4.56 -> 455 ouch!
+  end
+  
+  # Replacing the sprintf function to deal with money as float. "... %[flags]m ..."
+  def self.format_money(value, pattern="%.2m", *args)
+    opt = args.last.is_a?(Hash) ? args.pop : {}
+    sign = value < 0 ? -1 : 1
+    dollars, cents = value.abs.divmod( 10 ** (opt[:precision]||2))
+    dollars *= sign
+    parts = pattern.match(/^(.*)%([-\. \d+0]*)[fm](.*)/)
+    return pattern unless parts
+    intdec = parts[2].match(/(.*)\.(\d*)/)
+    dprec, cprec = intdec ? [intdec[1], intdec[2]] : ['', '']
+    dollars = sprintf("%#{dprec}d", dollars)
+    cents = '0' + cents.to_s while cents.to_s.length < (opt[:precision]||2)
+    cents = cents.to_s[0,cprec.to_i]
+    cents = cents + '0' while cents.length < cprec.to_i
+    value = parts[1] + "#{(dollars.to_i==0 && sign==-1) ? '-' : '' }#{dollars}#{cents>' '? '.':''}#{cents}" + parts[3]
+    value
+  end
+
+end

data/test/helper.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'easy_money'
+
+class Test::Unit::TestCase
+end
+
+class Sample
+  include EasyMoney
+  attr_accessor :price, :balance
+  easy_money :price
+  easy_money :balance
+end

data/test/test_easy_money.rb

@@ -0,0 +1,87 @@
+require 'helper'
+
+class TestEasyMoney < Test::Unit::TestCase
+
+  def test_include
+    sample = Sample.new
+    flunk "no price_money method" unless sample.respond_to?(:price_money)
+    flunk "no price_money= method" unless sample.respond_to?(:price_money=)
+  end
+
+  def test_method_money
+    s = Sample.new
+    [ 10000, 123456, 0, -1 -9876 ].each do |p|
+      s.price = p
+      m = s.price_money
+      s.price_money = m
+      flunk "Assignment error: p=#{p} m=#{m} price=#{s.price}" unless s.price = p
+    end
+  end
+
+  def test_method_money=
+    s = Sample.new
+    { "0.00"=>0, "12.34"=>1234, "-1.2345"=>-123, "12"=>1200, "4.56CR"=>-456 }.each do |m,p|
+      s.price_money = m
+      flunk "Assignment error: p=#{p} m=#{m} price=#{s.price}" unless s.price = p
+    end
+  end
+
+  def test_integer_to_money
+    assert EasyMoney.integer_to_money(123) == '1.23'
+    assert EasyMoney.integer_to_money(-12333) == '-123.33'
+    assert EasyMoney.integer_to_money(0) == '0.00'
+    assert EasyMoney.integer_to_money(nil, :nil=>'?') == '?'
+    assert EasyMoney.integer_to_money(-1, :negative=>'%.2f CR') == '0.01 CR'
+    assert EasyMoney.integer_to_money(0, :zero=>'free') == 'free'
+    assert EasyMoney.integer_to_money(100, :unit=>'$') == '$1.00'
+    assert EasyMoney.integer_to_money(100, :separator=>',') == '1,00'
+    assert EasyMoney.integer_to_money(12345678900, :separator=>',', :delimiter=>'.') == '123.456.789,00'
+    assert EasyMoney.integer_to_money(333, :precision=>3) == '0.333'
+    assert EasyMoney.integer_to_money(111, :precision=>1) == '11.1'
+    assert EasyMoney.integer_to_money(111, :precision=>0) == '111'
+  end
+
+  def test_money_to_integer
+    assert EasyMoney.money_to_integer('1.23'        ) == 123
+    assert EasyMoney.money_to_integer('0.00'        ) == 0
+    assert EasyMoney.money_to_integer('-1.23'       ) == -123
+    assert EasyMoney.money_to_integer('1.23 CR'     ) == -123
+    assert EasyMoney.money_to_integer('$-2.34 CR'   ) == 234
+    assert EasyMoney.money_to_integer('   1.234'    ) == 123
+    assert EasyMoney.money_to_integer('$1'          ) == 100
+    assert EasyMoney.money_to_integer('1'           ) == 100
+    assert EasyMoney.money_to_integer(''            ) == nil
+    assert EasyMoney.money_to_integer('1,00', :separator=>',',:delimiter=>'.') == 100
+    assert EasyMoney.money_to_integer('$123.456.789,00 CR', :separator=>',',:delimiter=>'.') == -12345678900
+    assert EasyMoney.money_to_integer('4.44', :precision=>4 ) == 44400
+    assert EasyMoney.money_to_integer('4.44', :precision=>0 ) == 4
+  end
+
+  def test_float_to_integer
+    assert EasyMoney.float_to_integer(1.00   ) == 100
+    assert EasyMoney.float_to_integer(1.001  ) == 100
+    assert EasyMoney.float_to_integer(-1.23  ) == -123
+    assert EasyMoney.float_to_integer(9.0    ) == 900
+    assert EasyMoney.float_to_integer(nil    ) == nil
+    assert EasyMoney.float_to_integer(0.00   ) == 0
+  end
+
+  def test_integer_to_float
+    assert EasyMoney.integer_to_float(1      ) == 0.01
+    assert EasyMoney.integer_to_float(0      ) == 0.0
+    assert EasyMoney.integer_to_float(-100   ) == -1.00
+    assert EasyMoney.integer_to_float(nil    ) == nil
+    assert EasyMoney.integer_to_float(9999888, :precision=>3 ) == 9999.888
+  end
+  
+  def test_format_money
+    assert EasyMoney.format_money(12345) == '123.45'
+    assert EasyMoney.format_money(12345, "%07.2m") == '0000123.45'
+    assert EasyMoney.format_money(12345, "%07.3m") == '0000123.450'
+    assert EasyMoney.format_money(12345, "%m") == '123'
+    assert EasyMoney.format_money(12345, "free") == 'free'
+    assert EasyMoney.format_money(-12345) == '-123.45'
+    assert EasyMoney.format_money(-12345, "%07.1m") == '-000123.4'
+    assert EasyMoney.format_money(-1) == '-0.01'
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: easy_money
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Allen Fair
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-23 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: Easy Money handling for Rails/ActiveRecord
+email: allen.fair@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- easy_money.gemspec
+- lib/easy_money.rb
+- test/helper.rb
+- test/test_easy_money.rb
+has_rdoc: true
+homepage: http://github.com/afair/easy_money
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Easy Money handling for Rails/ActiveRecord
+test_files: 
+- test/helper.rb
+- test/test_easy_money.rb