invoicing 0.1.0 → 0.2.0

data/History.txt

@@ -0,0 +1,21 @@
+== 0.2.0 2009-04-20
+
+* 4 major enhancements:
+  * New associated gem invoicing_generator for generating an invoicing component in a Rails project
+    (script/generate invoicing_ledger)
+  * Generated controller and views for rendering statements and ledger
+  * Comes with a nice default stylesheet out of the box
+  * More flexible formatting of currency values
+* 1 bugfix:
+  * Accidental overwriting of total_amount value on payment LedgerItems without LineItems
+
+== 0.1.0 2009-02-10
+
+* 2 major enhancements:
+  * Core API is now usable
+  * RCov reports 100% test coverage
+
+== 0.0.1 2009-01-05
+
+* 1 major enhancement:
+  * Initial public release

data/{Manifest → Manifest.txt}

@@ -1,29 +1,35 @@
-CHANGELOG
+History.txt
+LICENSE
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+lib/invoicing.rb
 lib/invoicing/cached_record.rb
 lib/invoicing/class_info.rb
 lib/invoicing/connection_adapter_ext.rb
 lib/invoicing/countries/uk.rb
 lib/invoicing/currency_value.rb
 lib/invoicing/find_subclasses.rb
+lib/invoicing/ledger_item.rb
 lib/invoicing/ledger_item/render_html.rb
 lib/invoicing/ledger_item/render_ubl.rb
-lib/invoicing/ledger_item.rb
 lib/invoicing/line_item.rb
 lib/invoicing/price.rb
 lib/invoicing/tax_rate.rb
 lib/invoicing/taxable.rb
 lib/invoicing/time_dependent.rb
 lib/invoicing/version.rb
-lib/invoicing.rb
-LICENSE
-Manifest
-Rakefile
-README
+script/console
+script/destroy
+script/generate
+tasks/rcov.rake
 test/cached_record_test.rb
 test/class_info_test.rb
 test/connection_adapter_ext_test.rb
 test/currency_value_test.rb
 test/find_subclasses_test.rb
+test/fixtures/README
 test/fixtures/cached_record.sql
 test/fixtures/class_info.sql
 test/fixtures/currency_value.sql
@@ -31,7 +37,6 @@ test/fixtures/find_subclasses.sql
 test/fixtures/ledger_item.sql
 test/fixtures/line_item.sql
 test/fixtures/price.sql
-test/fixtures/README
 test/fixtures/tax_rate.sql
 test/fixtures/taxable.sql
 test/fixtures/time_dependent.sql
@@ -55,6 +60,3 @@ test/tax_rate_test.rb
 test/taxable_test.rb
 test/test_helper.rb
 test/time_dependent_test.rb
-website/curvycorners.js
-website/screen.css
-website/template.html.erb

data/PostInstall.txt

