Module: DoubleEntry

Includes:: Configurable

Defined in:: lib/double_entry.rb,
lib/double_entry/line.rb,
lib/double_entry/errors.rb,
lib/double_entry/account.rb,
lib/double_entry/locking.rb,
lib/double_entry/version.rb,
lib/double_entry/transfer.rb,
lib/double_entry/configurable.rb,
lib/double_entry/configuration.rb,
lib/double_entry/line_metadata.rb,
lib/double_entry/account_balance.rb,
lib/double_entry/balance_calculator.rb,
lib/double_entry/validation/line_check.rb,
lib/double_entry/validation/account_fixer.rb,
lib/generators/double_entry/install/install_generator.rb

Overview

Keep track of all the monies!

This module provides the public interfaces for everything to do with transferring money around the system.

Defined Under Namespace

Modules: BalanceCalculator, Configurable, Generators, Locking, Validation Classes: Account, AccountBalance, AccountIdentifierTooLongError, AccountWouldBeSentNegative, AccountWouldBeSentPositiveError, Configuration, DoubleEntryError, DuplicateAccount, DuplicateTransfer, Line, LineMetadata, MismatchedCurrencies, MissingAccountError, Railtie, ScopeIdentifierTooLongError, Transfer, TransferCodeTooLongError, TransferIsNegative, TransferNotAllowed, UnknownAccount

Constant Summary collapse

VERSION =

'2.0.0'

Class Method Summary collapse

.account(identifier, options = {}) ⇒ DoubleEntry::Account::Instance

Get the particular account instance with the provided identifier and scope.
.balance(account, options = {}) ⇒ Money

Get the current or historic balance of an account.
.lock_accounts(*accounts) { ... } ⇒ Object

Lock accounts in preparation for transfers.
.table_name_prefix ⇒ Object private
.transfer(amount, options = {}) ⇒ [Line, Line]

Transfer money from one account to another.

Methods included from Configurable

included

Class Method Details

.account(identifier, options = {}) ⇒ `DoubleEntry::Account::Instance`

Get the particular account instance with the provided identifier and scope.

Examples:

Obtain the ‘cash’ account for a user

DoubleEntry.account(:cash, scope: user)

Parameters:

identifier (Symbol) —

The symbol identifying the desired account. As specified in the account configuration.
options (Hash) (defaults to: {}) —

a customizable set of options

Options Hash (options):

:scope (Object) —

Limit the account to the given scope. As specified in the account configuration.

Returns:

(DoubleEntry::Account::Instance)

Raises:

(DoubleEntry::UnknownAccount) —

The described account has not been configured. It is unknown.
(DoubleEntry::AccountScopeMismatchError) —

The provided scope does not match that defined on the account.



51
52
53

# File 'lib/double_entry.rb', line 51

def account(identifier, options = {})
  Account.account(identifier, options)
end

.balance(account, options = {}) ⇒ `Money`

Get the current or historic balance of an account.

Examples:

Obtain the current balance of my checking account

checking_account = DoubleEntry.account(:checking, scope: user)
DoubleEntry.balance(checking_account)

Obtain the current balance of my checking account (without account or user model)

DoubleEntry.balance(:checking, scope: user_id)

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))

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),
)

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),
)

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),
)

Parameters:

account (DoubleEntry::Account:Instance, Symbol) —

Find the balance for this account
options (Hash) (defaults to: {}) —

a customizable set of options

Options Hash (options):

:scope (Object) —

The scope identifier of the account (only needed if the provided account is a symbol).
:from (Time) —

used with :to, consider only the time between these dates
:to (Time) —

used with :from, consider only the time between these dates
:at (Time) —

obtain the account balance at this time
:code (Symbol) —

consider only the transfers with this code
:codes (Array<Symbol>) —

consider only the transfers with these codes

Returns:

(Money) —

The balance

Raises:

(DoubleEntry::UnknownAccount) —

The described account has not been configured. It is unknown.
(DoubleEntry::AccountScopeMismatchError) —

The provided scope does not match that defined on the account.

