# You should track your finances in TOML

<!-- atom-id: 4738FCCA-E1AE-42AE-9F64-D519DBC1CCE0 -->
<time datetime="2023-11-13T13:00:00+01:00">

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't delve into the details here, but the
[plaintextaccounting.org] 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:

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

```beancount
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'll 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---an 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't 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:

- Interoperability: It is trivial to convert from one data format to another.
  Just look at the [serde] framework for Rust, or the countless number of
  [conversion tools][transform.tools] available online.
- Language support: You can expect to find a high-quality maintaned library for
  parsing any of the big data formats in most languages. These often also
  deserialize into native data-structures, which should be easier to handle when
  scripting.
- Standard: This hooks a bit into interoperability, but the key here is that you
  can expect your data to be easily used by or ported to any tool or service you
  want to use in the future. Not only that, but having a simple map to e.g. JSON
  makes the path to a web-accessible API quite clear.

## Why TOML?

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

> A config file format for humans.

The whole ethos around plain text accounting is that it can be read in it's 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:

```toml
[[transaction]]
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](https://toml.io/en/v1.0.0#offset-date-time)
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---for example
currency prices, posting metadata, balance assertions and more---but 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'll be happy to discuss! I'm
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.

[plaintextaccounting.org]: https://plaintextaccounting.org
[Newcomer FAQ]: https://github.com/plaintextaccounting/plaintextaccounting/wiki/Newcomer-FAQ
[Beancount]: https://github.com/beancount/
[Ledger]: https://ledger-cli.org/
[hledger]: https://hledger.org/
[serde]: https://serde.rs/
[transform.tools]: https://transform.tools/
[TOML]: https://toml.io/en/
[public inbox]: https://lists.sr.ht/~kmaasrud/inbox
[mynt]: https://git.sr.ht/~kmaasrud/mynt