diff --git a/README.md b/README.md new file mode 100644 index 0000000..50b0e79 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +This is a toy configuration language. If you want to know why, see the [WHY](WHY.md) doc. diff --git a/WHY.md b/WHY.md new file mode 100644 index 0000000..d40bcf9 --- /dev/null +++ b/WHY.md @@ -0,0 +1,86 @@ +### Why? + +Quite often in the course of writing Go programs I've found myself in need of a +format to describe the application's configuration. The only formats in the Go +standard library are json and xml. + +#### Why not XML? + +xml is fairly verbose and doesn't map to data structures particularly well. +There are many ways of expressing the same thing. E.g., what's the difference +between this: + +``` + + jordan + orelli + +``` + +and this: ``? + +There are also spurious type indicators. What do you do if you just want an +array of integers? + +``` + + 1 + 3 + 8 + +``` + +In reality, all I want for that is something like `sizes: [1 3 8]`. + +On top of the combination ambiguity and verbosity of the language itself, the +xml package in the Go standard library is cumbersome to work with. The few +times I've tried it, it didn't strike me as being a particularly pleasurable +programming model. It's not particularly well-suited to the task of writing +the host application, and it's not particularly well-suited to the task of +writing the config files themselves. + +#### Why not JSON? + +Historically, I have always used json as the configuration format for Go +projects. I've found this to be the best option. It's in the standard +library, so it doesn't add any dependencies to your project. Everyone can +understand it, and those that don't pick it up very quickly. It's a nearly +ideal format, inasmuch as it doesn't litter itself with spurious information, +it's relatively compact, and it's a familiar set of non-word characters that +everyone can grok. The parsing API is also quite nice, and the json package in +the standard library is extremely easy to use. As far as programming the host +application, json works very well. + +But over time, using json gets worse and worse. When it comes to authoring +json config files, things are a little less rosey. At first it seems fine, +when your configs are small and your projects are simple. Over time, as the +projects get more complex and you require more configuration, the files become +challenging to read and edit. It's exceptionally easy to introduce syntax +errors into json documents. Object keys seem to require double-quotes for no +reason at all. There are no comments. You're more or less pidgeonholed into +making your whole configuration file one object, because if you don't, you wind +up complicating the parsing API for the host application, and it becomes +difficult to program, which was one of the best features of using json to begin +with. Then there are the weird things, like the fact that re-declaring a key +in an object just overwrites the previous value +([ex](http://play.golang.org/p/ky4F9UmM1Z)), which fundamentally makes no +sense because objects are supposed to be order-independent but in reality +they're not. As far as performing automated validations, json doesn't give you +much help. + +It also seems to drive my colleagues in ops into an absolute rage. + +#### Why not YAML? + +Every time I use YAML I accidentally break it. It's incredibly brittle. I +actually do buy the argument that semantic whitespace is great for humans. I +programmed a significant amount of Python and loved every minute of it. + +But where it really breaks down is that semantic whitespace is an absolute +showstopper when it comes to generating a configuration file from a template +system, which is a common technique in +[Chef](http://en.wikipedia.org/wiki/Chef_%28software%29), the configuration +management tool we use [where I work](https://www.etsy.com/). Beyond being +impossible to template out, it's much, much too complicated. The YAML spec is +nearly as large as the specification for Go itself! +