From 6bab2e2b4b99ea42bbc45d0b79c0603aa3eb9d42 Mon Sep 17 00:00:00 2001 From: Jordan Orelli Date: Sat, 2 May 2015 19:27:46 -0400 Subject: [PATCH] add some readme info --- README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 77 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 35431ac..3841839 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ This is a toy configuration language. If you want to know why, see the [WHY](WHY.md) doc. -# stability +# Instability This isn't even remotely stable. Don't use this in an actual project, I promise you I will break this. @@ -17,16 +17,16 @@ format in Go projects. The syntax is fairly similar, with a few changes: - support for complex numbers. The only reason I included this is that it's 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. Variables whose name starts - with a period are hidden; they are only valid in the context of the moon - document in which they appear, and they are not accessible to the host - program. + 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. @@ -77,23 +77,38 @@ Moon defines the following types: These are strings: ``` -"this one" -'that one' +this is a bare string +"this is a quoted string" +'this is also a quoted string' + +inside of a bare string, "quotes" don't need to be escaped +but semicolons \;, colons \:, parens \( and \), brackets \[ and \] and braces \{ \} need to be escaped. ``` - You can use single or double quotes. Escape quotes with a backslash. + You can use single or double quotes. Escape quotes with a backslash. Quoted + strings may contain newlines and special characters. + + The following characters are special characters: `:`, `;`, `[`, `]`, `#`, + `{`, and `}`. The colon is used to separate a key from a value. The + semicolon is used to terminate a bare string. A newline will also terminate + a bare string. A close bracket must be a special string in order to support + a bare string being the last element of a list, without requiring that you + add a semicolon after it. An open bracket doesn't need to be a special + character, but I made it a special character to be symetrical with the close + bracket. The same logic applies for braces. + - objects: or maybe you call them hashes, objects, or associative arrays. Moon calls them objects, but you'd never know it because it's actually the `map[string]interface{}` type in Go, which is effectively the same thing. - Unlike json objects, and unlike strings, the keys in objects are not quoted. - Also there are no commas between the values but I'm not sure I like this yet, - so it might change. These are some objects: + Keys are bare strings, but object keys may not contain spaces. + + These are some objects: ``` {name: "jordan" age: 28} { one: 1 - two: "two is also a number" + two: two is also a number pi: 3.14 } ``` @@ -105,11 +120,60 @@ Moon defines the following types: ``` [1 2 3] [ - "one" + one 2 3.14 ] + +# this is a list of three elements +[moe; larry; curly] + +# this is a list of one element +[moe larry curl] +``` + +- variables: a variable is indicated with a `@` character. A variable may + refer to any key that has already been defined in the current moon document. + Here is an example of how you would use a variable: + +``` +original_value: this is the original value, which is a string +duplicate_value: @original_value ``` + If the name of a key begins with an `@` character, it is a private key. A + private key may be referenced in the rest of the moon document, but it is not + available anywhere outside of the moon document parser. This is useful for + the composition of larger, nested values, without polluting the document's + root namespace. Here is an example of a private key: +``` +@my_private_key: a great value +my_public_key: @my_private_key +``` + + This isn't particularly useful for simple values, but consider the following: + +``` +@prod: { + label: production + hostname: prod.example.com + port: 9000 + user: prod-user +} + +@dev: { + label: development + hostname: dev.example.com + port: 9200 + user: dev-user +} + +servers: [@prod @dev] +``` + The only key in the root namespace of the document is `servers`; the + individual server configs are considered only a part of the document. Since + we know that these values are private to the document itself, we know we are + free to modify them as we see fit, without affecting how the host program + sees the moon document.