double_entry 0.3.1 → 0.4.0

data/README.md

@@ -31,16 +31,27 @@ Rails Versions: Rails 3.2.x, 4.0.x, 4.1.x
 
 In your application's `Gemfile`, add:
 
-    gem 'double_entry'
+```ruby
+gem 'double_entry'
+```
 
-Then run:
+Download and install the gem with Bundler:
 
-    bundle
-    rails generate double_entry:install
+```sh
+bundle
+```
 
-Run migration files:
+Generate Rails schema migrations for the required tables:
 
-    rake db:migrate
+```sh
+rails generate double_entry:install
+```
+
+Update the local database:
+
+```sh
+rake db:migrate
+```
 
 
 ## Interface
@@ -91,7 +102,12 @@ will return the current balance for an account as a Money object.
 To transfer money between accounts:
 
 ```ruby
-DoubleEntry.transfer(20.dollars, :from => account_a, :to => account_b, :code => :purchase)
+DoubleEntry.transfer(
+  20.dollars,
+  :from => one_account,
+  :to   => another_account,
+  :code => :a_business_code_for_this_type_of_transfer,
+)
 ```
 
 The possible transfers, and their codes, should be defined in the configuration.
@@ -107,8 +123,9 @@ manually lock the accounts you're using:
 
 ```ruby
 DoubleEntry.lock_accounts(account_a, account_b) do
-  # Do some other stuff in here...
+  # Perhaps transfer some money
   DoubleEntry.transfer(20.dollars, :from => account_a, :to => account_b, :code => :purchase)
+  # Perform other tasks that should be commited atomically with the transfer of funds...
 end
 ```
 
@@ -214,33 +231,45 @@ correct balances from the lines table.
 
 ## Future Direction
 