@@ -0,0 +1,10 @@
+
+Thanks for trying the Ruby Invoicing Gem. Hope you find it useful.
+Do please blog and tweet about it (tag your posts with #invgem).
+
+Now please go to the root of your Rails project and type:
+    script/generate invoicing_ledger billing --currency=GBP
+(replace GBP with your currency if you do not use Pounds Sterling).
+For more information please go to http://ept.github.com/invoicing/
+
+

data/README.rdoc

@@ -0,0 +1,55 @@
+= Ruby Invoicing Framework
+
+* {Ruby Invoicing Framework website}[http://ept.github.com/invoicing/]
+* {API Reference Docs}[http://invoicing.rubyforge.org/doc/]
+* {Browse the code on GitHub}[http://github.com/ept/invoicing/]
+* {RubyForge project}[http://rubyforge.org/projects/invoicing/]
+* Email: Martin Kleppmann <ept@rubyforge.org>
+
+== DESCRIPTION
+
+This is a framework for generating and displaying invoices (ideal for
+commercial Rails apps). It allows for flexible business logic; provides tools
+for tax handling, commission calculation etc. It aims to be both
+developer-friendly and accountant-friendly.
+
+The Ruby Invoicing Framework is based on
+{ActiveRecord}[http://api.rubyonrails.org/classes/ActiveRecord/Base.html].
+
+Please see {the website}[http://ept.github.com/invoicing/] for an introduction
+to using Invoicing, and check the
+{API reference}[http://invoicing.rubyforge.org/doc/] for in-depth details.
+
+== FEATURES
+
+* TODO
+
+== REQUIREMENTS
+
+* ActiveRecord >= 2.1
+* Only MySQL and PostgreSQL databases are currently supported
+
+== INSTALL
+
+sudo gem install invoicing
+
+== STATUS
+
+So far, the Ruby Invoicing Framework has been tested with ActiveRecord 2.2.2,
+MySQL 5.0.67 and PostgreSQL 8.3.5. We will be testing it across a wider
+variety of versions soon.
+
+== CREDITS
+
+The Ruby invoicing framework originated as part of the website
+{Bid for Wine}[http://www.bidforwine.co.uk], developed by Patrick Dietrich,
+Conrad Irwin, Michael Arnold and Martin Kleppmann for Ept Computing Ltd.
+It was extracted from the Bid for Wine codebase and substantially extended
+by Martin Kleppmann.
+
+== LICENSE
+
+Copyright (c) 2009 Martin Kleppmann, Ept Computing Limited.
+
+This gem is made publicly available under the terms of the MIT license.
+See LICENSE and/or COPYING for details.

data/Rakefile

@@ -1,75 +1,37 @@
-require 'rubygems'
-require 'echoe'
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/invoicing'
 
-# Add the project's top level directory and the lib directory to the Ruby search path
-$: << File.expand_path(File.join(File.dirname(__FILE__), "lib"))
-$: << File.expand_path(File.dirname(__FILE__))
-
-require 'invoicing'
-
-Echoe.new('invoicing', Invoicing::VERSION) do |p|
-  p.summary = 'Ruby invoicing framework'
-  p.description = 'Provides tools for applications which need to generate invoices for customers.'
-  p.url = 'http://invoicing.rubyforge.org/'
-  p.author = 'Martin Kleppmann'
-  p.email = 'rubyforge@eptcomputing.com'
-  p.dependencies = ['activerecord >=2.1.0', 'builder >= 2.0']
-  p.docs_host = 'ept@rubyforge.org:/var/www/gforge-projects/'
-  p.test_pattern = 'test/*_test.rb' # do not include test/models/*.rb
-  p.rcov_options = "-x '/Library/'"
+# Hoe calls Ruby with the "-w" set by default; unfortunately, ActiveRecord (at version 2.2.2
+# at least) causes a lot of warnings internally, by no fault of our own, which clutters
+# the output. Comment out the following four lines to see those warnings.
+class Hoe
+  RUBY_FLAGS = ENV['RUBY_FLAGS'] || "-I#{%w(lib test).join(File::PATH_SEPARATOR)}" +
+      (RUBY_DEBUG ? " #{RUBY_DEBUG}" : '')
 end
 
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('invoicing', Invoicing::VERSION) do |p|
+  p.developer('Martin Kleppmann', 'rubyforge@eptcomputing.com')
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.post_install_message = 'PostInstall.txt'
+  p.rubyforge_name = p.name
+  p.extra_deps = [
+    ['activerecord', '>= 2.1.0'],
+    ['builder', '>= 2.0']
+  ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+    #['invoicing_generator', "= #{Invoicing::VERSION}"] - causes a circular dependency in rubygems < 1.2
+  ]
 
-desc "Generate a new website from README file"
-task 'website' do
-  require 'rubygems'
-  require 'redcloth'
-  require 'syntax/convertors/html'
-  require 'erb'
-  
-  version  = Invoicing::VERSION
-  download = 'http://rubyforge.org/projects/invoicing'
-  
-  def convert_syntax(syntax, source)
-    return Syntax::Convertors::HTML.for_syntax(syntax).convert(source).gsub(%r!^<pre>|</pre>$!,'')
-  end
-  
-  template = ERB.new(File.open(File.join(File.dirname(__FILE__), '/website/template.html.erb')).read)
-  
-  title = nil
-  body = nil
-  File.open(File.join(File.dirname(__FILE__), '/README')) do |fsrc|
-    title = fsrc.readline.gsub(/^[^ ]* /, '')
-    body_text = fsrc.read
-    syntax_items = []
-    body_text.gsub!(%r!<(pre|code)[^>]*?syntax=['"]([^'"]+)[^>]*>(.*?)</\1>!m){
-      ident = syntax_items.length
-      element, syntax, source = $1, $2, $3
-      syntax_items << "<#{element} class='syntax'>#{convert_syntax(syntax, source)}</#{element}>"
-      "syntax-temp-#{ident}"
-    }
-    body = RedCloth.new(body_text).to_html
-    body.gsub!(%r!(?:<pre><code>)?syntax-temp-(\d+)(?:</code></pre>)?!){ syntax_items[$1.to_i] }
-  end
-  
-  File.open(File.join(File.dirname(__FILE__), '/website/index.html'), 'w') do |fout|
-    fout.write(template.result(binding))
-  end
+  p.test_globs = %w[test/*_test.rb] # do not include test/models/*.rb
+  p.clean_globs |= %w[**/.DS_Store tmp *.log coverage]
+  p.rsync_args = '-av --delete --ignore-errors'
 end
 
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
 
-desc "Generate and publish website"
-task :publish_website => :website do
-  require 'net/sftp'
-  upload_user = 'ept'
-  upload_host = 'rubyforge.org'
-  upload_dir = '/var/www/gforge-projects/invoicing'
-  local_dir = File.join(File.dirname(__FILE__), 'website')
-  Net::SFTP.start(upload_host, upload_user) do |sftp|
-    for f in Dir.entries(local_dir)
-      next if f =~ /^\./
-      puts "Uploading #{f} to #{upload_user}@#{upload_host}:#{upload_dir}/#{f}"
-      sftp.upload!(File.join(local_dir, f), "#{upload_dir}/#{f}")
-    end
-  end
-end
+# Tasks to run by default
+# task :default => [:spec, :features]

data/lib/invoicing/currency_value.rb

@@ -84,6 +84,31 @@ module Invoicing
       #     validates_inclusion_of :currency_code, %w( USD GBP EUR JPY )
       #     acts_as_currency_value :net_amount, :tax_amount, :currency => :currency_code
       #   end
+      #
+      # You may also specify the <tt>:value_for_formatting</tt> option, passing it the name of a method on
+      # your model object. That method will be called when a CurrencyValue method with +_formatted+ suffix
+      # is called, and allows you to modify the numerical value before it is formatted into a string. An
+      # options hash is also passed. This can be useful, for example, if a value is stored positive but you
+      # want to display it as negative in certain circumstances depending on the view:
+      #
+      #   class LedgerItem < ActiveRecord::Base
+      #     acts_as_ledger_item
+      #     acts_as_currency_value :total_amount, :tax_amount, :value_for_formatting => :value_for_formatting
+      #
+      #     def value_for_formatting(value, options={})
+      #       value *= -1 if options[:debit]  == :negative &&  debit?(options[:self_id])
+      #       value *= -1 if options[:credit] == :negative && !debit?(options[:self_id])
+      #       value
+      #     end
+      #   end
+      #
+      #   invoice = Invoice.find(1)
+      #   invoice.total_amount_formatted :debit => :negative, :self_id => invoice.sender_id
+      #     # => '$25.00'
+      #   invoice.total_amount_formatted :debit => :negative, :self_id => invoice.recipient_id
+      #     # => '-$25.00'
+      #
+      # (The example above is actually a real part of +LedgerItem+.)
       def acts_as_currency_value(*args)
         Invoicing::ClassInfo.acts_as(Invoicing::CurrencyValue, self, args)
 
@@ -94,8 +119,8 @@ module Invoicing
 
     # 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)
+    def format_currency_value(value, options={})
+      currency_value_class_info.format_value(self, value, options)
     end
     
     
@@ -109,6 +134,73 @@ module Invoicing
     protected :write_back_currency_values
 
 
+    # Encapsulates the methods for formatting currency values in a human-friendly way.
+    # These methods do not depend on ActiveRecord and can thus also be called externally.
+    module Formatter
+      class << self
+        
+        # Given the three-letter ISO 4217 code of a currency, returns a hash with useful bits of information:
+        # <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(code, options={})
+          code = code.to_s.upcase
+          valid_options = [:symbol, :round, :suffix, :space, :digits]
+          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
+          options.each_pair {|key, value| info[key] = value if valid_options.include? key }
+        
+          info[:suffix] ||= (info[:code] == info[:symbol]) && !info[:code].nil?
+          info[:space]  ||= info[:suffix]
+          info[:digits] = -Math.log10(info[:round]).floor if info[:digits].nil?
+          info[:digits] = 0 if info[:digits] < 0
+        
+          info
+        end
+      
+        # Given the three-letter ISO 4217 code of a currency and a BigDecimal value, returns the
+        # value formatted as an UTF-8 string, ready for human consumption.
+        #
+        # FIXME: This method currently does not take locale into account -- it always uses the dot
+        # as decimal separator and the comma as thousands separator.
+        def format_value(currency_code, value, options={})
+          info = currency_info(currency_code, options)
+          
+          negative = false
+          if value < 0
+            negative = true
+            value = -value
+          end
+        
+          value = "%.#{info[:digits]}f" % value
+          while value.sub!(/(\d+)(\d\d\d)/, '\1,\2'); end
+          value.sub!(/^\-/, '') # avoid displaying minus zero
+          
+          formatted = if ['', nil].include? info[:symbol]
+            value
+          elsif info[:space]
+            info[:suffix] ? "#{value} #{info[:symbol]}" : "#{info[:symbol]} #{value}"
+          else
+            info[:suffix] ? "#{value}#{info[:symbol]}" : "#{info[:symbol]}#{value}"
+          end
+          
+          if negative
+            # default is to use proper unicode minus sign
+            formatted = (options[:negative] == :brackets) ? "(#{formatted})" : (
+              (options[:negative] == :hyphen) ? "-#{formatted}" : "\xE2\x88\x92#{formatted}"
+            )
+          end
+          formatted
+        end
+      end
+    end
+
+
     class ClassInfo < Invoicing::ClassInfo::Base #:nodoc:
       
       def initialize(model_class, previous_info, args)
@@ -132,11 +224,18 @@ module Invoicing
             write_attribute(attr, new_value)
           end
           
-          define_method("#{attr}_formatted") do
-            begin
-              format_currency_value(Kernel.Float(send("#{attr}_before_type_cast")))
+          define_method("#{attr}_formatted") do |*args|
+            options = args.first || {}
+            value_as_float = begin
+              Kernel.Float(send("#{attr}_before_type_cast")) 
             rescue ArgumentError, TypeError
-              ''  # if <attr>_before_type_cast could not be converted to float
+              nil
+            end
+            
+            if value_as_float.nil?
+              ''
+            else
+              format_currency_value(value_as_float, options.merge({:method_name => attr}))
             end
           end
         end
@@ -153,43 +252,20 @@ module Invoicing
         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.
+      # Returns a hash of information about the currency used by model +object+.
       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
+        ::Invoicing::CurrencyValue::Formatter.currency_info(currency_of(object), all_options)
       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}"
+      def format_value(object, value, options={})
+        options = all_options.merge(options).symbolize_keys
+        intercept = options[:value_for_formatting]
+        if intercept && object.respond_to?(intercept)
+          value = object.send(intercept, value, options)
         end
+        ::Invoicing::CurrencyValue::Formatter.format_value(currency_of(object), value, options)
       end
       
       # If other modules have registered callbacks for the event of reading a rounded attribute,

data/lib/invoicing/ledger_item.rb

@@ -310,7 +310,7 @@ module Invoicing
         
         # Set the 'amount' columns to act as currency values
         acts_as_currency_value(info.method(:total_amount), info.method(:tax_amount),
-          :currency => info.method(:currency))
+          :currency => info.method(:currency), :value_for_formatting => :value_for_formatting)
         
         extend Invoicing::FindSubclasses
         include Invoicing::LedgerItem::RenderHTML
@@ -416,10 +416,13 @@ module Invoicing
     
     # Calculate sum of net_amount and tax_amount across all line items, and assign it to total_amount;
     # calculate sum of tax_amount across all line items, and assign it to tax_amount.
-    # Called automatically as a +before_validation+ callback.
+    # Called automatically as a +before_validation+ callback. If the LedgerItem subtype is +payment+
+    # and there are no line items then the total amount is not touched.
     def calculate_total_amount
-      net_total = tax_total = BigDecimal('0')
       line_items = ledger_item_class_info.get(self, :line_items)
+      return if self.class.is_payment && line_items.empty?
+
+      net_total = tax_total = BigDecimal('0')
       
       line_items.each do |line|
         info = line.send(:line_item_class_info)
@@ -544,6 +547,17 @@ module Invoicing
       raise ArgumentError, "self_id #{self_id.inspect} is both sender and recipient" if sender_is_self && recipient_is_self
       self.class.debit_when_sent_by_self ? sender_is_self : recipient_is_self
     end
+
+    # Invoked internally when +total_amount_formatted+ or +tax_amount_formatted+ is called. Allows
+    # you to specify options like <tt>:debit => :negative, :self_id => 42</tt> meaning that if this
+    # ledger item is a debit as regarded from the point of view of +self_id+ then it should be
+    # displayed as a negative number. Note this only affects the output formatting, not the actual
+    # stored values.
+    def value_for_formatting(value, options={})
+      value = -value if (options[:debit]  == :negative) &&  debit?(options[:self_id])
+      value = -value if (options[:credit] == :negative) && !debit?(options[:self_id])
+      value
+    end
     
     
     module ClassMethods
@@ -580,29 +594,52 @@ module Invoicing
       
       # Returns a summary of the customer or supplier account between two parties identified
       # by +self_id+ (the party from whose perspective the account is seen, 'you') and +other_id+
-      # ('them', your supplier/customer). The return value is a hash with the following structure:
+      # ('them', your supplier/customer). The return value is a hash with ISO 4217 currency codes
+      # as keys (as symbols), and summary objects as values. An account using only one currency
+      # will have only one entry in the hash, but more complex accounts may have several.
+      #
+      # The summary object has the following methods:
       #
-      #   { :GBP => {                                 # ISO 4217 currency code for the following figures
-      #       :sales             => BigDecimal(...),  # Sum of sales (invoices sent by self_id)
-      #       :purchases         => BigDecimal(...),  # Sum of purchases (invoices received by self_id)
-      #       :sale_receipts     => BigDecimal(...),  # Sum of payments received from customer
-      #       :purchase_payments => BigDecimal(...),  # Sum of payments made to supplier
-      #       :balance           => BigDecimal(...)   # sales - purchases - sale_receipts + purchase_payments
-      #     },
-      #     :USD => {                                 # Another block as above, if the account uses
-      #       ...                                     # multiple currencies
-      #   }}
+      #   currency          => symbol           # Same as the key of this hash entry
+      #   sales             => BigDecimal(...)  # Sum of sales (invoices sent by self_id)
+      #   purchases         => BigDecimal(...)  # Sum of purchases (invoices received by self_id)
+      #   sale_receipts     => BigDecimal(...)  # Sum of payments received from customer
+      #   purchase_payments => BigDecimal(...)  # Sum of payments made to supplier
+      #   balance           => BigDecimal(...)  # sales - purchases - sale_receipts + purchase_payments
       #
       # The <tt>:balance</tt> fields indicate any outstanding money owed on the account: the value is
       # positive if they owe you money, and negative if you owe them money.
-      def account_summary(self_id, other_id)
+      #
+      # In addition, +acts_as_currency_value+ is set on the numeric fields, so you can use its
+      # convenience methods such as +summary.sales_formatted+.
+      #
+      # If +other_id+ is +nil+, this method aggregates the accounts of +self_id+ with *all* other
+      # parties.
+      def account_summary(self_id, other_id=nil)
         info = ledger_item_class_info
-        conditions = {info.method(:sender_id)    => [self_id, other_id],
-                      info.method(:recipient_id) => [self_id, other_id]}
-
-        with_scope :find => {:conditions => conditions} do
-          summaries = account_summaries(self_id)
-          summaries[other_id] || {}
+        self_id = self_id.to_i
+        other_id = [nil, ''].include?(other_id) ? nil : other_id.to_i
+        
+        if other_id.nil?
+          result = {}
+          # Sum over all others, grouped by currency
+          account_summaries(self_id).each_pair do |other_id, hash|
+            hash.each_pair do |currency, summary|
+              if result[currency]
+                result[currency] += summary
+              else
+                result[currency] = summary
+              end
+            end
+          end
+          result
+          
+        else
+          conditions = {info.method(:sender_id)    => [self_id, other_id],
+                        info.method(:recipient_id) => [self_id, other_id]}
+          with_scope(:find => {:conditions => conditions}) do
+            account_summaries(self_id)[other_id] || {}
+          end
         end
       end
     
@@ -611,11 +648,11 @@ module Invoicing
       # which have +self_id+ as their +sender_id+ or +recipient_id+. Returns a hash whose keys are the
       # other party of each account (i.e. the value of +sender_id+ or +recipient_id+ which is not
       # +self_id+, as an integer), and whose values are again hashes, of the same form as returned by
-      # +account_summary+:
+      # +account_summary+ (+summary+ objects as documented on +account_summary+):
       #
       #   LedgerItem.account_summaries(1)
-      #     # => { 2 => { :USD => { :sales => ... }, :EUR => { :sales => ... } },
-      #     #      3 => { :EUR => { :sales => ... } } }
+      #     # => { 2 => { :USD => summary, :EUR => summary },
+      #     #      3 => { :EUR => summary } }
       #
       # If you want to further restrict the ledger items taken into account in this calculation (e.g.
       # include only data from a particular quarter) you can call this method within an ActiveRecord
@@ -646,8 +683,6 @@ module Invoicing
         other_id_column = ext.conditional_function(sender_is_self, cols[:recipient_id], cols[:sender_id])
         filter_conditions = "#{cols[:status]} IN ('closed','cleared') AND (#{sender_is_self} OR #{recipient_is_self})"
         
-        
-
         sql = "SELECT #{other_id_column} AS other_id, #{cols[:currency]} AS currency, " + 
           "SUM(#{ext.conditional_function(debit_when_sent,      cols[:total_amount], 0)}) AS sales, " +
           "SUM(#{ext.conditional_function(debit_when_received,  cols[:total_amount], 0)}) AS purchase_payments, " +
@@ -672,7 +707,7 @@ module Invoicing
           row.symbolize_keys!
           other_id = row[:other_id].to_i
           currency = row[:currency].to_sym
-          summary = {:balance => BigDecimal('0')}
+          summary = {:balance => BigDecimal('0'), :currency => currency}
           
           {:sales => 1, :purchases => -1, :sale_receipts => -1, :purchase_payments => 1}.each_pair do |field, factor|
             summary[field] = BigDecimal(row[field])
@@ -680,11 +715,95 @@ module Invoicing
           end
           
           results[other_id] ||= {}
-          results[other_id][currency] = summary
+          results[other_id][currency] = AccountSummary.new summary
         end
         
         results
       end
+
+      # Takes an array of IDs like those used in +sender_id+ and +recipient_id+, and returns a hash
+      # which maps each of these IDs (typecast to integer) to the <tt>:name</tt> field of the
+      # hash returned by +sender_details+ or +recipient_details+ for that ID. This is useful as it
+      # allows +LedgerItem+ to use human-readable names for people or organisations in its output,
+      # without depending on a particular implementation of the model objects used to store those
+      # entities.
+      #
+      #   LedgerItem.sender_recipient_name_map [2, 4]
+      #   => {2 => "Fast Flowers Ltd.", 4 => "Speedy Motors"}
+      def sender_recipient_name_map(*sender_recipient_ids)
+        sender_recipient_ids = sender_recipient_ids.flatten.map &:to_i
+        sender_recipient_to_ledger_item_ids = {}
+        result_map = {}
+        info = ledger_item_class_info
+        
+        # Find the most recent occurrence of each ID, first in the sender_id column, then in recipient_id
+        [:sender_id, :recipient_id].each do |column|
+          column = info.method(column)
+          quoted_column = connection.quote_column_name(column)
+          sql = "SELECT MAX(#{primary_key}) AS id, #{quoted_column} AS ref FROM #{quoted_table_name} WHERE "
+          sql << merge_conditions({column => sender_recipient_ids})
+          sql << " GROUP BY #{quoted_column}"
+          
+          ActiveRecord::Base.connection.select_all(sql).each do |row|
+            sender_recipient_to_ledger_item_ids[row['ref'].to_i] = row['id'].to_i
+          end
+          
+          sender_recipient_ids -= sender_recipient_to_ledger_item_ids.keys
+        end
+        
+        # Load all the ledger items needed to get one representative of each name
+        find(sender_recipient_to_ledger_item_ids.values.uniq).each do |ledger_item|
+          sender_id = info.get(ledger_item, :sender_id)
+          recipient_id = info.get(ledger_item, :recipient_id)
+          
+          if sender_recipient_to_ledger_item_ids.include? sender_id
+            details = info.get(ledger_item, :sender_details)
+            result_map[sender_id] = details[:name]
+          end
+          if sender_recipient_to_ledger_item_ids.include? recipient_id
+            details = info.get(ledger_item, :recipient_details)
+            result_map[recipient_id] = details[:name]
+          end
+        end
+        
+        result_map
+      end
+      
+    end # module ClassMethods
+    
+    
+    # Very simple class for representing the sum of all sales, purchases and payments on
+    # an account.
+    class AccountSummary #:nodoc:
+      NUM_FIELDS = [:sales, :purchases, :sale_receipts, :purchase_payments, :balance]
+      attr_reader *([:currency] + NUM_FIELDS)
+            
+      def initialize(hash)
+        @currency = hash[:currency]; @sales = hash[:sales]; @purchases = hash[:purchases]
+        @sale_receipts = hash[:sale_receipts]; @purchase_payments = hash[:purchase_payments]
+        @balance = hash[:balance]
+      end
+      
+      def method_missing(name, *args)
+        if name.to_s =~ /(.*)_formatted$/
+          ::Invoicing::CurrencyValue::Formatter.format_value(currency, send($1))
+        else
+          super
+        end
+      end
+      
+      def +(other)
+        hash = {:currency => currency}
+        NUM_FIELDS.each {|field| hash[field] = send(field) + other.send(field) }
+        AccountSummary.new hash
+      end
+      
+      def to_s
+        NUM_FIELDS.map do |field|
+          val = send("#{field}_formatted")
+          "#{field} = #{val}"
+        end.join('; ')
+      end
     end