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/reporting.rb,
lib/double_entry/configurable.rb,
lib/double_entry/configuration.rb,
lib/double_entry/account_balance.rb,
lib/double_entry/balance_calculator.rb,
lib/double_entry/reporting/aggregate.rb,
lib/double_entry/reporting/day_range.rb,
lib/double_entry/reporting/hour_range.rb,
lib/double_entry/reporting/time_range.rb,
lib/double_entry/reporting/week_range.rb,
lib/double_entry/reporting/year_range.rb,
lib/double_entry/reporting/month_range.rb,
lib/double_entry/validation/line_check.rb,
lib/double_entry/reporting/line_aggregate.rb,
lib/double_entry/reporting/aggregate_array.rb,
lib/double_entry/reporting/time_range_array.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, Reporting, Validation Classes: Account, AccountBalance, AccountIdentifierTooLongError, AccountScopeMismatchError, AccountWouldBeSentNegative, AccountWouldBeSentPositiveError, Configuration, DuplicateAccount, DuplicateTransfer, Line, MismatchedCurrencies, MissingAccountError, ScopeIdentifierTooLongError, Transfer, TransferCodeTooLongError, TransferIsNegative, TransferNotAllowed, UnknownAccount

Constant Summary collapse

VERSION =

'0.10.1'

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 = {}) ⇒ Object
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.



42
43
44

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

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 132

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



153
154
155

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

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.



158
159
160

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

def table_name_prefix
  'double_entry_'
end

.transfer(amount, options = {}) ⇒ `Object`

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

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.



78
79
80

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

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 = {}) ⇒ Object

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 = {}) ⇒ `Object`