-No immediate to-do's.
+See the Github project [issues](https://github.com/envato/double_entry/issues).
 
 ## Development Environment Setup
 
 1. Clone this repo.
 
-        git clone git@github.com:envato/double_entry.git && cd double_entry
+    ```sh
+    git clone git@github.com:envato/double_entry.git && cd double_entry
+    ```
 
 2. Run the included setup script to install the gem dependencies.
 
-        ./script/setup.sh
+    ```sh
+    ./script/setup.sh
+    ```
 
-3. Install MySQL and PostgreSQL. The tests run using both databases.
+3. Install MySQL and PostgreSQL. We run tests against both databases.
 4. Create a database in MySQL.
 
-        mysql -u root -e 'create database double_entry_test;'
+    ```sh
+    mysql -u root -e 'create database double_entry_test;'
+    ```
 
 5. Create a database in PostgreSQL.
 
-        psql -c 'create database double_entry_test;' -U postgres
+    ```sh
+    psql -c 'create database double_entry_test;' -U postgres
+    ```
 
 6. Specify how the tests should connect to the database
 
-        cp spec/support/database.example.yml spec/support/database.yml
-        vim spec/support/database.yml
+    ```sh
+    cp spec/support/{database.example.yml,database.yml}
+    vim spec/support/database.yml
+    ```
 
 7. Run the tests
 
-        bundle exec rake
+    ```sh
+    bundle exec rake
+    ```
 

data/lib/double_entry.rb

@@ -31,7 +31,7 @@ module DoubleEntry
     #
     # @example Obtain the 'cash' account for a user
     #   DoubleEntry.account(:cash, scope: user)
-    # @param identifier [Symbol] The symbol identifying the desired account. As
+    # @param [Symbol] identifier The symbol identifying the desired account. As
     #   specified in the account configuration.
     # @option options :scope Limit the account to the given scope. As specified
     #   in the account configuration.
@@ -56,12 +56,12 @@ module DoubleEntry
     #   checking_account = DoubleEntry.account(:checking, scope: user)
     #   savings_account  = DoubleEntry.account(:savings,  scope: user)
     #   DoubleEntry.transfer(
-    #     Money.new(20_00),
-    #     from: checking_account,
-    #     to:   savings_account,
-    #     code: :save,
+    #     20.dollars,
+    #     :from => checking_account,
+    #     :to   => savings_account,
+    #     :code => :save,
     #   )
-    # @param amount [Money] The quantity of money to transfer from one account
+    # @param [Money] amount The quantity of money to transfer from one account
     #   to the other.
     # @option options :from [DoubleEntry::Account::Instance] Transfer money out
     #   of this account.
@@ -69,7 +69,6 @@ module DoubleEntry
     #   this account.
     # @option options :code [Symbol] The application specific code for this
     #   type of transfer. As specified in the transfer configuration.
-    # @option options :meta [String] Metadata to associate with this transfer.
     # @option options :detail [ActiveRecord::Base] ActiveRecord model
     #   associated (via a polymorphic association) with the transfer.
     # @raise [DoubleEntry::TransferIsNegative] The amount is less than zero.
@@ -82,14 +81,50 @@ module DoubleEntry
 
     # Get the current or historic balance of an account.
     #
-    # @param account [DoubleEntry::Account:Instance, Symbol]
-    # @option options :scope [Object, String]
-    # @option options :from [Time]
-    # @option options :to [Time]
-    # @option options :at [Time]
-    # @option options :code [Symbol]
-    # @option options :codes [Array<Symbol>]
-    # @return [Money]
+    # @example Obtain the current balance of my checking account
+    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   DoubleEntry.balance(checking_account)
+    # @example Obtain the current balance of my checking account (without account or user model)
+    #   DoubleEntry.balance(:checking, :scope => user_id)
+    # @example Obtain a historic balance of my checking account
+    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   DoubleEntry.balance(checking_account, :at => Time.new(2012, 1, 1))
+    # @example Obtain the net balance of my checking account during may
+    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   DoubleEntry.balance(
+    #     checking_account,
+    #     :from => Time.new(2012, 5,  1,  0,  0,  0),
+    #     :to   => Time.new(2012, 5, 31, 23, 59, 59),
+    #   )
+    # @example Obtain the balance of salary deposits made to my checking account during may
+    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   DoubleEntry.balance(
+    #     checking_account,
+    #     :code => :salary,
+    #     :from => Time.new(2012, 5,  1,  0,  0,  0),
+    #     :to   => Time.new(2012, 5, 31, 23, 59, 59),
+    #   )
+    # @example Obtain the balance of salary & lottery deposits made to my checking account during may
+    #   checking_account = DoubleEntry.account(:checking, :scope => user)
+    #   DoubleEntry.balance(
+    #     checking_account,
+    #     :codes => [ :salary, :lottery ],
+    #     :from  => Time.new(2012, 5,  1,  0,  0,  0),
+    #     :to    => Time.new(2012, 5, 31, 23, 59, 59),
+    #   )
+    # @param [DoubleEntry::Account:Instance, Symbol] account Find the balance
+    #   for this account
+    # @option options :scope [Object] The scope identifier of the account (only
+    #   needed if the provided account is a symbol).
+    # @option options :from [Time] used with :to, consider only the time
+    #   between these dates
+    # @option options :to [Time] used with :from, consider only the time
+    #   between these dates
+    # @option options :at [Time] obtain the account balance at this time
+    # @option options :code [Symbol] consider only the transfers with this code
+    # @option options :codes [Array<Symbol>] consider only the transfers with
+    #   these codes
+    # @return [Money] The balance
     def balance(account, options = {})
       BalanceCalculator.calculate(account, options)
     end

data/lib/double_entry/line.rb

@@ -72,16 +72,6 @@ module DoubleEntry
       self[:code].try(:to_sym)
     end
 
-    def meta=(meta)
-      self[:meta] = Marshal.dump(meta)
-      meta
-    end
-
-    def meta
-      meta = self[:meta]
-      meta ? Marshal.load(meta) : {}
-    end
-
     def account=(account)
       self[:account] = account.identifier.to_s
       self.scope = account.scope_identity
@@ -107,18 +97,18 @@ module DoubleEntry
     end
 
     def pair
-      if credit?
+      if decrease?
         [self, partner]
       else
         [partner, self]
       end
     end
 
-    def credit?
+    def decrease?
       amount < Money.empty
     end
 
-    def debit?
+    def increase?
       amount > Money.empty
     end
 

data/lib/double_entry/reporting.rb

@@ -34,28 +34,36 @@ module DoubleEntry
     # and provided custom filters.
     #
     # @example Find the sum for all $10 :save transfers in all :checking accounts in the current month (assume the date is January 30, 2014).
-    #   time_range = DoubleEntry::TimeRange.make(2014, 1)
-    #   class ::DoubleEntry::Line
+    #   time_range = DoubleEntry::Reporting::TimeRange.make(2014, 1)
+    #
+    #   DoubleEntry::Line.class_eval do
     #     scope :ten_dollar_transfers, -> { where(:amount => 10_00) }
     #   end
-    #   DoubleEntry.aggregate(:sum, :checking, :save, range: time_range, filter: [:ten_dollar_transfers])
-    # @param function [Symbol] The function to perform on the set of transfers.
+    #
+    #   DoubleEntry::Reporting.aggregate(
+    #     :sum,
+    #     :checking,
+    #     :save,
+    #     :range  => time_range,
+    #     :filter => [ :ten_dollar_transfers ],
+    #   )
+    # @param [Symbol] function The function to perform on the set of transfers.
     #   Valid functions are :sum, :count, and :average
-    # @param account [Symbol] The symbol identifying the account to perform
+    # @param [Symbol] account The symbol identifying the account to perform
     #   the aggregate calculation on. As specified in the account configuration.
-    # @param code [Symbol] The application specific code for the type of
+    # @param [Symbol] code The application specific code for the type of
     #   transfer to perform an aggregate calculation on. As specified in the
     #   transfer configuration.
-    # @option options :range [DoubleEntry::TimeRange] Only include transfers
-    #   in the given time range in the calculation.
-    # @option options :filter [Array[Symbol], or Array[Hash<Symbol,Parameter>]]
+    # @option options :range [DoubleEntry::Reporting::TimeRange] Only include
+    #   transfers in the given time range in the calculation.
+    # @option options :filter [Array<Symbol>, Array<Hash<Symbol, Object>>]
     #   A custom filter to apply before performing the aggregate calculation.
-    #   Currently, filters must be monkey patched as scopes into the DoubleEntry::Line
-    #   class in order to be used as filters, as the example shows.
-    #   If the filter requires a parameter, it must be given in a Hash, otherwise
-    #   pass an array with the symbol names for the defined scopes.
-    # @return Returns a Money object for :sum and :average calculations, or a
-    #   Fixnum for :count calculations.
+    #   Currently, filters must be monkey patched as scopes into the
+    #   DoubleEntry::Line class in order to be used as filters, as the example
+    #   shows. If the filter requires a parameter, it must be given in a Hash,
+    #   otherwise pass an array with the symbol names for the defined scopes.
+    # @return [Money, Fixnum] Returns a Money object for :sum and :average
+    #   calculations, or a Fixnum for :count calculations.
     # @raise [Reporting::AggregateFunctionNotSupported] The provided function
     #   is not supported.
     #
@@ -70,20 +78,27 @@ module DoubleEntry
     # and provided custom filters.
     #
     # @example Find the number of all $10 :save transfers in all :checking accounts per month for the entire year (Assume the year is 2014).
-    #   DoubleEntry.aggregate_array(:sum, :checking, :save, range_type: 'month', start: '2014-01-01', finish: '2014-12-31')
-    # @param function [Symbol] The function to perform on the set of transfers.
+    #   DoubleEntry::Reporting.aggregate_array(
+    #     :sum,
+    #     :checking,
+    #     :save,
+    #     :range_type => 'month',
+    #     :start      => '2014-01-01',
+    #     :finish     => '2014-12-31',
+    #   )
+    # @param [Symbol] function The function to perform on the set of transfers.
     #   Valid functions are :sum, :count, and :average
-    # @param account [Symbol] The symbol identifying the account to perform
+    # @param [Symbol] account The symbol identifying the account to perform
     #   the aggregate calculation on. As specified in the account configuration.
-    # @param code [Symbol] The application specific code for the type of
+    # @param [Symbol] code The application specific code for the type of
     #   transfer to perform an aggregate calculation on. As specified in the
     #   transfer configuration.
-    # @option options :filter [Array[Symbol], or Array[Hash<Symbol,Parameter>]]
+    # @option options :filter [Array<Symbol>, Array<Hash<Symbol, Object>>]
     #   A custom filter to apply before performing the aggregate calculation.
-    #   Currently, filters must be monkey patched as scopes into the DoubleEntry::Line
-    #   class in order to be used as filters, as the example shows.
-    #   If the filter requires a parameter, it must be given in a Hash, otherwise
-    #   pass an array with the symbol names for the defined scopes.
+    #   Currently, filters must be monkey patched as scopes into the
+    #   DoubleEntry::Line class in order to be used as filters, as the example
+    #   shows. If the filter requires a parameter, it must be given in a Hash,
+    #   otherwise pass an array with the symbol names for the defined scopes.
     # @option options :range_type [String] The type of time range to return data
     #   for.  For example, specifying 'month' will return an array of the resulting
     #   aggregate calculation for each month.
@@ -95,7 +110,7 @@ module DoubleEntry
     # @option options :finish [String] The finish (or end) date for the time range
     #   to perform calculations in.  The default finish date is the current date.
     #   The format of the string must be as follows: 'YYYY-mm-dd'
-    # @return [Array[Money/Fixnum]] Returns an array of Money objects for :sum
+    # @return [Array<Money, Fixnum>] Returns an array of Money objects for :sum
     #   and :average calculations, or an array of Fixnum for :count calculations.
     #   The array is indexed by the range_type.  For example, if range_type is
     #   specified as 'month', each index in the array will represent a month.
@@ -110,14 +125,15 @@ module DoubleEntry
     # the provided minimum balance.
     #
     # @example Find users with at least $1,000,000 in their savings accounts
-    #   DoubleEntry.scopes_with_minimum_balance_for_account(
-    #     Money.new(1_000_000_00),
-    #     :savings
-    #   ) # might return user ids: [ 1423, 12232, 34729 ]
-    # @param minimum_balance [Money] Minimum account balance a scope must have
+    #   DoubleEntry::Reporting.scopes_with_minimum_balance_for_account(
+    #     1_000_000.dollars,
+    #     :savings,
+    #   ) # might return the user ids: [ 1423, 12232, 34729 ]
+    # @param [Money] minimum_balance Minimum account balance a scope must have
     #   to be included in the result set.
-    # @param account_identifier [Symbol]
+    # @param [Symbol] account_identifier 
     # @return [Array<Fixnum>] Scopes
+    #
     def scopes_with_minimum_balance_for_account(minimum_balance, account_identifier)
       select_values(sanitize_sql_array([<<-SQL, account_identifier, minimum_balance.cents])).map {|scope| scope.to_i }
         SELECT scope
@@ -132,6 +148,7 @@ module DoubleEntry
     # @api private
     # @return [Boolean] true if all the amounts for an account add up to the final balance,
     #   which they always should.
+    #
     def reconciled?(account)
       scoped_lines = Line.where(:account => "#{account.identifier}", :scope => "#{account.scope}")
       sum_of_amounts = scoped_lines.sum(:amount)

data/lib/double_entry/transfer.rb

@@ -5,10 +5,10 @@ module DoubleEntry
     # @api private
     def self.transfer(defined_transfers, amount, options = {})
       raise TransferIsNegative if amount < Money.empty
-      from, to, code, meta, detail = options[:from], options[:to], options[:code],  options[:meta],  options[:detail]
+      from, to, code, detail = options[:from], options[:to], options[:code],  options[:detail]
       defined_transfers.
         find!(from, to, code).
-        process!(amount, from, to, code, meta, detail)
+        process(amount, from, to, code, detail)
     end
 
     # @api private
@@ -44,24 +44,17 @@ module DoubleEntry
       end
     end
 
-    attr_accessor :code, :from, :to, :description, :meta_requirement
+    attr_accessor :code, :from, :to, :description
 
     def initialize(attributes)
-      @meta_requirement = []
       attributes.each { |name, value| send("#{name}=", value) }
     end
 
-    def process!(amount, from, to, code, meta, detail)
+    def process(amount, from, to, code, detail)
       if from.scope_identity == to.scope_identity and from.identifier == to.identifier
         raise TransferNotAllowed.new
       end
 
-      meta_requirement.each do |key|
-        if meta[key].nil?
-          raise RequiredMetaMissing.new
-        end
-      end
-
       Locking.lock_accounts(from, to) do
         credit, debit = Line.new, Line.new
 
@@ -74,7 +67,6 @@ module DoubleEntry
         credit.amount,  debit.amount  = -amount, amount
         credit.account, debit.account = from, to
         credit.code,    debit.code    = code, code
-        credit.meta,    debit.meta    = meta, meta
         credit.detail,  debit.detail  = detail, detail
         credit.balance, debit.balance = credit_balance.balance, debit_balance.balance
 

data/lib/double_entry/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module DoubleEntry
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/generators/double_entry/install/templates/migration.rb

@@ -20,7 +20,6 @@ class CreateDoubleEntryTables < ActiveRecord::Migration
       t.integer  "partner_id"
       t.string   "partner_account"
       t.string   "partner_scope"
-      t.string   "meta"
       t.integer  "detail_id"
       t.string   "detail_type"
       t.timestamps

data/spec/double_entry/line_spec.rb

@@ -10,13 +10,11 @@ describe DoubleEntry::Line do
         :account => account,
         :partner_account => partner_account,
         :code => code,
-        :meta => meta,
       )
     }
     let(:account) { DoubleEntry.account(:test, :scope => "17") }
     let(:partner_account) { DoubleEntry.account(:test, :scope => "72") }
     let(:code) { :test_code }
-    let(:meta) { "test meta" }
     before { persisted_line.save! }
     subject { DoubleEntry::Line.last }
 
@@ -41,28 +39,6 @@ describe DoubleEntry::Line do
       its("partner_account.account.identifier") { should eq :test }
       its("partner_account.scope") { should eq "91" }
     end
-
-    context "given meta = 'the meta'" do
-      let(:meta) { "the meta" }
-      its(:meta) { should eq "the meta" }
-    end
-
-    context "given meta = nil" do
-      let(:meta) { nil }
-      its(:meta) { should eq nil }
-    end
-
-    context "given meta has not been persisted (NULL)" do
-      let(:persisted_line) {
-        DoubleEntry::Line.new(
-          :amount => Money.new(10_00),
-          :balance => Money.empty,
-          :account => DoubleEntry.account(:savings, :scope => User.make!),
-          :code => code,
-        )
-      }
-      its(:meta) { should eq Hash.new }
-    end
   end
 
   it "has a table name prefixed with double_entry_" do

data/spec/double_entry_spec.rb

@@ -100,7 +100,7 @@ describe DoubleEntry do
         end
 
         config.define_transfers do |transfers|
-          transfers.define(:from => :savings, :to => :cash, :code => :xfer, :meta_requirement => [:ref])
+          transfers.define(:from => :savings, :to => :cash, :code => :xfer)
         end
       end
     end
@@ -115,7 +115,6 @@ describe DoubleEntry do
         :from => savings,
         :to   => cash,
         :code => :xfer,
-        :meta => { :ref => 'shopping!' },
       )
     end
 
