ledger

README

Ledger in Go

This is a project to parse and import transactions in a ledger file similar to the Ledger command line tool written in C++.

I have been using this tool to track my finances for over a year. I have data going back over five years.

Simple Ledger file support

The ledger file this will parse is much simpler than the C++ tool.

Transaction Format:

<YYYY/MM/dd> <Payee description>
    <Account Name 1>    <Amount 1>
    .
    .
    .
    <Account Name N>    <Amount N>

The transaction must balance (the positive amounts must equal negative amounts). One of the account lines is allowed to have no amount. The amount necessary to balance the transaction will be added to that account for the transaction. Amounts must be decimal numbers with a negative(-) sign in front if necessary.

Example transaction:

2013/01/02 McDonald's #24233 HOUSTON TX
    Expenses:Dining Out:Fast Food        5.60
    Wallet:Cash

A ledger file is assumed to be a list of transactions separated by a new line.

ledger

This will parse a ledger file into an array of Transaction structs. There is also a function get balances for all accounts in the ledger file.

GoDoc

cmd/ledger

A very simplistic version of Ledger. Supports "balance", "register", "print" and "stats" commands.

Example usage:

    ledger -f ledger.dat bal
    ledger -f ledger.dat bal Cash
    ledger -f ledger.dat reg
    ledger -f ledger.dat reg Food
    ledger -f ledger.dat print
    ledger -f ledger.dat stats

cmd/limport

Using an existing ledger as input to a bayesian classifier, it will attempt to classify an imported csv of transactions based on payee names and print them in a ledger file format.

Attempts to get payee, date, and amount based on headers in the csv file.

Example usage:

    ledger -f ledger.dat discover discover-recent-transactions.csv

In the above example "discover" is the account search string to use to find the account that all transactions in the csv file should be applied too. The second account to use for each transaction will be picked based on the bayesian classification of the payee.

cmd/lweb

A website view of the ledger file. This program will show the account list, and ledger for a given account.

Reports available through the web interface are taken from a toml configuration file of the report configuration. See reports-sample.toml for examples.

Example usage:

    lweb -f ledger.dat -r reports.toml --port 8080

Installing components

    go get -u github.com/howeyc/ledger/...

Incompatibilities

• C++ Ledger permits having amounts prefixed with $; Ledger in Go does not

• C++ Ledger permits an empty Payee Description; Ledger in Go does not

Documentation

Index

• type Account
  • func GetBalances(generalLedger []*Transaction, filterArr []string) []*Account
• type Period
• type RangeBalance
  • func BalancesByPeriod(trans []*Transaction, per Period, rType RangeType) []*RangeBalance
• type RangeType
• type Transaction
  • func ParseLedger(ledgerReader io.Reader) (generalLedger []*Transaction, err error)
  • func TransactionsInDateRange(trans []*Transaction, start, end time.Time) []*Transaction

Types

type Account

type Account struct {
	Name    string
	Balance *big.Rat
}

Account holds the name and balance

func GetBalances

func GetBalances(generalLedger []*Transaction, filterArr []string) []*Account

GetBalances provided a list of transactions and filter strings, returns account balances of all accounts that have any filter as a substring of the account name. Also returns balances for each account level depth as a separate record.

Accounts are sorted by name.

type Period

type Period string

Period is used to specify the length of a date range or frequency

const (
	PeriodMonth   Period = "Monthly"
	PeriodQuarter Period = "Quarterly"
	PeriodYear    Period = "Yearly"
)

Periods suppored by ledger

type RangeBalance

type RangeBalance struct {
	Start, End time.Time
	Balances   []*Account
}

RangeBalance contains the account balances and the start and end time of the date range

func BalancesByPeriod

func BalancesByPeriod(trans []*Transaction, per Period, rType RangeType) []*RangeBalance

BalancesByPeriod will return the account balances for each period.

type RangeType

type RangeType string

RangeType is used to specify how the data is "split" into sections

const (
	// RangeSnapshot will have each section be the running total at the time of the snapshot
	RangeSnapshot RangeType = "Snapshot"

	// RangePartition will have each section be the accumulated value of the transactions within that partition's date range
	RangePartition RangeType = "Partition"
)

type Transaction

type Transaction struct {
	Payee          string
	Date           time.Time
	AccountChanges []Account
}

Transaction is the basis of a ledger. The ledger holds a list of transactions. A Transaction has a Payee, Date (with no time, or to put another way, with hours,minutes,seconds values that probably doesn't make sense), and a list of Account values that hold the value of the transaction for each account.

func ParseLedger

func ParseLedger(ledgerReader io.Reader) (generalLedger []*Transaction, err error)

ParseLedger parses a ledger file and returns a list of Transactions.

Transactions are sorted by date.

func TransactionsInDateRange

func TransactionsInDateRange(trans []*Transaction, start, end time.Time) []*Transaction

TransactionsInDateRange returns a new array of transactions that are in the date range specified by start and end. The returned list contains transactions on the same day as start but does not include any transactions on the day of end.