invoicing 0.1.0

data/lib/invoicing/connection_adapter_ext.rb

@@ -0,0 +1,44 @@
+module Invoicing
+  # Extensions specific to certain database adapters. Currently only MySQL and PostgreSQL are
+  # supported.
+  class ConnectionAdapterExt
+  
+    # Creates a database-specific SQL fragment for evaluating a three-legged conditional function
+    # in a query.
+    def self.conditional_function(condition, value_if_true, value_if_false)
+      case ActiveRecord::Base.connection.adapter_name
+        when "MySQL"
+          "IF(#{condition}, #{value_if_true}, #{value_if_false})"
+        when "PostgreSQL"
+          "CASE WHEN #{condition} THEN #{value_if_true} ELSE #{value_if_false} END"
+        else
+          raise "Database adapter #{ActiveRecord::Base.connection.adapter_name} not supported by invoicing gem"
+      end
+    end
+    
+    # Suppose <tt>A has_many B</tt>, and you want to select all As, counting for each A how many
+    # Bs it has. In MySQL you can just say:
+    #   SELECT A.*, COUNT(B.id) AS number_of_bs FROM A LEFT JOIN B on A.id = B.a_id GROUP BY A.id
+    # PostgreSQL, however, doesn't like you selecting a column from A if that column is neither
+    # in the <tt>GROUP BY</tt> clause nor wrapped in an aggregation function (even though it is
+    # implicitly grouped by through the fact that <tt>A.id</tt> is unique per row). Therefore
+    # for PostgreSQL, we need to explicitly list all of A's columns in the <tt>GROUP BY</tt>
+    # clause.
+    #
+    # This method takes a model class (a subclass of <tt>ActiveRecord::Base</tt>) and returns
+    # a string suitable to be used as the contents of the <tt>GROUP BY</tt> clause.
+    def self.group_by_all_columns(model_class)
+      case ActiveRecord::Base.connection.adapter_name
+        when "MySQL"
+          model_class.quoted_table_name + "." +
+            ActiveRecord::Base.connection.quote_column_name(model_class.primary_key)
+        when "PostgreSQL"
+          model_class.column_names.map{ |column|
+            model_class.quoted_table_name + "." + ActiveRecord::Base.connection.quote_column_name(column)
+          }.join(', ')
+        else
+          raise "Database adapter #{ActiveRecord::Base.connection.adapter_name} not supported by invoicing gem"
+      end
+    end
+  end
+end

data/lib/invoicing/countries/uk.rb

@@ -0,0 +1,24 @@
+module Invoicing
+  module Countries
+    module UK
+      # Extremely simplistic implementation of UK VAT. This needs to be fixed.
+      class VAT
+        def apply_tax(params)
+          params[:value] * BigDecimal('1.15')
+        end
+        
+        def remove_tax(params)
+          params[:value] / BigDecimal('1.15')
+        end
+        
+        def tax_info(params)
+          "(inc. VAT)"
+        end
+        
+        def tax_details(params)
+          "(including VAT at 15%)"
+        end
+      end
+    end
+  end
+end

data/lib/invoicing/currency_value.rb

