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
- type AccountInfo
- type AccountMap
- type Amount
- 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
- type Balances
- type CompileArgs
- type CompileInput
- type DisableAccount
- type Entry
- type Journal
- type Split
- type Transaction
- type Unit
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Account ¶
type Account string
Account is a bookkeeping account. Accounts are colon separated paths, like "Income:Salary".
func (Account) Leaf ¶
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 ¶
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 ¶
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"}
type AccountInfo ¶ added in v0.15.0
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 ¶ added in v0.20.0
type AccountMap map[Account]*AccountInfo
An AccountMap holds account information for multiple accounts.
type Amount ¶
An Amount is an amount of a certain unit, e.g., currency or commodity.
func (*Amount) Equal ¶ added in v0.18.0
Equal returns true if the amounts are equal.
func (*Amount) Sign ¶ added in v0.20.0
Sign returns:
-1 if amount < 0 0 if amount == 0 +1 if amount > 0
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) AddBal ¶ added in v0.14.0
AddBal adds the amounts of the argument balance.
func (*Balance) Amount ¶
Amount returns the amount of the given unit in the balance. The returned amount is independent memory from the balance.
func (*Balance) Amounts ¶
Amounts returns the amounts in the balance. The amounts are sorted by unit.
func (*Balance) Clear ¶ added in v0.14.0
func (b *Balance) Clear()
Clear clears the balance, making it empty/zero.
func (*Balance) Empty ¶
Empty returns true if the balance is empty/zero.
func (*Balance) Equal ¶
Equal returns true if the two balances are equal.
func (*Balance) Has ¶ added in v0.18.0
Has returns true if the balance has a non-zero amount for the unit.
func (*Balance) Set ¶ added in v0.18.0
Set sets the receiver balance to the argument 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 ¶
A Balances maps multiple accounts to their balances.
func (Balances) Accounts ¶ added in v0.14.0
Accounts returns all of the accounts with balances in sorted order.
func (Balances) Add ¶
Add adds an amount to an account, even if the account is not yet in the map.
type CompileArgs ¶ added in v0.20.0
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 ¶ added in v0.20.0
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 ¶ added in v0.20.0
func Files(filename ...string) []CompileInput
Files returns an option that specifies input files.
type DisableAccount ¶ added in v0.13.0
A DisableAccount entry represents an account closing.
func (*DisableAccount) Date ¶ added in v0.13.0
func (c *DisableAccount) Date() civil.Date
func (*DisableAccount) Position ¶ added in v0.13.0
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:
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
type Split ¶
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.
Source Files