# File 'lib/double_entry.rb', line 142

def balance(account, options = {})
  account = account(account, options) if account.is_a? Symbol
  BalanceCalculator.calculate(account, options)
end

.lock_accounts(*accounts) { ... } ⇒ `Object`

Lock accounts in preparation for transfers.

This creates a transaction, and uses database-level locking to ensure that we’re the only ones who can transfer to or from the given accounts for the duration of the transaction.

Examples:

Lock the savings and checking accounts for a user

checking_account = DoubleEntry.account(:checking, scope: user)
savings_account  = DoubleEntry.account(:savings,  scope: user)
DoubleEntry.lock_accounts(checking_account, savings_account) do
  # ...
end

Yields:

Hold the locks while the provided block is processed.

Raises:

(DoubleEntry::Locking::LockMustBeOutermostTransaction) —

The transaction must be the outermost database transaction



163
164
165

# File 'lib/double_entry.rb', line 163

def lock_accounts(*accounts, &block)
  Locking.lock_accounts(*accounts, &block)
end

.table_name_prefix ⇒ `Object`

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



168
169
170

# File 'lib/double_entry.rb', line 168

def table_name_prefix
  'double_entry_'
end

.transfer(amount, options = {}) ⇒ `[Line, Line]`

Transfer money from one account to another.

Only certain transfers are allowed. Define legal transfers in your configuration file.

If you’re doing more than one transfer in one hit, or you’re doing other database operations along with your transfer, you’ll need to use the lock_accounts method.

Examples:

Transfer $20 from a user’s checking to savings account

checking_account = DoubleEntry.account(:checking, scope: user)
savings_account  = DoubleEntry.account(:savings,  scope: user)
credit, debit = DoubleEntry.transfer(
  20.dollars,
  from: checking_account,
  to:   savings_account,
  code: :save,
)

Parameters:

amount (Money) —

The quantity of money to transfer from one account to the other.
options (Hash) (defaults to: {}) —

a customizable set of options

Options Hash (options):

:from (DoubleEntry::Account::Instance) —

Transfer money out of this account.
:to (DoubleEntry::Account::Instance) —

Transfer money into this account.
:code (Symbol) —

The application specific code for this type of transfer. As specified in the transfer configuration.
:detail (ActiveRecord::Base) —

ActiveRecord model associated (via a polymorphic association) with the transfer.

Returns:

([Line, Line]) —

The credit & debit (in that order) created by the transfer

Raises:

(DoubleEntry::TransferIsNegative) —

The amount is less than zero.
(DoubleEntry::TransferNotAllowed) —

A transfer between these accounts with the provided code is not allowed. Check configuration.



88
89
90

# File 'lib/double_entry.rb', line 88

def transfer(amount, options = {})
  Transfer.transfer(amount, options)
end

Module: DoubleEntry

Overview

Defined Under Namespace

Constant Summary collapse

Class Method Summary collapse

Methods included from Configurable

Class Method Details

.account(identifier, options = {}) ⇒ DoubleEntry::Account::Instance

Examples:

Obtain the ‘cash’ account for a user

.balance(account, options = {}) ⇒ Money

Examples:

Obtain the current balance of my checking account

Obtain the current balance of my checking account (without account or user model)

Obtain a historic balance of my checking account

Obtain the net balance of my checking account during may

Obtain the balance of salary deposits made to my checking account during may

Obtain the balance of salary & lottery deposits made to my checking account during may

.lock_accounts(*accounts) { ... } ⇒ Object

Examples:

Lock the savings and checking accounts for a user

.table_name_prefix ⇒ Object

.transfer(amount, options = {}) ⇒ [Line, Line]

Examples:

Transfer $20 from a user’s checking to savings account

.account(identifier, options = {}) ⇒ `DoubleEntry::Account::Instance`

.balance(account, options = {}) ⇒ `Money`

.lock_accounts(*accounts) { ... } ⇒ `Object`

.table_name_prefix ⇒ `Object`

.transfer(amount, options = {}) ⇒ `[Line, Line]`