@@ -0,0 +1,212 @@
+module Invoicing
+  # = Input and output of monetary values
+  #
+  # This module simplifies model objects which need to store monetary values. It automatically takes care
+  # of currency rounding conventions and formatting values for output.
+  #
+  # == General notes on currency precision and rounding
+  #
+  # It is important to deal carefully with rounding errors in accounts. If the figures don't add up exactly,
+  # you may have to pay for expensive accountant hours while they try to find out where the missing pennies or
+  # cents have gone -- better to avoid this trouble from the start. Because of this, it is strongly recommended
+  # that you use fixed-point or decimal datatypes to store any sort of currency amounts, never floating-point
+  # numbers.
+  #
+  # Keep in mind that not all currencies subdivide their main unit into 100 smaller units; storing four digits
+  # after the decimal point should be enough to allow you to expand into other currencies in future. Also leave
+  # enough headroom in case you ever need to use an inflated currency. For example,
+  # if you are using MySQL, <tt>decimal(20,4)</tt> may be a good choice for all your columns which store
+  # monetary amounts. The extra few bytes aren't going to cost you anything.
+  #
+  # On the other hand, it doesn't usually make sense to store monetary values with a higher precision than is
+  # conventional for a particular currency (usually this is related to the value of the smallest coin in
+  # circulation, but conventions may differ). For example, if your currency rounds to two decimal places, then
+  # you should also round every monetary amount to two decimal places before storing it. If you store values
+  # at a higher precision than you display, your numbers may appear to not add up correctly when you present
+  # them to users. Fortunately, this module automatically performs currency-specific rounding for you.
+  #
+  # == Using +acts_as_currency_value+
+  #
+  # This module simplifies model objects which need to store monetary values, by automatically taking care
+  # of currency rounding and formatting conventions. In a typical set-up, every model object which has one or
+  # more attributes storing monetary amounts (a price, a fee, a tax amount, a payment value, etc.) should also
+  # have a +currency+ column, which stores the ISO 4217 three-letter upper-case code identifying the currency.
+  # Annotate your model class with +acts_as_currency_value+, passing it a list of attribute names which store
+  # monetary amounts. If you refuse to store a +currency+ attribute, you may instead specify a default currency
+  # by passing a <tt>:currency_code => CODE</tt> option to +acts_as_currency_value+, but this is not recommended:
+  # even if you are only using one currency now, you may well expand into other currencies later. It is not
+  # possible to have multiple different currencies in the same model object.
+  #
+  # The +CurrencyValue+ module knows how to handle a set of default currencies (see +CURRENCIES+ below). If your
+  # currency is not supported in the way you want, you can extend/modify the hash yourself (please also send us
+  # a patch so that we can extend our list of inbuilt currencies):
+  #   Invoicing::CurrencyValue::CURRENCIES['HKD'] = {:symbol => 'HK$', :round => 0.10, :digits => 2}
+  # This specifies that the Hong Kong Dollar should be displayed using the 'HK$' symbol and two digits after the
+  # decimal point, but should always be rounded to the nearest 10 cents since the 10 cent coin is the smallest
+  # in circulation (therefore the second digit after the decimal point will always be zero).
+  #
+  # When that is done, you can use the model object normally, and rounding will occur automatically:
+  #   invoice.currency = 'HKD'
+  #   invoice.tax_amount = invoice.net_amount * TaxRates.default_rate_now  # 1234.56789
+  #   invoice.tax_amount == BigDecimal('1234.6')                           # true - rounded to nearest 0.01
+  #
+  # Moreover, you can just append +_formatted+ to your attribute name and get the value formatted for including
+  # in your views:
+  #   invoice.tax_amount_formatted                                         # 'HK$1,234.60'
+  # The string returned by a +_formatted+ method is UTF-8 encoded -- remember most currency symbols (except $)
+  # are outside basic 7-bit ASCII.
+  module CurrencyValue
+    
+    # Data about currencies, indexed by ISO 4217 code. (Currently a very short list, in need of extending.)
+    # The values are hashes, in which the following keys are recognised: 
+    # <tt>:round</tt>::  Smallest unit of the currency in normal use, to which values are rounded. Default is 0.01.
+    # <tt>:symbol</tt>:: Symbol or string usually used to denote the currency. Encoded as UTF-8. Default is ISO 4217 code.
+    # <tt>:suffix</tt>:: +true+ if the currency symbol appears after the number, +false+ if it appears before. Default +false+.
+    CURRENCIES = {
+      'EUR' => {:symbol => "\xE2\x82\xAC"},                   # Euro
+      'GBP' => {:symbol => "\xC2\xA3"},                       # Pound Sterling
+      'USD' => {:symbol => "$"},                              # United States Dollar
+      'CAD' => {:symbol => "$"},                              # Canadian Dollar
+      'AUD' => {:symbol => "$"},                              # Australian Dollar
+      'CNY' => {:symbol => "\xE5\x85\x83", :suffix => true},  # Chinese Yuan (RMB)
+      'INR' => {:symbol => "\xE2\x82\xA8"},                   # Indian Rupee
+      'JPY' => {:symbol => "\xC2\xA5",     :round  => 1}      # Japanese Yen
+    }
+    
+    module ActMethods
+      # Declares that the current model object has columns storing monetary amounts. Pass those attribute
+      # names to +acts_as_currency_value+. By default, we try to find an attribute or method called +currency+,
+      # which stores the 3-letter ISO 4217 currency code for a record; if that attribute has a different name,
+      # specify the name using the <tt>:currency</tt> option. For example:
+      #
+      #   class Price < ActiveRecord::Base
+      #     validates_numericality_of :net_amount, :tax_amount
+      #     validates_inclusion_of :currency_code, %w( USD GBP EUR JPY )
+      #     acts_as_currency_value :net_amount, :tax_amount, :currency => :currency_code
+      #   end
+      def acts_as_currency_value(*args)
+        Invoicing::ClassInfo.acts_as(Invoicing::CurrencyValue, self, args)
+
+        # Register callback if this is the first time acts_as_currency_value has been called
+        before_save :write_back_currency_values if currency_value_class_info.previous_info.nil?
+      end
+    end
+
+    # Format a numeric monetary value into a human-readable string, in the currency of the
+    # current model object.
+    def format_currency_value(value)
+      currency_value_class_info.format_value(self, value)
+    end
+    
+    
+    # Called automatically via +before_save+. Writes the result of converting +CurrencyValue+ attributes
+    # back to the actual attributes, so that they are saved in the database. (This doesn't happen in
+    # +convert_currency_values+ to avoid losing the +_before_type_cast+ attribute values.)
+    def write_back_currency_values
+      currency_value_class_info.all_args.each {|attr| write_attribute(attr, send(attr)) }
+    end
+    
+    protected :write_back_currency_values
+
+
+    class ClassInfo < Invoicing::ClassInfo::Base #:nodoc:
+      
+      def initialize(model_class, previous_info, args)
+        super
+        new_args.each{|attr| generate_attrs(attr)}
+      end
+      
+      # Generates the getter and setter method for attribute +attr+.
+      def generate_attrs(attr)
+        model_class.class_eval do
+          define_method(attr) do
+            currency_info = currency_value_class_info.currency_info_for(self)
+            return read_attribute(attr) if currency_info.nil?
+            round_factor = BigDecimal(currency_info[:round].to_s)
+            
+            value = currency_value_class_info.attr_conversion_input(self, attr)
+            value.nil? ? nil : (value / round_factor).round * round_factor
+          end
+          
+          define_method("#{attr}=") do |new_value|
+            write_attribute(attr, new_value)
+          end
+          
+          define_method("#{attr}_formatted") do
+            begin
+              format_currency_value(Kernel.Float(send("#{attr}_before_type_cast")))
+            rescue ArgumentError, TypeError
+              ''  # if <attr>_before_type_cast could not be converted to float
+            end
+          end
+        end
+      end
+      
+      # Returns the value of the currency code column of +object+, if available; otherwise the
+      # default currency code (set by the <tt>:currency_code</tt> option), if available; +nil+ if all
+      # else fails.
+      def currency_of(object)
+        if object.attributes.has_key?(method(:currency)) || object.respond_to?(method(:currency))
+          get(object, :currency)
+        else
+          all_options[:currency_code]
+        end
+      end
+      
+      # Returns a hash of information about the currency used by model +object+. Contains the following keys:
+      # <tt>:code</tt>::   The ISO 4217 code of the currency.
+      # <tt>:round</tt>::  Smallest unit of the currency in normal use, to which values are rounded. Default is 0.01.
+      # <tt>:symbol</tt>:: Symbol or string usually used to denote the currency. Encoded as UTF-8. Default is ISO 4217 code.
+      # <tt>:suffix</tt>:: +true+ if the currency symbol appears after the number, +false+ if it appears before.
+      # <tt>:space</tt>::  Whether or not to leave a space between the number and the currency symbol.
+      # <tt>:digits</tt>:: Number of digits to display after the decimal point.
+      def currency_info_for(object)
+        valid_options = [:symbol, :round, :suffix, :space, :digits, :format]
+        code = currency_of(object)
+        info = {:code => code, :symbol => code, :round => 0.01, :suffix => nil, :space => nil, :digits => nil}
+        if ::Invoicing::CurrencyValue::CURRENCIES.has_key? code
+          info.update(::Invoicing::CurrencyValue::CURRENCIES[code])
+        end
+        all_options.each_pair {|key, value| info[key] = value if valid_options.include? key }
+        
+        info[:suffix] = true if info[:suffix].nil? && (info[:code] == info[:symbol]) && !info[:code].nil?
+        info[:space]  = true if info[:space].nil?  && info[:suffix]
+        info[:digits] = -Math.log10(info[:round]).floor if info[:digits].nil?
+        info[:digits] = 0 if info[:digits] < 0
+        
+        info
+      end
+      
+      # Formats a numeric value as a nice currency string in UTF-8 encoding.
+      # +object+ is the model object carrying the value (used to determine the currency).
+      def format_value(object, value)
+        info = currency_info_for(object)
+        
+        # FIXME: take locale into account
+        value = "%.#{info[:digits]}f" % value
+        while value.sub!(/(\d+)(\d\d\d)/,'\1,\2'); end
+        if info[:space]
+          info[:suffix] ? "#{value} #{info[:symbol]}" : "#{info[:symbol]} #{value}"
+        else
+          info[:suffix] ? "#{value}#{info[:symbol]}" : "#{info[:symbol]}#{value}"
+        end
+      end
+      
+      # If other modules have registered callbacks for the event of reading a rounded attribute,
+      # they are executed here. +attr+ is the name of the attribute being read.
+      def attr_conversion_input(object, attr)
+        value = nil
+          
+        if callback = all_options[:conversion_input]
+          value = object.send(callback, attr)
+        end
+          
+        unless value
+          raw_value = object.read_attribute(attr)
+          value = BigDecimal.new(raw_value.to_s) unless raw_value.nil?
+        end
+        value
+      end
+    end
+  end
+end