@@ -137,7 +136,6 @@ describe DoubleEntry do
           :from => savings,
           :to   => cash,
           :code => :yfer,
-          :meta => { :ref => 'shopping!' },
         )
       }.to raise_error DoubleEntry::TransferNotAllowed
     end
@@ -151,18 +149,6 @@ describe DoubleEntry do
         )
       }.to raise_error DoubleEntry::TransferNotAllowed
     end
-
-    it 'raises an exception when required meta data is omitted' do
-      expect {
-        DoubleEntry.transfer(
-          Money.new(100_00),
-          :from => savings,
-          :to   => cash,
-          :code => :xfer,
-          :meta => {},
-        )
-      }.to raise_error DoubleEntry::RequiredMetaMissing
-    end
   end
 
   describe 'lines' do
@@ -173,7 +159,7 @@ describe DoubleEntry do
           accounts.define(:identifier => :b)
         end
 
-        description = ->(line) { "Money goes #{line.credit? ? 'out' : 'in'}: #{line.amount.format}" }
+        description = ->(line) { "Money goes #{line.decrease? ? 'out' : 'in'}: #{line.amount.format}" }
         config.define_transfers do |transfers|
           transfers.define(:code => :xfer, :from => :a, :to => :b, :description => description)
         end
@@ -208,11 +194,11 @@ describe DoubleEntry do
       expect(credit_line.partner_account).to eq debit_line.account
     end
 
-    it 'knows if it is a credit or debit' do
-      expect(credit_line).to be_credit
-      expect(debit_line).to be_debit
-      expect(credit_line).to_not be_debit
-      expect(debit_line).to_not be_credit
+    it 'knows if it is an increase or decrease' do
+      expect(credit_line).to be_decrease
+      expect(debit_line).to be_increase
+      expect(credit_line).to_not be_increase
+      expect(debit_line).to_not be_decrease
     end
 
     it 'can reference its partner' do

data/spec/support/schema.rb

@@ -21,7 +21,6 @@ ActiveRecord::Schema.define do
     t.integer  "partner_id"
     t.string   "partner_account"
     t.string   "partner_scope"
-    t.string   "meta"
     t.integer  "detail_id"
     t.string   "detail_type"
     t.datetime "created_at"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: double_entry
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -16,7 +16,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-11 00:00:00.000000000 Z
+date: 2014-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: money