journal

Documentation

Overview

Package journal implements the processing of bookkeeping journals from keeper files.

File format

See the documentation for the kpr package for keeper file syntax. This section describes some additional semantics for keeper files as implemented by this package.

Unit declarations must come before any use of that unit. Otherwise, the order of entries in keeper files is not significant.

The total of all splits in a transaction must balance. Only one split in a transaction can omit the amount, which will be inferred as the remaining amount needed to balance the transaction. This inference does not work if more than one unit is unbalanced.

Balance assertions apply at the end of the day, to match how balances are handled in practice.

Tree balance assertions apply to a tree of accounts.

Disabled accounts prevent transactions from posting to that account. Disable account entries also assert that the account balance is zero.

Example

const contents = `unit USD 100
tx 2020-01-02 "Paycheck"
Income:Salary -12 USD
Assets:Bank
end
`
j, _ := Compile(&CompileArgs{
	Inputs: []CompileInput{
		Bytes("example", []byte(contents)),
	},
})
fmt.Printf("%s", j.Balances["Assets:Bank"])

Output:

12.00 USD

Index

• type Account
  • func (a Account) Leaf() string
  • func (a Account) Parent() Account
  • func (a Account) Parts() []string
  • func (a Account) Under(parent Account) bool
• type AccountInfo
• type AccountMap
• type Amount
  • func (a *Amount) Equal(b *Amount) bool
  • func (a *Amount) Neg()
  • func (a *Amount) Sign() int
  • func (a *Amount) String() string
  • func (a *Amount) Zero() bool
• type Balance
  • func (b *Balance) Add(a *Amount)
  • func (b *Balance) AddBal(b2 *Balance)
  • func (b *Balance) Amount(u Unit) *Amount
  • func (b *Balance) Amounts() []*Amount
  • func (b *Balance) Clear()
  • func (b *Balance) Empty() bool
  • func (b *Balance) Equal(b2 *Balance) bool
  • func (b *Balance) Has(u Unit) bool
  • func (b *Balance) Neg()
  • func (b *Balance) Set(b2 *Balance)
  • func (b Balance) String() string
  • func (b *Balance) Units() []Unit
• type BalanceAssert
  • func (b *BalanceAssert) Date() civil.Date
  • func (b *BalanceAssert) Position() token.Position
• type Balances
  • func (b Balances) Accounts() []Account
  • func (b Balances) Add(a Account, am *Amount)
  • func (b Balances) Delete(a Account)
  • func (b Balances) Neg()
• type CompileArgs
• type CompileInput
  • func Bytes(filename string, src []byte) CompileInput
  • func Files(filename ...string) []CompileInput
• type DisableAccount
  • func (c *DisableAccount) Date() civil.Date
  • func (c *DisableAccount) Position() token.Position
• type Entry
• type Journal
  • func Compile(a *CompileArgs) (*Journal, error)
  • func (j *Journal) BalancesEnding(d civil.Date) Balances
• type Split
• type Transaction
  • func (t *Transaction) Date() civil.Date
  • func (t *Transaction) Position() token.Position
• type Unit
  • func (u Unit) String() string

Examples

• Package
• Account.Leaf
• Account.Parent
• Account.Parts
• Account.Under
• Compile

Types

type Account

type Account string

Account is a bookkeeping account. Accounts are colon separated paths, like "Income:Salary".

func (Account) Leaf

func (a Account) Leaf() string

Leaf returns the leaf part of the Account (after the last colon).

Example

fmt.Printf("%#v\n", Account("Assets:Cash").Leaf())
fmt.Printf("%#v\n", Account("Assets").Leaf())

Output:

"Cash"
"Assets"

func (Account) Parent

func (a Account) Parent() Account

Parent returns the parent account.

Example

fmt.Printf("%#v\n", Account("Assets:Cash").Parent())
fmt.Printf("%#v\n", Account("Assets").Parent())

Output:

"Assets"
""

func (Account) Parts

func (a Account) Parts() []string