data/lib/invoicing/find_subclasses.rb

@@ -0,0 +1,193 @@
+module Invoicing
+  # = Subclass-aware filtering by class methods
+  #
+  # Utility module which can be mixed into <tt>ActiveRecord::Base</tt> subclasses which use
+  # single table inheritance. It enables you to query the database for model objects based
+  # on static class properties without having to instantiate more model objects than necessary.
+  # Its methods should be used as class methods, so the module should be mixed in using +extend+.
+  #
+  # For example:
+  #
+  #   class Product < ActiveRecord::Base
+  #     extend Invoicing::FindSubclasses
+  #     def self.needs_refrigeration; false; end
+  #   end
+  #   
+  #   class Food < Product; end
+  #   class Bread < Food; end
+  #   class Yoghurt < Food
+  #     def self.needs_refrigeration; true; end
+  #   end
+  #   class GreekYoghurt < Yoghurt; end
+  #   
+  #   class Drink < Product; end
+  #   class SoftDrink < Drink; end
+  #   class Smoothie < Drink
+  #     def self.needs_refrigeration; true; end
+  #   end
+  #
+  # So we know that all +Yoghurt+ and all +Smoothie+ objects need refrigeration (including subclasses
+  # of +Yoghurt+ and +Smoothly+, unless they override +needs_refrigeration+ again), and the others
+  # don't. This fact is defined through a class method and not stored in the database. It needn't
+  # necessarily be constant -- you could make +needs_refrigeration+ return +true+ or +false+
+  # depending on the current temperature, for example.
+  #
+  # Now assume that in your application you need to query all objects which need refrigeration
+  # (and maybe also satisfy some other conditions). Since the database knows nothing about
+  # +needs_refrigeration+, what you would have to do traditionally is to instantiate all objects
+  # and then to filter them yourself, i.e.
+  #
+  #   Product.find(:all).select{|p| p.class.needs_refrigeration}
+  #
+  # However, if only a small proportion of your products needs refrigeration, this requires you to
+  # load many more objects than necessary, putting unnecessary load on your application. With the
+  # +FindSubclasses+ module you can let the database do the filtering instead:
+  #
+  #   Product.find(:all, :conditions => {:needs_refrigeration => true})
+  #
+  # You could even define a named scope to do the same thing:
+  #
+  #   class Product
+  #     named_scope :refrigerated_products, :conditions => {:needs_refrigeration => true})
+  #   end
+  #
+  # Much nicer! The condition looks precisely like a condition on a database table column, even
+  # though it actually refers to a class method. Under the hood, this query translates into:
+  #
+  #   Product.find(:all, :conditions => {:type => ['Yoghurt', 'GreekYoghurt', 'Smoothie']})
+  #
+  # And of course you can combine it with normal conditions on database table columns. If there
+  # is a table column and a class method with the same name, +FindSublasses+ remains polite and lets
+  # the table column take precedence.
+  #
+  # == How it works
+  #
+  # +FindSubclasses+ relies on having a list of all subclasses of your single-table-inheritance
+  # base class; then, if you specify a condition with a key which has no corresponding database
+  # table column, +FindSubclasses+ will check all subclasses for the return value of a class
+  # method with that name, and search for the names of classes which match the condition.
+  #
+  # Purists of object-oriented programming will most likely find this appalling, and it's important
+  # to know the limitations. In Ruby, a class can be notified if it subclassed, by defining the
+  # <tt>Class#inherited</tt> method; we use this to gather together a list of subclasses. Of course,
+  # we won't necessarily know about every class in the world which may subclass our class; in
+  # particular, <tt>Class#inherited</tt> won't be called until that subclass is loaded.
+  # 
+  # If you're including the Ruby files with the subclass definitions using +require+, we will learn
+  # about subclasses as soon as they are defined. However, if class loading is delayed until a 
+  # class is first used (for example, <tt>ActiveSupport::Dependencies</tt> does this with model
+  # objects in Rails projects), we could run into a situation where we don't yet know about all 
+  # subclasses used in a project at the point where we need to process a class method condition.
+  # This would cause us to omit some objects we should have found.
+  #
+  # To prevent this from happening, this module searches for all types of object currently stored
+  # in the table (along the lines of <tt>SELECT DISTINCT type FROM table_name</tt>), and makes sure
+  # all class names mentioned there are loaded before evaluating a class method condition. Note that
+  # this doesn't necessarily load all subclasses, but at least it loads those which currently have
+  # instances stored in the database, so we won't omit any objects when selecting from the table.
+  # There is still room for race conditions to occur, but otherwise it should be fine. If you want
+  # to be on the safe side you can ensure all subclasses are loaded when your application
+  # initialises -- but that's not completely DRY ;-)
+  module FindSubclasses
+    
+    # Overrides <tt>ActiveRecord::Base.sanitize_sql_hash_for_conditions</tt> since this is the method
+    # used to transform a hash of conditions into an SQL query fragment. This overriding method
+    # searches for class method conditions in the hash and transforms them into a condition on the
+    # class name. All further work is delegated back to the superclass method.
+    #
+    # Condition formats are very similar to those accepted by +ActiveRecord+:
+    #   {:my_class_method => 'value'}     # known_subclasses.select{|cls| cls.my_class_method == 'value' }
+    #   {:my_class_method => [1, 2]}      # known_subclasses.select{|cls| [1, 2].include?(cls.my_class_method) }
+    #   {:my_class_method => 3..6}        # known_subclasses.select{|cls| (3..6).include?(cls.my_class_method) }
+    #   {:my_class_method => true}        # known_subclasses.select{|cls| cls.my_class_method }
+    #   {:my_class_method => false}       # known_subclasses.reject{|cls| cls.my_class_method }
+    def sanitize_sql_hash_for_conditions(attrs, table_name = quoted_table_name)
+      new_attrs = {}
+      
+      attrs.each_pair do |attr, value|
+        attr = attr_base = attr.to_s
+        attr_table_name = table_name
+
+        # Extract table name from qualified attribute names
+        attr_table_name, attr_base = attr.split('.', 2) if attr.include?('.')
+        
+        if columns_hash.include?(attr_base) || ![self.table_name, quoted_table_name].include?(attr_table_name)
+          new_attrs[attr] = value   # Condition on a table column, or another table -- pass through unmodified
+        else
+          begin
+            matching_classes = select_matching_subclasses(attr_base, value)
+            new_attrs["#{self.table_name}.#{inheritance_column}"] = matching_classes.map{|cls| cls.name.to_s}
+          rescue NoMethodError
+            new_attrs[attr] = value # If the class method doesn't exist, fall back to passing condition through unmodified
+          end
+        end
+      end
+
+      super(new_attrs, table_name)
+    end
+    
+    # Returns a list of those classes within +known_subclasses+ which match a condition
+    # <tt>method_name => value</tt>. May raise +NoMethodError+ if a class object does not
+    # respond to +method_name+. 
+    def select_matching_subclasses(method_name, value, table = table_name, type_column = inheritance_column)
+      known_subclasses(table, type_column).select do |cls|
+        returned = cls.send(method_name)
+        (returned == value) or case value
+          when true         then !!returned
+          when false        then !returned
+          when Array, Range then value.include?(returned)
+        end
+      end
+    end
+    
+    # Ruby callback which is invoked when a subclass is created. We use this to build a list of known
+    # subclasses.
+    def inherited(subclass)
+      remember_subclass subclass
+      super
+    end
+    
+    # Add +subclass+ to the list of know subclasses of this class.
+    def remember_subclass(subclass)
+      @known_subclasses ||= [self]
+      @known_subclasses << subclass unless @known_subclasses.include? subclass
+      self.superclass.remember_subclass(subclass) if self.superclass.respond_to? :remember_subclass
+    end
+    
+    # Return the list of all known subclasses of this class, if necessary checking the database for
+    # classes which have not yet been loaded.
+    def known_subclasses(table = table_name, type_column = inheritance_column)
+      load_all_subclasses_found_in_database(table, type_column)
+      @known_subclasses ||= [self]
+    end
+    
+  private
+    # Query the database for all qualified class names found in the +type_column+ column
+    # (called +type+ by default), and check that classes of that name have been loaded by the Ruby
+    # interpreter. If a type name is encountered which cannot be loaded,
+    # <tt>ActiveRecord::SubclassNotFound</tt> is raised.
+    #
+    # TODO: Cache this somehow, to avoid querying for class names more often than necessary. It's not
+    # obvious though how to do this best -- a different Ruby instance may insert a row into the
+    # database with a type which is not yet loaded in this interpreter. Maybe reloading the list
+    # of types from the database every 30-60 seconds or so would be a compromise?
+    def load_all_subclasses_found_in_database(table = table_name, type_column = inheritance_column)
+      quoted_table_name = connection.quote_table_name(table)
+      quoted_inheritance_column = connection.quote_column_name(type_column)
+      query = "SELECT DISTINCT #{quoted_inheritance_column} FROM #{quoted_table_name}"
+      for subclass_name in connection.select_all(query).map{|record| record[type_column]}
+        unless subclass_name.blank? # empty string or nil means base class
+          begin
+            compute_type(subclass_name)
+          rescue NameError
+            raise ActiveRecord::SubclassNotFound, # Error message borrowed from ActiveRecord::Base
+              "The single-table inheritance mechanism failed to locate the subclass: '#{subclass_name}'. " +
+              "This error is raised because the column '#{type_column}' is reserved for storing the class in case of inheritance. " +
+              "Please rename this column if you didn't intend it to be used for storing the inheritance class " +
+              "or overwrite #{self.to_s}.inheritance_column to use another column for that information."
+          end
+        end
+      end
+    end
+  end
+end