I wrote in budgeting tools that I was taking a look at Plain Text Accounting and in particular, hledger. My Jury's still out on the tools, but in the time I've been looking at them I've come across a couple of foot-guns I thought it was worth writing down.
hledger's ledger format is derived from that of its predecessor
ledger, and so some of the problems might be inherited. 1. significant white space delimiters The basic syntax for a transaction looks like this
There's some significant white space delimiters in play. The most subtle is what separates the account names from the values: it is two or more spaces. A single space, and the value is treated as part of the account name. For some reason I hit this frequently with trying to encode opening balances: the account name used as the source of the initial balances is something not otherwise generally referred to again (something like
2020-03-15 client payment assets:checking $ 2000 income:consulting $-2000
equity:opening balances) and the transaction amount is inferred where possible, so I ended up with a bunch of accounts named
equity:opening balances 100and similar. 2. flexible decimal delimiter The value of transactions can be interspersed with commas and periods to make it more readable: e.g. $2000 could be written as $2,000. Different locales have different conventions here: It seems some(/most/all?) of Europe use periods to separate out the units and a comma to delimit the fractional part, whereas the US and the UK do the opposite. There is no built-in association between the currency symbol you are using and the period/comma convention: it's quite possible to accidentally write a number which is interpreted differently to how you intended, and it doesn't matter if you are using $ or etc. 3. new syntax has unexpected results in old versions Finally, my favourite.
hledgerhas a notion of rules that can be used to match transactions when importing from CSV. The format looks like this:
By default, multiple rules in sequence like above are OR'd: any of them can match. The
if (match rule) & (another rule) account1 some:account:from account2 some:account:to
&prefix switches the behaviour to AND. But,
&is a relatively new addition: it's not supported in 1.18.1, the version in Debian stable, which upstream released in June 2020. In prior versions the
&prefix is not a syntax error, or at least, not one that's reported: it's silently ignored; meaning, the line with the
&does nothing, and any of the other rules in the set will match. This is easy to miss, and means imports could be incorrectly posted.