Parts returns the parts of the account between the colons.

Example

fmt.Printf("%#v\n", Account("Assets:Cash").Parts())
fmt.Printf("%#v\n", Account("Assets").Parts())

Output:

[]string{"Assets", "Cash"}
[]string{"Assets"}

func (Account) Under

func (a Account) Under(parent Account) bool

Under returns true if the Account is a child account of the argument.

Example

fmt.Println(Account("Assets:Cash").Under("Assets"))
fmt.Println(Account("Assets:Cash:Wallet").Under("Assets"))
fmt.Println(Account("Assets:Cash").Under(""))

Output:

true
true
true

type AccountInfo

type AccountInfo struct {
	// If the account is disabled, points to the entry that
	// disabled the account.  Otherwise this is nil.
	Disabled *DisableAccount
	Metadata map[string]string
}

An AccountInfo represents account information.

type AccountMap

type AccountMap map[Account]*AccountInfo

An AccountMap holds account information for multiple accounts.

type Amount

type Amount struct {
	Number big.Int
	Unit   Unit
}

An Amount is an amount of a certain unit, e.g., currency or commodity.

func (*Amount) Equal

func (a *Amount) Equal(b *Amount) bool

Equal returns true if the amounts are equal.

func (*Amount) Neg

func (a *Amount) Neg()

Neg flips the sign of the amount.

func (*Amount) Sign

func (a *Amount) Sign() int

Sign returns:

-1 if amount <  0
 0 if amount == 0
+1 if amount >  0

func (*Amount) String

func (a *Amount) String() string

func (*Amount) Zero

func (a *Amount) Zero() bool

Zero returns whether the amount is zero.

type Balance

type Balance struct {
	// contains filtered or unexported fields
}

A Balance represents a balance of amounts of various units. The zero value is ready for use.

func (*Balance) Add

func (b *Balance) Add(a *Amount)

Add adds an amount to the balance.

func (*Balance) AddBal

func (b *Balance) AddBal(b2 *Balance)

AddBal adds the amounts of the argument balance.

func (*Balance) Amount

func (b *Balance) Amount(u Unit) *Amount

Amount returns the amount of the given unit in the balance. The returned amount is independent memory from the balance.

func (*Balance) Amounts

func (b *Balance) Amounts() []*Amount

Amounts returns the amounts in the balance. The amounts are sorted by unit.

func (*Balance) Clear

func (b *Balance) Clear()

Clear clears the balance, making it empty/zero.

func (*Balance) Empty

func (b *Balance) Empty() bool

Empty returns true if the balance is empty/zero.

func (*Balance) Equal

func (b *Balance) Equal(b2 *Balance) bool

Equal returns true if the two balances are equal.

func (*Balance) Has

func (b *Balance) Has(u Unit) bool

Has returns true if the balance has a non-zero amount for the unit.

func (*Balance) Neg

func (b *Balance) Neg()

Neg negates the sign of the balance.

func (*Balance) Set

func (b *Balance) Set(b2 *Balance)

Set sets the receiver balance to the argument balance.

func (Balance) String

func (b Balance) String() string

func (*Balance) Units

func (b *Balance) Units() []Unit

Units returns the units in the balance

type BalanceAssert

type BalanceAssert struct {
	EntryPos  token.Position
	EntryDate civil.Date
	Account   Account
	// Whether this is a balance assertion for the account tree.
	Tree     bool
	Declared Balance
	Actual   Balance
	Diff     Balance // Actual - Declared
}

A BalanceAssert entry represents a balance assertion.

func (*BalanceAssert) Date

func (b *BalanceAssert) Date() civil.Date

func (*BalanceAssert) Position

func (b *BalanceAssert) Position() token.Position

type Balances

type Balances map[Account]*Balance

A Balances maps multiple accounts to their balances.

func (Balances) Accounts

func (b Balances) Accounts() []Account

Accounts returns all of the accounts with balances in sorted order.

func (Balances) Add

func (b Balances) Add(a Account, am *Amount)

