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/line_metadata.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/double_entry/reporting/line_aggregate_filter.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, LineMetadata, MismatchedCurrencies, MissingAccountError, ScopeIdentifierTooLongError, Transfer, TransferCodeTooLongError, TransferIsNegative, TransferNotAllowed, UnknownAccount

Constant Summary collapse

VERSION =

'1.0.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.



43
44
45

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

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 133

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



154
155
156

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

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.



159
160
161

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

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.



79
80
81

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

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

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

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

.table_name_prefix ⇒ Object

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

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

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

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

.table_name_prefix ⇒ `Object`

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