invoicing 0.1.0

data/lib/invoicing/price.rb

@@ -0,0 +1,9 @@
+module Invoicing
+  module Price
+    module ActMethods
+      def acts_as_price(*args)
+        
+      end
+    end
+  end
+end

data/lib/invoicing/tax_rate.rb

@@ -0,0 +1,9 @@
+module Invoicing
+  module TaxRate
+    module ActMethods
+      def acts_as_tax_rate(*args)
+        
+      end
+    end
+  end
+end

data/lib/invoicing/taxable.rb

@@ -0,0 +1,355 @@
+# encoding: utf-8
+
+module Invoicing
+  # = Computation of tax on prices
+  #
+  # This module provides a general-purpose framework for calculating tax. Its most common application
+  # will probably be for computing VAT/sales tax on the price of your product, but since you can easily
+  # attach your own tax computation logic, it can apply in a broad variety of different situations.
+  #
+  # Computing the tax on a price may be as simple as multiplying it with a constant factor, but in most
+  # cases it will be more complicated. The tax rate may change over time (see +TimeDependent+), may vary
+  # depending on the customer currently viewing the page (and the country in which they are located),
+  # and may depend on properties of the object to which the price belongs. This module does not implement
+  # any specific computation, but makes easy to implement specific tax regimes with minimal code duplication.
+  #
+  # == Using taxable attributes in a model
+  #
+  # If you have a model object (a subclass of <tt>ActiveRecord::Base</tt>) with a monetary quantity
+  # (such as a price) in one or more of its database columns, you can declare that those columns/attributes
+  # are taxable, for example:
+  #
+  #   class MyProduct < ActiveRecord::Base
+  #     acts_as_taxable :normal_price, :promotion_price, :tax_logic => Invoicing::Countries::UK::VAT.new
+  #   end
+  #
+  # In the taxable columns (+normal_price+ and +promotion_price+ in this example) you <b>must always
+  # store values excluding tax</b>. The option <tt>:tax_logic</tt> is mandatory, and you must give it
+  # an instance of a 'tax logic' object; you may use one of the tax logic implementations provided with
+  # this framework, or write your own. See below for details of what a tax logic object needs to do.
+  #
+  # Your database table should also contain a column +currency+, in which you store the ISO 4217
+  # three-letter upper-case code identifying the currency of the monetary amounts in the same table row.
+  # If your currency code column has a name other than +currency+, you need to specify the name of that
+  # column to +acts_as_taxable+ using the <tt>:currency => '...'</tt> option.
+  #
+  # For each attribute which you declare as taxable, several new methods are generated on your model class:
+  #
+  # <tt><attr></tt>::                        Returns the amount of money excluding tax, as stored in the database,
+  #                                          subject to the model object's currency rounding conventions.
+  # <tt><attr>=</tt>::                       Assigns a new value (exclusive of tax) to the attribute.
+  # <tt><attr>_taxed</tt>::                  Returns the amount of money including tax, as computed by the tax
+  #                                          logic, subject to the model object's currency rounding conventions.
+  # <tt><attr>_taxed=</tt>::                 Assigns a new value (including tax) to the attribute.
+  # <tt><attr>_tax_rounding_error</tt>::     Returns a number indicating how much the tax-inclusive value of the
+  #                                          attribute has changed as a result of currency rounding. See the section
+  #                                          'currency rounding errors' below. +nil+ if the +_taxed=+ attribute
+  #                                          has not been assigned.
+  # <tt><attr>_tax_info</tt>::               Returns a short string to inform a user about the tax status of
+  #                                          the value returned by <tt><attr>_taxed</tt>; this could be
+  #                                          "inc. VAT", for example, if the +_taxed+ attribute includes VAT.
+  # <tt><attr>_tax_details</tt>::            Like +_tax_info+, but a longer string for places in the user
+  #                                          interface where more space is available. For example, "including
+  #                                          VAT at 15%".
+  # <tt><attr>_with_tax_info</tt>::          Convenience method for views: returns the attribute value including
+  #                                          tax, formatted as a human-friendly currency string in UTF-8, with
+  #                                          the return value of +_tax_info+ appended. For example,
+  #                                          "AU$1,234.00 inc. GST".
+  # <tt><attr>_with_tax_details</tt>::       Like +_with_tax_info+, but using +_tax_details+. For example,
+  #                                          "AU$1,234.00 including 10% Goods and Services Tax".
+  # <tt><attr>_taxed_before_type_cast</tt>:: Returns any value which you assign to <tt><attr>_taxed=</tt> without
+  #                                          converting it first. This means you to can use +_taxed+ attributes as
+  #                                          fields in Rails forms and get the expected behaviour of form validation.
+  #
+  # +acts_as_currency+ is automatically called for all attributes given to +acts_as_taxable+, as well as all
+  # generated <tt><attr>_taxed</tt> attributes. This means you get automatic currency-specific rounding
+  # behaviour as documented in the +CurrencyValue+ module, and you get two additional methods for free:
+  # <tt><attr>_formatted</tt> and <tt><attr>_taxed_formatted</tt>, which return the untaxed and taxed amounts
+  # respectively, formatted as a nice human-friendly string.
+  #
+  # The +Taxable+ module automatically converts between taxed and untaxed attributes. This works as you would
+  # expect: you can assign to a taxed attribute and immediately read from an untaxed attribute, or vice versa.
+  # When you store the object, only the untaxed value is written to the database. That way, if the tax rate
+  # changes or you open your business to overseas customers, nothing changes in your database.
+  #
+  # == Using taxable attributes in views and forms
+  #
+  # The tax logic object allows you to have one single place in your application where you declare which products
+  # are seen by which customers at which tax rate. For example, if you are a VAT registered business in an EU
+  # country, you always charge VAT at your home country's rate to customers within your home country; however,
+  # to a customer in a different EU country you do not charge any VAT if you have received a valid VAT registration
+  # number from them. You see that this logic can easily become quite complicated. This complexity should be
+  # encapsulated entirely within the tax logic object, and not require any changes to your views or controllers if
+  # at all possible.
+  #
+  # The way to achieve this is to <b>always use the +_taxed+ attributes in views and forms</b>, unless you have a
+  # very good reason not to. The value returned by <tt><attr>_taxed</tt>, and the value you assign to
+  # <tt><attr>_taxed=</tt>, do not necessarily have to include tax; for a given customer and product, the tax may
+  # be zero-rated or not applicable, in which case their numeric value will be the same as the untaxed attributes.
+  # The attributes are called +_taxed+ because they may be taxed, not because they necessarily always are. It is
+  # up to the tax logic to decide whether to return the same number, or one modified to include tax.
+  #
+  # The purpose of the +_tax_info+ and +_tax_details+ methods is to clarify the tax status of a given number to the
+  # user; if the number returned by the +_taxed+ attribute does not contain tax for whatever reason, +_tax_info+ for
+  # the same attribute should say so.
+  #
+  # Using these attributes, views can be kept very simple:
+  #
+  #   <h1>Products</h1>
+  #   <table>
+  #     <tr>
+  #       <th>Name</th>
+  #       <th>Price</th>
+  #     </tr>
+  #   <% for product in @products %>
+  #     <tr>
+  #       <td><%=h product.name %></td>
+  #       <td><%=h product.price_with_tax_info %></td>                                # e.g. "$25.80 (inc. tax)"
+  #     </tr>
+  #   <% end %>
+  #   </table>
+  #   
+  #   <h1>New product</h1>
+  #   <% form_for(@product) do |f| %>
+  #     <%= f.error_messages %>
+  #     <p>
+  #       <%= f.label :name, "Product name:" %><br />
+  #       <%= f.text_field :name %>
+  #     </p>
+  #     <p>
+  #       <%= f.label :price_taxed, "Price #{h(@product.price_tax_info)}:" %><br />   # e.g. "Price (inc. tax):"
+  #       <%= f.text_field :price_taxed %>
+  #     </p>
+  #   <% end %>
+  #
+  # If this page is viewed by a user who shouldn't be shown tax, the numbers in the output will be different,
+  # and it might say "excl. tax" instead of "inc. tax"; but none of that clutters the view. Moreover, any price
+  # typed into the form will of course be converted as appropriate for that user. This is important, for
+  # example, in an auction scenario, where you may have taxed and untaxed bidders bidding in the same
+  # auction; their input and output is personalised depending on their account information, but for
+  # purposes of determining the winning bidder, all bidders are automatically normalised to the untaxed
+  # value of their bids.
+  #
+  # == Tax logic objects
+  #
+  # A tax logic object is an instance of a class with the following structure:
+  #
+  #   class MyTaxLogic
+  #     def apply_tax(params)
+  #       # Called to convert a value without tax into a value with tax, as applicable. params is a hash:
+  #       #   :model_object => The model object whose attribute is being converted
+  #       #   :attribute    => The name of the attribute (without '_taxed' suffix) being converted
+  #       #   :value        => The untaxed value of the attribute as a BigDecimal
+  #       # Should return a number greater than or equal to the input value. Don't worry about rounding --
+  #       # CurrencyValue deals with that.
+  #     end
+  #    
+  #     def remove_tax(params)
+  #       # Does the reverse of apply_tax -- converts a value with tax into a value without tax. The params
+  #       # hash has the same format. First applying tax and then removing it again should always result in the
+  #       # starting value (for the the same object and the same environment -- it may depend on time,
+  #       # global variables, etc).
+  #     end
+  #    
+  #     def tax_info(params, *args)
+  #       # Should return a short string to explain to users which operation has been performed by apply_tax
+  #       # (e.g. if apply_tax has added VAT, the string could be "inc. VAT"). The params hash is the same as
+  #       # given to apply_tax. Additional parameters are optional; if any arguments are passed to a call to
+  #       # model_object.<attr>_tax_info then they are passed on here.
+  #     end
+  #    
+  #     def tax_details(params, *args)
+  #       # Like tax_info, but should return a longer string for use in user interface elements which are less
+  #       # limited in size.
+  #     end
+  #    
+  #     def mixin_methods
+  #       # Optionally you can define a method mixin_methods which returns a list of method names which should
+  #       # be included in classes which use this tax logic. Methods defined here become instance methods of
+  #       # model objects with acts_as_taxable attributes. For example:
+  #       [:some_other_method]
+  #     end
+  #    
+  #     def some_other_method(params, *args)
+  #       # some_other_method was named by mixin_methods to be included in model objects. For example, if the
+  #       # class MyProduct uses MyTaxLogic, then MyProduct.find(1).some_other_method(:foo, 'bar') will
+  #       # translate into MyTaxLogic#some_other_method({:model_object => MyProduct.find(1)}, :foo, 'bar').
+  #       # The model object on which the method is called is passed under the key :model_object in the
+  #       # params hash, and all other arguments to the method are simply passed on.
+  #     end
+  #   end
+  #
+  #
+  # == Currency rounding errors
+  # 
+  # Both the taxed and the untaxed value of an attribute are currency values, and so they must both be rounded
+  # to the accuracy which is conventional for the currency in use (see the discussion of precision and rounding
+  # in the +CurrencyValue+ module). If we are always storing untaxed values and outputting taxed values to the
+  # user, this is not a problem. However, if we allow users to input taxed values (like in the form example
+  # above), something curious may happen: The input value has its tax removed, is rounded to the currency's
+  # conventional precision and stored in the database in untaxed form; then later it is loaded, tax is added
+  # again, it is again rounded to the currency's conventional precision, and displayed to the user. If the
+  # rounding steps have rounded the number upwards twice, or downwards twice, it may happen that the value
+  # displayed to the user differs slightly from the one they originally entered.
+  # 
+  # We believe that storing untaxed values and performing currency rounding are the right things to do, and this
+  # apparent rounding error is a natural consequence. This module therefore tries to deal with the error
+  # elegantly: If you assign a value to a taxed attribute and immediately read it again, it will return the
+  # same value as if it had been stored and loaded again (i.e. the number you read has been rounded twice --
+  # make sure the currency code has been assigned to the object beforehand, so that the +CurrencyValue+ module
+  # knows which precision to apply).
+  # 
+  # Moreover, after assigning a value to a <tt><attr>_taxed=</tt> attribute, the <tt><attr>_tax_rounding_error</tt>
+  # method can tell you whether and by how much the value has changed as a result of removing and re-applying
+  # tax. A negative number indicates that the converted amount is less than the input; a positive number indicates
+  # that it is more than entered by the user; and zero means that there was no difference.
+  # 
+  module Taxable
+    module ActMethods
+      # Declares that one or more attributes on this model object store monetary values to which tax may be
+      # applied. Takes one or more attribute names, followed by an options hash:
+      # <tt>:tax_logic</tt>:: Object with instance methods apply_tax, remove_tax, tax_info and tax_details
+      #                       as documented in the +Taxable+ module. Required.
+      # <tt>:currency</tt>::  The name of the attribute/database column which stores the ISO 4217 currency
+      #                       code for the monetary amounts in this model object. Required if the column
+      #                       is not called +currency+.
+      # +acts_as_taxable+ implies +acts_as_currency_value+ with the same options. See the +Taxable+ for details.
+      def acts_as_taxable(*args)
+        Invoicing::ClassInfo.acts_as(Invoicing::Taxable, self, args)
+        
+        attrs = taxable_class_info.new_args.map{|a| a.to_s }
+        currency_attrs = attrs + attrs.map{|attr| "#{attr}_taxed"}
+        currency_opts = taxable_class_info.all_options.update({:conversion_input => :convert_taxable_value})
+        acts_as_currency_value(currency_attrs, currency_opts)
+        
+        attrs.each {|attr| generate_attr_taxable_methods(attr) }
+        
+        if tax_logic = taxable_class_info.all_options[:tax_logic]
+          other_methods = (tax_logic.respond_to?(:mixin_methods) ? tax_logic.mixin_methods : []) || []
+          other_methods.each {|method_name| generate_attr_taxable_other_method(method_name.to_s) }
+        else
+          raise ArgumentError, 'You must specify a :tax_logic option for acts_as_taxable'
+        end
+      end
+    end
+    
+    # If +write_attribute+ is called on a taxable attribute, we note whether the taxed or the untaxed
+    # version contains the latest correct value. We don't do the conversion immediately in case the tax
+    # logic requires the value of another attribute (which may be assigned later) to do its calculation.
+    def write_attribute(attribute, value) #:nodoc:
+      attribute = attribute.to_s
+      attr_regex = taxable_class_info.all_args.map{|a| a.to_s }.join('|')
+      @taxed_or_untaxed ||= {}
+      @taxed_attributes ||= {}
+      
+      if attribute =~ /^(#{attr_regex})$/
+        @taxed_or_untaxed[attribute] = :untaxed
+        @taxed_attributes[attribute] = nil
+      elsif attribute =~ /^(#{attr_regex})_taxed$/
+        @taxed_or_untaxed[$1] = :taxed
+        @taxed_attributes[$1] = value
+      end
+      
+      super
+    end
+    
+    # Called internally to convert between taxed and untaxed values. You shouldn't usually need to
+    # call this method from elsewhere.
+    def convert_taxable_value(attr) #:nodoc:
+      attr = attr.to_s
+      attr_without_suffix = attr.sub(/(_taxed)$/, '')
+      to_status = ($1 == '_taxed') ? :taxed : :untaxed
+
+      @taxed_or_untaxed ||= {}
+      from_status = @taxed_or_untaxed[attr_without_suffix] || :untaxed # taxed or untaxed most recently assigned?
+      
+      attr_to_read = attr_without_suffix
+      attr_to_read += '_taxed' if from_status == :taxed
+      
+      if from_status == :taxed && to_status == :taxed
+        # Special case: remove tax, apply rounding errors, apply tax again, apply rounding errors again.
+        write_attribute(attr_without_suffix, send(attr_without_suffix))
+        send(attr)
+      else
+        taxable_class_info.convert(self, attr_without_suffix, read_attribute(attr_to_read), from_status, to_status)
+      end
+    end
+    
+    protected :write_attribute, :convert_taxable_value
+
+
+    module ClassMethods #:nodoc:
+      # Generate additional accessor method for attribute with getter +method_name+.
+      def generate_attr_taxable_methods(method_name) #:nodoc:
+        
+        define_method("#{method_name}_tax_rounding_error") do
+          original_value = read_attribute("#{method_name}_taxed")
+          return nil if original_value.nil? # Can only have a rounding error if the taxed attr was assigned
+          
+          original_value = BigDecimal.new(original_value.to_s)
+          converted_value = send("#{method_name}_taxed")
+          
+          return nil if converted_value.nil?
+          converted_value - original_value
+        end
+
+        define_method("#{method_name}_tax_info") do |*args|
+          tax_logic = taxable_class_info.all_options[:tax_logic]
+          tax_logic.tax_info({:model_object => self, :attribute => method_name, :value => send(method_name)}, *args)
+        end
+
+        define_method("#{method_name}_tax_details") do |*args|
+          tax_logic = taxable_class_info.all_options[:tax_logic]
+          tax_logic.tax_details({:model_object => self, :attribute => method_name, :value => send(method_name)}, *args)
+        end
+        
+        define_method("#{method_name}_with_tax_info") do |*args|
+          amount = send("#{method_name}_taxed_formatted")
+          tax_info = send("#{method_name}_tax_info").to_s
+          tax_info.blank? ? amount : "#{amount} #{tax_info}"
+        end
+        
+        define_method("#{method_name}_with_tax_details") do |*args|
+          amount = send("#{method_name}_taxed_formatted")
+          tax_details = send("#{method_name}_tax_details").to_s
+          tax_details.blank? ? amount : "#{amount} #{tax_details}"
+        end
+        
+        define_method("#{method_name}_taxed_before_type_cast") do
+          @taxed_attributes ||= {}
+          @taxed_attributes[method_name] ||
+            read_attribute_before_type_cast("#{method_name}_taxed") ||
+            send("#{method_name}_taxed")
+        end
+      end
+      
+      # Generate a proxy method called +method_name+ which is forwarded to the +tax_logic+ object.
+      def generate_attr_taxable_other_method(method_name) #:nodoc:
+        define_method(method_name) do |*args|
+          tax_logic = taxable_class_info.all_options[:tax_logic]
+          tax_logic.send(method_name, {:model_object => self}, *args)
+        end
+      end
+
+      private :generate_attr_taxable_methods, :generate_attr_taxable_other_method
+    end # module ClassMethods
+    
+    
+    class ClassInfo < Invoicing::ClassInfo::Base #:nodoc:
+      # Performs the conversion between taxed and untaxed values. Arguments +from_status+ and
+      # +to_status+ must each be either <tt>:taxed</tt> or <tt>:untaxed</tt>.
+      def convert(object, attr_without_suffix, value, from_status, to_status)
+        return nil if value.nil?
+        value = BigDecimal.new(value.to_s)
+        return value if from_status == to_status
+        
+        if to_status == :taxed
+          all_options[:tax_logic].apply_tax({:model_object => object, :attribute => attr_without_suffix, :value => value})
+        else
+          all_options[:tax_logic].remove_tax({:model_object => object, :attribute => attr_without_suffix, :value => value})
+        end
+      end
+    end
+    
+  end
+end

data/lib/invoicing/time_dependent.rb

@@ -0,0 +1,388 @@
+module Invoicing
+  # == Time-dependent value objects
+  #
+  # This module implements the notion of a value (or a set of values) which may change at
+  # certain points in time, and for which it is important to have a full history of values
+  # for every point in time. It is used in the invoicing framework as basis for tax rates,
+  # prices, commissions etc.
+  #
+  # === Background
+  #
+  # To illustrate the need for this tool, consider for example the case of a tax rate. Say
+  # the rate is currently 10%, and in a naive implementation you simply store the value
+  # <tt>0.1</tt> in a constant. Whenever you need to calculate tax on a price, you multiply
+  # the price with the constant, and store the result together with the price in the database.
+  # Then, one day the government decides to increase the tax rate to 12%. On the day the
+  # change takes effect, you change the value of the constant to <tt>0.12</tt>.
+  #
+  # This naive implementation has a number of problems, which are addressed by this module:
+  # * With a constant, you have no way of informing users what a price will be after an
+  #   upcoming tax change. Using +TimeDependent+ allows you to query the value on any date
+  #   in the past or future, and show it to users as appropriate. You also gain the ability
+  #   to process back-dated or future-dated transactions if this should be necessary.
+  # * With a constant, you have no explicit information in your database informing you which
+  #   rate was applied for a particular tax calculation. You may be able to infer the rate
+  #   from the prices you store, but this may not be enough in cases where there is additional
+  #   metadata attached to tax rates (e.g. if there are different tax rates for different
+  #   types of product). With +TimeDependent+ you can have an explicit reference to the tax
+  #   object which formed the basis of a calculation, giving you a much better audit trail.
+  # * If there are different tax categories (e.g. a reduced rate for products of type A, and
+  #   a higher rate for type B), the government may not only change the rates themselves, but
+  #   also decide to reclassify product X as type B rather than type A. In any case you will
+  #   need to store the type of each of your products; however, +TimeDependent+ tries to
+  #   minimize the amount of reclassifying you need to do, should it become necessary.
+  #
+  # == Data Structure
+  #
+  # +TimeDependent+ objects are special ActiveRecord::Base objects. One database table is used,
+  # and each row in that table represents the value (e.g. the tax rate or the price) during
+  # a particular period of time. If there are multiple different values at the same time (e.g.
+  # a reduced tax rate and a higher rate), each of these is also represented as a separate
+  # row. That way you can refer to a +TimeDependent+ object from another model object (such as
+  # storing the tax category for a product), and refer simultaneously to the type of tax
+  # applicable for this product and the period for which this classification is valid.
+  #
+  # If a rate change is announced, it <b>important that the actual values in the table
+  # are not changed</b> in order to preserve historical information. Instead, add another
+  # row (or several rows), taking effect on the appropriate date. However, it is usually
+  # not necessary to update your other model objects to refer to these new rows; instead,
+  # each +TimeDependent+ object which expires has a reference to the new +TimeDependent+
+  # objects which replaces it. +TimeDependent+ provides methods for finding the current (or
+  # future) rate by following this chain of replacements.
+  #
+  # === Example
+  #
+  # To illustrate, take as example the rate of VAT (Value Added Tax) in the United Kingdom.
+  # The main tax rate was at 17.5% until 1 December 2008, when it was changed to 15%.
+  # On 1 January 2010 it is due to be changed back to 17.5%. At the same time, there are a
+  # reduced rates of 5% and 0% on certain goods; while the main rate was changed, the
+  # reduced rates stayed unchanged.
+  #
+  # The table of +TimeDependent+ records will look something like this:
+  #
+  #   +----+-------+---------------+------------+---------------------+---------------------+----------------+
+  #   | id | value | description   | is_default | valid_from          | valid_until         | replaced_by_id |
+  #   +----+-------+---------------+------------+---------------------+---------------------+----------------+
+  #   |  1 | 0.175 | Standard rate |          1 | 1991-04-01 00:00:00 | 2008-12-01 00:00:00 |              4 | 
+  #   |  2 |  0.05 | Reduced rate  |          0 | 1991-04-01 00:00:00 | NULL                |           NULL |
+  #   |  3 |   0.0 | Zero rate     |          0 | 1991-04-01 00:00:00 | NULL                |           NULL |
+  #   |  4 |  0.15 | Standard rate |          1 | 2008-12-01 00:00:00 | 2010-01-01 00:00:00 |              5 | 
+  #   |  5 | 0.175 | Standard rate |          1 | 2010-01-01 00:00:00 | NULL                |           NULL | 
+  #   +----+-------+---------------+------------+---------------------+---------------------+----------------+
+  #
+  # Graphically, this may be illustrated as:
+  #
+  #             1991-04-01             2008-12-01             2010-01-01
+  #                      :                      :                      :
+  #   Standard rate: 17.5% -----------------> 15% ---------------> 17.5% ----------------->
+  #                      :                      :                      :
+  #   Zero rate:        0% --------------------------------------------------------------->
+  #                      :                      :                      :
+  #   Reduced rate:     5% --------------------------------------------------------------->
+  #
+  # It is a deliberate choice that a +TimeDependent+ object references its successor, and not
+  # its predecessor. This is so that you can classify your items based on the current
+  # classification, and be sure that if the current rate expires there is an unambiguous
+  # replacement for it. On the other hand, it is usually not important to know what the rate
+  # for a particular item would have been at some point in the past.
+  #
+  # Now consider a slightly more complicated (fictional) example, in which a UK court rules
+  # that teacakes have been incorrectly classified for VAT purposes, namely that they should
+  # have been zero-rated while actually they had been standard-rated. The court also decides
+  # that all sales of teacakes before 1 Dec 2008 should maintain their old standard-rated status,
+  # while sales from 1 Dec 2008 onwards should be zero-rated.
+  #
+  # Assume you have an online shop in which you sell teacakes and other goods (both standard-rated
+  # and zero-rated). You can handle this reclassification (in addition to the standard VAT rate
+  # change above) as follows:
+  #
+  #             1991-04-01             2008-12-01             2010-01-01
+  #                      :                      :                      :
+  #   Standard rate: 17.5% -----------------> 15% ---------------> 17.5% ----------------->
+  #                      :                      :                      :
+  #   Teacakes:      17.5% ------------.        :                      :
+  #                      :              \_      :                      :
+  #   Zero rate:        0% ---------------+->  0% ---------------------------------------->
+  #                      :                      :                      :
+  #   Reduced rate:     5% --------------------------------------------------------------->
+  #
+  # Then you just need to update the teacake products in your database, which previously referred
+  # to the 17.5% object valid from 1991-04-01, to refer to the special teacake rate. None of the
+  # other products need to be modified. This way, the teacakes will automatically switch to the 0%
+  # rate on 2008-12-01. If you add any new teacake products to the database after December 2008, you
+  # can refer either to the teacake rate or to the new 0% rate which takes effect on 2008-12-01;
+  # it won't make any difference.
+  #
+  # == Usage notes
+  #
+  # This implementation is designed for tables with a small number of rows (no more than a few
+  # dozen) and very infrequent changes. To reduce database load, it caches model objects very
+  # aggressively; <b>you will need to restart your Ruby interpreter after making a change to
+  # the data</b> as the cache is not cleared between requests. This is ok because you shouldn't
+  # be lightheartedly modifying +TimeDependent+ data anyway; a database migration as part of an
+  # explicitly deployed release is probably the best way of introducing a rate change
+  # (that way you can also check it all looks correct on your staging server before making the
+  # rate change public).
+  #
+  # A model object using +TimeDependent+ must inherit from ActiveRecord::Base and must have
+  # at least the following columns (although columns may have different names, if declared to
+  # +acts_as_time_dependent+):
+  # * <tt>id</tt> -- An integer primary key
+  # * <tt>valid_from</tt> -- A column of type <tt>datetime</tt>, which must not be <tt>NULL</tt>.
+  #   It contains the moment at which the rate takes effect. The oldest <tt>valid_from</tt> dates
+  #   in the table should be in the past by a safe margin.
+  # * <tt>valid_until</tt> -- A column of type <tt>datetime</tt>, which contains the moment from
+  #   which the rate is no longer valid. It may be <tt>NULL</tt>, in which case the the rate is
+  #   taken to be "valid until further notice". If it is not <tt>NULL</tt>, it must contain a
+  #   date strictly later than <tt>valid_from</tt>.
+  # * <tt>replaced_by_id</tt> -- An integer, foreign key reference to the <tt>id</tt> column in
+  #   this same table. If <tt>valid_until</tt> is <tt>NULL</tt>, <tt>replaced_by_id</tt> must also
+  #   be <tt>NULL</tt>. If <tt>valid_until</tt> is non-<tt>NULL</tt>, <tt>replaced_by_id</tt> may
+  #   or may not be <tt>NULL</tt>; if it refers to a replacement object, the <tt>valid_from</tt>
+  #   value of that replacement object must be equal to the <tt>valid_until</tt> value of this
+  #   object.
+  #
+  # Optionally, the table may have further columns:
+  # * <tt>value</tt> -- The actual (usually numeric) value for which we're going to all this
+  #   effort, e.g. a tax rate percentage or a price in some currency unit.
+  # * <tt>is_default</tt> -- A boolean column indicating whether or not this object should be
+  #   considered a default during its period of validity. This may be useful if there are several
+  #   different rates in effect at the same time (such as standard, reduced and zero rate in the
+  #   example above). If this column is used, there should be exactly one default rate at any
+  #   given point in time, otherwise results are undefined.
+  #
+  # Apart from these requirements, a +TimeDependent+ object is a normal model object, and you may
+  # give it whatever extra metadata you want, and make references to it from any other model object.
+  module TimeDependent
+
+    module ActMethods
+      # Identifies the current model object as a +TimeDependent+ object, and creates all the
+      # necessary methods.
+      #
+      # Accepts options in a hash, all of which are optional:
+      # * <tt>id</tt> -- Alternative name for the <tt>id</tt> column
+      # * <tt>valid_from</tt> -- Alternative name for the <tt>valid_from</tt> column
+      # * <tt>valid_until</tt> -- Alternative name for the <tt>valid_until</tt> column
+      # * <tt>replaced_by_id</tt> -- Alternative name for the <tt>replaced_by_id</tt> column
+      # * <tt>value</tt> -- Alternative name for the <tt>value</tt> column
+      # * <tt>is_default</tt> -- Alternative name for the <tt>is_default</tt> column
+      #
+      # Example:
+      #
+      #   class CommissionRate < ActiveRecord::Base
+      #     acts_as_time_dependent :value => :rate
+      #     belongs_to :referral_program
+      #     named_scope :for_referral_program, lambda { |p| { :conditions => { :referral_program_id => p.id } } }
+      #   end
+      #   
+      #   reseller_program = ReferralProgram.find(1)
+      #   current_commission = CommissionRate.for_referral_program(reseller_program).default_record_now
+      #   puts "Earn #{current_commission.rate} per cent commission as a reseller..."
+      #   
+      #   changes = current_commission.changes_until(1.year.from_now)
+      #   for next_commission in changes
+      #     message = next_commission.nil? ? "Discontinued as of" : "Changing to #{next_commission.rate} per cent on"
+      #     puts "#{message} #{current_commission.valid_until.strftime('%d %b %Y')}!"
+      #     current_commission = next_commission
+      #   end
+      #
+      def acts_as_time_dependent(*args)
+        # Activate CachedRecord first, because ClassInfo#initialize expects the cache to be ready
+        acts_as_cached_record(*args)
+        
+        Invoicing::ClassInfo.acts_as(Invoicing::TimeDependent, self, args)
+                
+        # Create replaced_by association if it doesn't exist yet
+        replaced_by_id = time_dependent_class_info.method(:replaced_by_id)
+        unless respond_to? :replaced_by
+          belongs_to :replaced_by, :class_name => class_name, :foreign_key => replaced_by_id
+        end
+        
+        # Create value_at and value_now method aliases
+        value_method = time_dependent_class_info.method(:value).to_s
+        if value_method != 'value'
+          alias_method(value_method + '_at',  :value_at)
+          alias_method(value_method + '_now', :value_now)
+          class_eval <<-ALIAS
+            class << self
+              alias_method('default_#{value_method}_at',  :default_value_at)
+              alias_method('default_#{value_method}_now', :default_value_now)
+            end
+          ALIAS
+        end
+      end # acts_as_time_dependent
+    end # module ActMethods
+
+    
+    module ClassMethods
+      # Returns a list of records which are valid at some point during a particular date/time
+      # range. If there is a change of rate during this time interval, and one rate replaces
+      # another, then only the earliest element of each replacement chain is returned
+      # (because we can unambiguously convert from an earlier rate to a later one, but
+      # not necessarily in reverse).
+      #
+      # The date range must not be empty (i.e. +not_after+ must be later than +not_before+,
+      # not the same time or earlier). If you need the records which are valid at one
+      # particular point in time, use +valid_records_at+.
+      #
+      # A typical application for this method would be where you want to offer users the
+      # ability to choose from a selection of rates, including ones which are not yet
+      # valid but will become valid within the next month, for example.
+      def valid_records_during(not_before, not_after)
+        info = time_dependent_class_info
+        
+        # List of all records whose validity period intersects the selected period
+        valid_records = cached_record_list.select do |record|
+          valid_from  = info.get(record, :valid_from)
+          valid_until = info.get(record, :valid_until)
+          has_taken_effect = (valid_from < not_after) # N.B. less than
+          not_yet_expired  = (valid_until == nil) || (valid_until > not_before)
+          has_taken_effect && not_yet_expired
+        end
+        
+        # Select only those which do not have a predecessor which is also valid
+        valid_records.select do |record|
+          record.predecessors.empty? || (valid_records & record.predecessors).empty?
+        end
+      end
+      
+      # Returns the list of all records which are valid at one particular point in time.
+      # If you need to consider a period of time rather than a point in time, use
+      # +valid_records_during+.
+      def valid_records_at(point_in_time)
+        info = time_dependent_class_info
+        cached_record_list.select do |record|
+          valid_from  = info.get(record, :valid_from)
+          valid_until = info.get(record, :valid_until)
+          has_taken_effect = (valid_from <= point_in_time) # N.B. less than or equals
+          not_yet_expired  = (valid_until == nil) || (valid_until > point_in_time)
+          has_taken_effect && not_yet_expired
+        end
+      end
+      
+      # Returns the default record which is valid at a particular point in time.
+      # If there is no record marked as default, nil is returned; if there are
+      # multiple records marked as default, results are undefined.
+      # This method only works if the model objects have an +is_default+ column.
+      def default_record_at(point_in_time)
+        info = time_dependent_class_info
+        valid_records_at(point_in_time).select{|record| info.get(record, :is_default)}.first
+      end
+      
+      # Returns the default record which is valid at the current moment.
+      def default_record_now
+        default_record_at(Time.now)
+      end
+      
+      # Finds the default record for a particular +point_in_time+ (using +default_record_at+),
+      # then returns the value of that record's +value+ column. If +value+ was renamed to
+      # +another_method_name+ (option to +acts_as_time_dependent+), then
+      # +default_another_method_name_at+ is defined as an alias for +default_value_at+.
+      def default_value_at(point_in_time)
+        time_dependent_class_info.get(default_record_at(point_in_time), :value)
+      end
+    
+      # Finds the current default record (like +default_record_now+),
+      # then returns the value of that record's +value+ column. If +value+ was renamed to
+      # +another_method_name+ (option to +acts_as_time_dependent+), then
+      # +default_another_method_name_now+ is defined as an alias for +default_value_now+.
+      def default_value_now
+        default_value_at(Time.now)
+      end
+    
+    end # module ClassMethods
+
+    # Returns a list of objects of the same type as this object, which refer to this object
+    # through their +replaced_by_id+ values. In other words, this method returns all records
+    # which are direct predecessors of the current record in the replacement chain.
+    def predecessors
+      time_dependent_class_info.predecessors(self)
+    end
+    
+    # Translates this record into its replacement for a given point in time, if necessary/possible.
+    #
+    # * If this record is still valid at the given date/time, this method just returns self.
+    # * If this record is no longer valid at the given date/time, the record which has been
+    #   marked as this rate's replacement for the given point in time is returned.
+    # * If this record has expired and there is no valid replacement, nil is returned.
+    # * On the other hand, if the given date is at a time before this record becomes valid,
+    #   we try to follow the chain of +predecessors+ records. If there is an unambiguous predecessor
+    #   record which is valid at the given point in time, it is returned; otherwise nil is returned.
+    def record_at(point_in_time)
+      valid_from  = time_dependent_class_info.get(self, :valid_from)
+      valid_until = time_dependent_class_info.get(self, :valid_until)
+      
+      if valid_from > point_in_time
+        (predecessors.size == 1) ? predecessors[0].record_at(point_in_time) : nil
+      elsif valid_until.nil? || (valid_until > point_in_time)
+        self
+      elsif replaced_by.nil?
+        nil
+      else
+        replaced_by.record_at(point_in_time)
+      end
+    end
+  
+    # Returns self if this record is currently valid, otherwise its past or future replacement
+    # (see +record_at+). If there is no valid replacement, nil is returned.
+    def record_now
+      record_at Time.now
+    end
+    
+    # Finds this record's replacement for a given point in time (see +record_at+), then returns
+    # the value in its +value+ column. If +value+ was renamed to +another_method_name+ (option to
+    # +acts_as_time_dependent+), then +another_method_name_at+ is defined as an alias for +value_at+.
+    def value_at(point_in_time)
+      time_dependent_class_info.get(record_at(point_in_time), :value)
+    end
+
+    # Returns +value_at+ for the current date/time. If +value+ was renamed to +another_method_name+
+    # (option to +acts_as_time_dependent+), then +another_method_name_now+ is defined as an alias for
+    # +value_now+.
+    def value_now
+      value_at Time.now
+    end
+    
+    # Examines the replacement chain from this record into the future, during the period
+    # starting with this record's +valid_from+ and ending at +point_in_time+.
+    # If this record stays valid until after +point_in_time+, an empty list is returned.
+    # Otherwise the sequence of replacement records is returned in the list. If a record
+    # expires before +point_in_time+ and without replacement, a +nil+ element is inserted
+    # as the last element of the list.
+    def changes_until(point_in_time)
+      info = time_dependent_class_info
+      changes = []
+      record = self
+      while !record.nil?
+        valid_until = info.get(record, :valid_until)
+        break if valid_until.nil? || (valid_until > point_in_time)
+        record = record.replaced_by
+        changes << record
+      end
+      changes
+    end
+    
+    
+    # Stores state in the ActiveRecord class object
+    class ClassInfo < Invoicing::ClassInfo::Base #:nodoc:
+      
+      def initialize(model_class, previous_info, args)
+        super
+        # @predecessors is a hash of an ID pointing to the list of all objects which have that ID
+        # as replaced_by_id value
+        @predecessors = {}
+        for record in model_class.cached_record_list
+          id = get(record, :replaced_by_id)
+          unless id.nil?
+            @predecessors[id] ||= []
+            @predecessors[id] << record
+          end
+        end
+      end
+      
+      def predecessors(record)
+        @predecessors[get(record, :id)] || []
+      end
+    end # class ClassInfo
+  end # module TimeDependent
+end