A new feature! And my thanks to Martin
John Wiegley
caused me to think some more about certain features missing in Ledger.
We had talked about adding an @check directive, which indicates at a
certain point in your Ledger file that an account's balance must match
a given amount. This is great for making sure you didn't make a
mistake while balancing your checkbook against the latest statement,
and also ensures that an account never becomes accidentally unbalanced
in the future due to later edits. I consider this a "must have"
feature.
After much thought today, I stumbled upon a solution which is so
basic, and so natural to the syntax and functioning of Ledger, that I
can't believe it never occurred to me in all these past 5 years! My
special thanks go to Martin for prompting this idea, which took all of
one hour to implement in 2.6.1b. It was just that easy! and only
costs a bit of CPU time.
Here's the new syntax. It's very simple, but has several uses:
# Setting an account's balance
You can now manually set an account's balance to whatever you want, at
any time. Here's how it might look at the beginning of your Ledger
file:
2008/07/27 Starting fresh
Assets:Checking = $1,000.00
Equity:Opening Balances
If Assets:Checking is empty, this is no different from omitting the
"=". However, if Assets:Checking did have a prior balance, the amount
of the transaction will be auto-calculated so that the final balance
of Assets:Checking is now $1,000.00.
Let me give an example of this. Say you have this:
2008/07/27 Starting fresh
Assets:Checking $750.00
Equity:Opening Balances
2008/07/27 Starting fresh
Assets:Checking = $1,000.00
Equity:Adjustments
These two entries are exactly equivalent to these two:
2008/07/27 Starting fresh
Assets:Checking $750.00
Equity:Opening Balances
2008/07/27 Starting fresh
Assets:Checking $250.00
Equity:Adjustments
The use of the "=" sign here is that it sets the transaction's amount
to whatever is required to satisfy the assignment. This is the
behavior if the transaction's amount is left empty.
# Multiple commodities
As far as commodities go, the = sign only works if the account
balance's commodity matches the commodity of the amount after the
equals sign. However, if the account has multiple commodities, only
the matching commodity is affected. Here's what I mean:
2008/07/24 Opening Balance
Assets:Checking = $250.00 ; we force set it
Equity:Opening Balances
2008/07/24 Opening Balance
Assets:Checking = EC 250.00 ; we force set it again
Equity:Opening Balances
This is an error, because $250.00 cannot be auto-balanced to match EC
250.00. However:
2008/07/24 Opening Balance
Assets:Checking = $250.00 ; we force set it again
Assets:Checking EC 100.00 ; and add some EC's
Equity:Opening Balances
2008/07/24 Opening Balance
Assets:Checking = EC 250.00 ; we force set the EC's
Equity:Opening Balances
This is *not* an error, because the latter auto-balancing transaction
only affects the EC 100.00 part of the account's balance; the $250.00
part is left alone.
# Checking statement balances
When you reconcile a statement, there are typically one or more
transactions which result in a known balance. Here's how you specify
that in your Ledger data:
2008/07/24 Opening Balance
Assets:Checking = $100.00
Equity:Opening Balances
2008/07/30 We spend money, with a known balance afterward
Expenses:Food $20.00
Assets:Checking = $80.00
2008/07/30 Again we spend money, but this time with all the info
Expenses:Food $20.00
Assets:Checking $-20.00 = $60.00
2008/07/30 This entry yield an 'unbalanced' error
Expenses:Food $20.00
Assets:Checking $-20.00 = $30.00
The last entry in this set fails to balance with an unbalanced
remainder of $-10.00. Either the entry must be corrected, or you can
have Ledger deal with the remainder automatically:
2008/07/30 The fixed entry
Expenses:Food $20.00
Assets:Checking $-20.00 = $30.00
Equity:Adjustments
# Conclusion
This simple feature has all the utility of @check, plus auto-balancing
to match known target balances, plus the ability to guarantee that an
account which uses only one commodity does contain only that commodity.
This feature has been checked in to 2.6.1b. It slows down textual
parsing slightly, does not affect loading from a binary cache.
John
Simon Michael
armchair. But while elegant, doesn't it make things more opaque to
someone trying to read/debug their financial records ?
John Wiegley
How do you mean?
John
Simon Michael
reconciling and reading back looking for an error in my recorded
entries, it seems these = transactions will require me to spend
brainpower to figure out what's going on. Just a hunch.
John Wiegley
Well, I happen to agree very much. Whenever you have implicit things
going on, you need to be 10x more careful than normal lest you start
relying on what you cannot see. Automation can be very dangerous when
it comes to finances, I think.
However, in this case you are still being explicit. The amount after
the "=" forces the account's total balance to be _exactly_ that amount
at that point, triggering an error if it fails. You should avoid
using the "no-amount" variant of this syntax except for establishing
an initial balance, or for adjusting something like a cash balance
(which is something I do all the time).
When used in conjunction with an amount, it acts as verification only,
so that you can make sure that a known balance remains such for all
time.
John