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, AccountWouldBeSentNegative, Configuration, DuplicateAccount, DuplicateTransfer, Line, RequiredMetaMissing, Transfer, TransferIsNegative, TransferNotAllowed, UnknownAccount, UserAccountNotLocked

Constant Summary

VERSION =

"0.3.1"

Class Method Summary

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

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

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

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

Get the current or historic balance of an account.

Parameters:

• account (DoubleEntry::Account:Instance, Symbol)
• options (Hash) (defaults to: {}) —

  a customizable set of options

Options Hash (options):

• :scope (Object, String)
• :from (Time)
• :to (Time)
• :at (Time)
• :code (Symbol)
• :codes (Array<Symbol>)

Returns:

• (Money)

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

def balance(account, options = {})
  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

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

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.

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

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(
  Money.new(20_00),
  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.

• :meta (String) —

  Metadata to associate with this transfer.

• :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.

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

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