Add adds an amount to an account, even if the account is not yet in the map.

func (Balances) Delete

func (b Balances) Delete(a Account)

Delete deletes all amounts for the account.

func (Balances) Neg

func (b Balances) Neg()

Neg negates the signs of the balances.

type CompileArgs

type CompileArgs struct {
	Inputs []CompileInput
	// If set, only consider entries up to and including the
	// specified date.
	Ending civil.Date
}

A CompileArgs describes arguments to Compile.

type CompileInput

type CompileInput interface {
	Filename() string
	Src() ([]byte, error)
}

A CompileInput defines an input source for Compile.

func Bytes

func Bytes(filename string, src []byte) CompileInput

Bytes returns an option that specifies input bytes.

func Files

func Files(filename ...string) []CompileInput

Files returns an option that specifies input files.

type DisableAccount

type DisableAccount struct {
	EntryPos  token.Position
	EntryDate civil.Date
	Account   Account
}

A DisableAccount entry represents an account closing.

func (*DisableAccount) Date

func (c *DisableAccount) Date() civil.Date

func (*DisableAccount) Position

func (c *DisableAccount) Position() token.Position

type Entry

type Entry interface {
	Date() civil.Date
	Position() token.Position
	// contains filtered or unexported methods
}

All entry types implement Entry.

Entry types:

• Transaction
• BalanceAssert
• DisableAccount

type Journal

type Journal struct {
	// Entries are the journal entries, sorted chronologically.
	Entries []Entry
	// Accounts contains all accounts and the associated account information.
	Accounts AccountMap
	// Balances is the final balance for all accounts.
	Balances Balances
	// BalanceErrors contains the balance assertion entries that failed.
	BalanceErrors []*BalanceAssert
}

A Journal represents bookkeeping information compiled from keeper file source.

Be careful; a Journal contains a lot of shared pointers internally. Modifying anything in a Journal is not recommended.

func Compile

func Compile(a *CompileArgs) (*Journal, error)

Compile compiles keeper file source into a Journal. Balance assertion errors are stored in the returned Journal rather than returned as errors here, to enable the caller to inspect the transactions to identify the error.

Example

package main

import (
	"fmt"
	"sort"

	"go.felesatra.moe/keeper/journal"
)

func main() {
	input := []byte(`unit USD 100
tx 2020-01-01 "Initial balance"
Assets:Cash 100 USD
Equity:Capital
end
`)
	j, err := journal.Compile(&journal.CompileArgs{
		Inputs: []journal.CompileInput{journal.Bytes("input", input)},
	})
	if err != nil {
		panic(err)
	}
	var as []journal.Account
	for a := range j.Accounts {
		as = append(as, a)
	}
	sort.Slice(as, func(i, j int) bool { return as[i] < as[j] })
	for _, a := range as {
		fmt.Println(a)
	}
}

Output:

Assets:Cash
Equity:Capital

func (*Journal) BalancesEnding

func (j *Journal) BalancesEnding(d civil.Date) Balances

BalancesEnding returns the balances of all accounts at the close of the given date.

type Split

type Split struct {
	Account Account
	Amount  *Amount
}

Split is one split in a transaction. This describes a change in the amount of one unit for one account.

type Transaction

type Transaction struct {
	EntryPos    token.Position
	EntryDate   civil.Date
	Description string
	Splits      []Split
}

A Transaction entry describes a bookkeeping transaction. The total balance of all splits should be zero.

func (*Transaction) Date

func (t *Transaction) Date() civil.Date

func (*Transaction) Position

func (t *Transaction) Position() token.Position

type Unit

type Unit struct {
	// Symbol for the unit.
	// This should be all uppercase ASCII letters.
	Symbol string
	// Scale indicates the minimum fractional unit amount,
	// e.g. 100 means 0.01 is the smallest amount.
	// This should be a multiple of 10.
	Scale uint64
}

Unit describes a unit, e.g., currency or commodity.

func (Unit) String

func (u Unit) String() string