For the next version of Buckaroo, we wanted to make improvements to the manifest format. Old versions of Buckaroo used JSON for the manifest and lock-files. This choice was not made very consciously, but at the time it seemed reasonable:

Yarn and NPM (arguably the most successful language package managers) both use JSON.

There is a JSON parser for literally every language (and usually more than one).

Everyone is familiar with JSON.

Over time, we've come to regret this decision:

JSON is tedious to edit by hand, since objects must be closed with curly braces.

JSON does not support comments.

Large JSON files can be difficult to read.

So we started looking for an alternative.

Amoungst newer package managers (Cargo, Dep), there is a clear winner: TOML. Tom's Obvious, Minimal Language (yes, the name is a tad egotistical)...

... aims to be a minimal configuration file format that's easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.

Already we have found it more convenient when tweaking packages over on buckaroo-pm. Often the TOML is a bit longer, but it's so much easier to read and edit!

Here's a side-by-side comparison:

{ "name" : "satori" , "dependencies" : { "libuv/libuv" : "1.11.0" , "google/gtest" : "1.8.0" , "nodejs/http-parser" : "2.7.1" , "madler/zlib" : "1.2.11" , "loopperfect/neither" : "0.4.0" , "loopperfect/r3" : "2.0.0" } }

And the TOML:

targets = [ "//:satori" ] [[dependency]] package = "github.com/buckaroo-pm/google-googletest" version = "branch=master" private = true [[dependency]] package = "github.com/buckaroo-pm/libuv" version = "branch=v1.x" [[dependency]] package = "github.com/buckaroo-pm/madler-zlib" version = "branch=master" [[dependency]] package = "github.com/buckaroo-pm/nodejs-http-parser" version = "branch=master" [[dependency]] package = "github.com/loopperfect/neither" version = "branch=master" [[dependency]] package = "github.com/loopperfect/r3" version = "branch=master"

But the biggest improvement is when fixing a Git merge. Unlike JSON, each line of TOML is largely self-contained. Without having to worry about trailing commas or closing braces, Git will get things right far more often. This is a huge relief when updating lock-files.

TOML files are use in Buckaroo v2 upwards. Let us know what you think! 💖