You should track your finances in TOML

No, really! Let me explain.

I am quite particular with my finances. Having a proper accounting system helps me keep control of my spendings and what I am saving. Being a pretty nerdy guy, I quickly gravitated towards the plain text accounting movement, with which I ensure that I can control my data, switch systems if I want and do custom scripting around my ledger. I won鈥檛 delve into the details here, but the website is a great source of information, and I recommend reading through the Newcomer FAQ if you want an introduction to the concept.

The most popular tools for plain text accounting today are Beancount, Ledger and hledger. They are all fantastic tools, using similarly inspired DSLs that are pretty easy to learn. However, their syntax deviate in subtle ways. Here is an example entry written in Ledger first and then Beancount:

2023/11/06 My local grocery store | Grocery shopping
  Assets:ExampleBank:Checkings  $-20
  Expenses:Food:Groceries        $20
2023-11-06 * "My local grocery store" "Grocery shopping"
  Assets:ExampleBank:Checkings  -20 USD
  Expenses:Food:Groceries        20 USD

They are not compatible with eachother, and converting between the two is non-trivial. There are countless examples of features (transaction flags, prices, capitalization conventions, metadata, etc.) that are non-interoperable like this.

Now say you want to write some scripts for processing your journal. This means you鈥檒l have to scour the internet for a parser supported by your language of choice, or write one on your own. Let me tell you, they are not abundant, and good luck finding a non-official library that is regularly updated. You might get forced to use a language you would not choose yourself, just to get some simple processing done.

Many of the reasons these tools have opted for a DSL, is to keep the amount of necessary typing to a minimum鈥攁n admirable goal which they achieve quite well in my opinion. However, most users use automated scripts, data-entry tools or at the least some editor completion to insert their data. Why, then, can鈥檛 we just use a standard plain text data serialization language?

Advantages of using a proper data serialization format

The advantages are obvious, given my gripes listed above; almost all of them are solved:


With these ideas in mind, why am I saying that TOML specifically is the solution? Well, the homepage says it all:

A config file format for humans.

The whole ethos around plain text accounting is that it can be read in it鈥檚 raw form and edited by hand if so desired. These goals are at the core of TOMLs design. Here is the equivalent transaction I showed above, written in my proposed TOML ledger specification:

date = 2023-11-06
description = "Grocery shopping"
payee = "My local grocery store"
postings = [
  { account = "Assets:ExampleBank:Checkings", amount = -20, currency = "USD" }
  { account = "Expenses:Food:Groceries", amount = 20, currency = "USD" }

Definitely more verbose, yes, but still reasonably short and totally legible (and perhaps even easier to understand without knowing the syntax beforehand.) Note also that TOML has a datetime type, which is perfectly suited for this use case.

Now this example leaves a lot to be desired. Evidently, writing out the currency in this way for each posting is not ideal, but could be solved by allowing the user to set a default currency. Accounts also borrow the colon-separated syntax from ledger, but I think this is also something that could be improved upon. There are also a lot of crucial details I have glossed over here鈥攆or example currency prices, posting metadata, balance assertions and more鈥攂ut I would say these are all pretty low-hanging fruit.

If you like the concept and have thoughts or ideas that you would like to share, please send an email to my public inbox, and I鈥檒l be happy to discuss! I鈥檓 doing some testing in a CLI called mynt, which initially is for personal use, but feel free to have a look at it for reference, contribute a patch if you see an improvement that can be made or even try it out yourself.

Here are some posts from sites I follow

Magit opening on a random window

If everything goes south and I find a better replacement for GNU Emacs, Magit1 would definitely be the hardest to replace. It is deeply ingrained in my daily workflow and I can鈥檛 imagine using Git with anything else. Having said that, I always hated how it鈥

via glorifiedgluer November 14, 2023

Can I be on your podcast?

I am working on rousing the Hare community to get the word out about our work. I have drafted the Hare evangelism guidelines to this effect, which summarizes how we want to see our community bringing Hare to more people. We鈥檇 like to spread the word in a way 鈥

via Drew DeVault's blog November 9, 2023

New Features Roll Call: Fall 2023

You should be able to communicate without worrying that every gossip tidbit, meme, or joke you share and who you share it with will get churned up into fodder for targeted ads or used to train an AI model. You also shouldn鈥檛 have to strip 鈥

via Signal Blog November 8, 2023