bal - a really, really simple finance balancer

fflarex · 2010-10-16 19:34:06

I know there are probably tons of simple awk-based checkbook scripts out there, but I'm pretty fond of mine so I thought I'd share it. I created it because ledger was too complex for my needs, but I loved the text-based nature of ledger. bal is probably not for you if you like GUI applications, or need support for multiple currencies and complex investments or accounts. ledger handles all of that fine though, and bal's file format was designed to be easy to convert into ledger's file format in case your finances become more complex in the future.

You record your transactions in a text file. Each transaction is a transfer from one account to another, so in that sense bal is like a double-entry accounting solution (however, it does not help with catching errors like most double-entry solutions because it is impossible for your accounts to add up to anything but zero!). All bal does is read this file and produce a report detailing the balances of your accounts within a certain time frame (by default, from the beginning of time until today). Rather than assigning a category like 'Food' to a purchase, you would simply have an expense account called 'Food' and transfer money from your checking account to your food account. Then when you check the balances of your accounts, the amount under the food account would indicate how much you have spent of food.

#!/bin/awk -f
# Simple finance balancer

# File Format: one transaction per line
# Tab-separated columns of date, account1, account2, payee/description, amount
# The amount specified is transferred from account2 to account1

# Limit by date with the -b and -e flags
# The date is just treated as a string, so be consistent!

# Using good account names and multiple ledger files eliminates the need for
# special support for reconciliation, simple budgeting, or "virtual transactions".

function shift() {
    for (i = 1; i < ARGC; i++) {
        ARGV[i] = ARGV[i+1]
    }
    delete ARGV[ARGC--]
}

BEGIN {
    FS="\t+"

    date = "date +%Y-%m-%d"
    if (ARGV[1] == "-b") { shift(); from  = ARGV[1]; shift(); }
    else from = "0"
    if (ARGV[1] == "-e") { shift(); until = ARGV[1]; shift(); }
    else { date | getline until; close(date) }
}

$1 >= from && $1 <= until {
    balance[$2] += $5
    balance[$3] -= $5
}

END {
    for (account in balance) {
        printf("%-20s %10.2f\n", account ":", balance[account]) | "sort"
    }
    close("sort")
}

There is no error checking, and you are expected to understand the source if you use it. But honestly, that should only take you about 10 minutes or less if you know any awk at all. If you have any questions please ask, but I have no intention of writing up full documentation for a 25 line program, which would far exceed the size of the source code. Please browse the docs of gnucash or ledger for help with some of the accounting concepts used in bal.

I'll just give a quick sample ledger and invocation of bal. You must use tabs in your ledger, but I think I can only display spaces on this forum (also, you can use multiple tabs to align your columns):

2010-10-01      a/Checking      q/Opening Balances      Checking           25.00
2010-10-01      a/Savings       q/Opening Balances      Savings           500.00
2010-10-03      a/Checking      e/Food                  Restaurant        -10.00
2010-10-04      e/Food          l/Credit Card           Restaurant         35.00
2010-10-07      a/Checking*     e/Food                  Grocery Store     -40.00
2010-10-08      a/Savings       i/Paycheck              Work              120.00

If I run bal on this file I get this:

$ bal ledger.sample
a/Checking:               15.00
a/Checking*:             -40.00
a/Savings:               620.00
e/Food:                   85.00
i/Paycheck:             -120.00
l/Credit Card:           -35.00
q/Opening Balances:     -525.00

Those lower case letters and slashes are not essential to using bal, they just help categorize my accounts (where a stands for assets, e for expenses, i for income, l for liabilities, and q for equity). I use the asterisk after the Checking account to indicate an unreconciled transaction. I'll simply go in and delete the asterisk when I reconcile my accounts. So this report tells me that my Checking balance was $15 last time I reconciled, but I have since spent $40 and overdrawn my account by $25! It also tells me that I have spent a total of $85 on food, that I owe $35 on my credit card, that I started out with $525, and I have made $120 working.

You'll notice that my income account is negative, while my expense account is positive. This will seem strange if you are unfamiliar with double-entry accounting. Please skim through gnucash's or ledger's docs, or Wikipedia's article on double-entry accounting to understand why. bal also trivially supports ledger's "virtual accounts" feature, simply by entering your virtual transactions in a separate file and invoking bal like `bal ledger ledger.virt`.

Last edited by fflarex (2010-10-16 20:32:19)

Sara · 2010-10-31 13:38:31

This looks pretty neat. Thanks for sharing.

Last edited by Sara (2010-10-31 13:39:31)

Arch Linux

#1 2010-10-16 19:34:06

bal - a really, really simple finance balancer

#2 2010-10-31 13:38:31

Re: bal - a really, really simple finance balancer

Board footer