documentation

master
Jordan Orelli 10 years ago
parent 8849bd0927
commit 76bb79412f

@ -1,42 +1,27 @@
This is a toy configuration language. If you want to know why, see the [WHY](WHY.md) doc. # Moon
Moon is a human-readable data exchange format designed to be used as a
configuration language in software projects. This projects contains a
description of Moon's grammar and a reference implementation of a moon
interpreter written in Go. For some history as to why this project was seen as
worthwhile, please see the [WHY](WHY.md) doc. For a description of Moon's
design goals (and non-goals), please see the [GOALS](GOALS.md) doc.
# Instability # Instability
This isn't even remotely stable. Don't use this in an actual project, I This project is not yet stable. Things may change. It's not recommended that
promise you I will break this. you use this in any type of production system, since I can't guarantee future
compatibility at this time.
# What it is
# Design
Moon is a configuration language intended to replace JSON as a configuration
format in Go projects. The syntax is fairly similar, with a few changes: A Moon file is a human-readable description of an unordered collection of
key-value pairs. Parsing a Moon document always yields either a Moon Document
- instead of having some hand-wavy "number" thing without ever specifying the or an error.
valid ranges or anything like that, there are two number types: int and
float64. Int means int32 on 32bit systems and int64 on 64bit systems. Maybe The top level of a Moon document contains a series of key-value pairs separated with a colon:
I'll go back on that because it sounds really dumb when I type it out.
- support for complex numbers. The only reason I included this is that it's ![Assignment Diagram](grammar/diagram/Assign.png)
included in the text/template package in the standard library and I stole the
number-parsing code from that library.
- bare strings. Support here is somewhat up in the air. Inside of bare
strings, the characters [, ], ;, :, {, and } must be escaped, because each of
those can terminate a bare string.
- comments. There are no comments in JSON and that's incredibly annoying.
Moon has them.
- variables. In moon, you can make a reference to a value that was already
defined.
- hidden variables. This sounds really dumb but it quickly became apparent
that if you're using variables to compose something, those variables end up
polluting the namespace of the moon document.
- a command-line tool. I'm sure these exist for json but there's no official
"this is the tool, that one isn't" decree.
- something kinda like xpath that lets you select elements in a document.
# How it works
json and similar formats parse text and render some kind of parse tree. We do
the same thing in moon, but then we walk the tree and evaluate it, which is why
variables are a thing. It's effectively just enough of a dynamic language
interpreter for variables to work.
# Types # Types

@ -43,10 +43,10 @@ writing the config files themselves.
Historically, I have always used json as the configuration format for Go 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 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 library, so it doesn't add any dependencies to your project. For small
understand it, and those that don't pick it up very quickly. It's a nearly configurations, json is very easy for a human to write. It's a nearly ideal
ideal format, inasmuch as it doesn't litter itself with spurious information, format, inasmuch as it doesn't litter itself with spurious information, it's
it's relatively compact, and it's a familiar set of non-word characters that 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 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 the standard library is extremely easy to use. As far as programming the host
application, json works very well. application, json works very well.
@ -72,15 +72,8 @@ It also seems to drive my colleagues in ops into an absolute rage.
#### Why not YAML? #### Why not YAML?
Every time I use YAML I accidentally break it. It's incredibly brittle. I Semantic whitespace makes it difficult to generate YAML from within a template
actually do buy the argument that semantic whitespace is great for humans. I language, such as ERB. Generating configuration files from templates or from a
programmed a significant amount of Python and loved every minute of it. parent application is a common strategy when using configuration management
systems, such as [Chef](https://www.chef.io/chef/).
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!

Loading…
Cancel
Save