Update spec

Author: antonmedv

spec/v0.1.md

@@ -0,0 +1,306 @@
+MAML v0.1
+=========
+
+Minimal Abstract Markup Language
+
+By Medvedev Anton.
+
+
+Objectives
+----------
+
+1. MAML aims to be a minimal configuration format.
+2. MAML should be easily readable by humans.
+3. MAML should be easily parsed by machines.
+
+
+Spec
+----
+
+* MAML is case-sensitive.
+* A MAML file must be a valid UTF-8 encoded Unicode document.
+* Whitespace means a space (0x20) or a tab (0x09).
+* Newline means LF (0x0A) or CRLF (0x0D 0x0A).
+
+Whitespaces and newlines are allowed to separate values and structural
+characters.
+
+
+Comment
+-------
+
+A hash symbol marks the rest of the line as a comment, except when inside a
+string.
+
+```maml
+# Comment before the object
+{
+  foo: "value" # Inline comment
+  bar: "# This is not a comment"
+}
+```
+
+Control characters other than tab (U+0000 to U+0008, U+000A to U+001F, U+007F)
+are not permitted in comments.
+
+
+Values
+------
+
+A MAML value is an object, array, string, multiline string, integer, float,
+boolean, or null.
+
+
+Array
+-----
+
+An array structure is represented as `[` `]` square brackets surrounding zero
+or more values. Values are separated by `,` comma or newlines. There is no
+requirement that the values in an array be of the same type.
+
+```maml
+[
+  "red"
+  "yellow"
+  "green"
+]
+```
+
+Commas are optional. Trailing comma is allowed.
+
+```maml
+[ "red", "yellow", "green", ]
+```
+
+
+Objects
+-------
+
+An object is an **ordered** set of key/value pairs. An object begins with `{`
+left brace and ends with `}` right brace. Each key is followed by `:` colon
+and the key/value pairs are separated by `,` comma or newlines.
+
+```maml
+{
+  key: "value"
+  "quotted key": "value"
+}    
+```
+
+Commas are optional. Trailing comma is allowed.
+
+```maml
+{
+  key: "value",
+  "quotted key": "value",
+}
+```
+
+Duplicate keys are **not allowed** within an object.
+
+
+Keys
+----
+
+A key may be either an identifier or a quoted string.
+
+**Identifier keys** may only contain `A-Z` `a-z` letters, `0-9` digits, `_`
+underscores, and `-` hyphens.
+
+Identifier keys are allowed to be composed of only digits, (for example,
+`1234`), but are always interpreted as strings.
+
+**Quoted string keys** follow the exact same rules as strings and allow
+you to use a much broader set of key names.
+
+An identifier key must be non-empty, but an empty quoted string key is allowed.
+
+
+String
+------
+
+**Strings** are surrounded by `"` quotation marks. Any Unicode character
+may be used except those that must be escaped: quotation mark, backslash, and
+the control characters other than tab (U+0000 to U+0008, U+000A to U+001F,
+U+007F).
+
+```maml
+"String with a \"nested\" string, \t tab, 😁 emoji, and \u0022 sequence"
+```
+
+For convenience, some popular characters have a compact escape sequence.
+
+```
+\b         - backspace       (U+0008)
+\t         - tab             (U+0009)
+\n         - linefeed        (U+000A)
+\f         - form feed       (U+000C)
+\r         - carriage return (U+000D)
+\"         - quote           (U+0022)
+\\         - backslash       (U+005C)
+```
+
+A Unicode character may be escaped with the `\uXXXX` form.
+The escape codes must be valid Unicode [scalar
+values](https://unicode.org/glossary/#unicode_scalar_value).
+
+All other escape sequences not listed above are reserved; if they are used,
+MAML should produce an error. All strings must contain only valid UTF-8
+characters.
+
+
+Multiline String
+----------------
+
+**Multiline Strings** are surrounded by `"""` three quotes on each
+side and allow newlines. There is no escaping. A newline immediately following
+the opening delimiter is ignored. All other content between the delimiters is
+interpreted as-is without modification.
+
+```maml
+"""
+The quick brown
+fox jumps over
+the lazy dog.
+"""
+}
+```
+
+In the previous example, a string ends with a newline at the end.
+
+```maml
+"The quick brown\nfox jumps over\nthe lazy dog.\n"
+```
+
+To avoid the last newline, place the closing delimiter on the same line.
+
+```maml
+"""
+The quick brown
+fox jumps over
+the lazy dog."""
+```
+
+You can write one or two quotes anywhere within a multiline string,
+but sequences of three or more quotes are not permitted.
+
+```maml
+"""
+Maximum of two "" quotes allowed inside.
+"""
+```
+
+All escape sequences are preserved as is.
+
+```maml
+"""
+There is no escaping, so \n, \u0022, etc.,
+are interpreted as-is without modification.
+"""
+```
+
+Multiline string may also be written in a single line.
+
+```maml
+"""A multiline string and with "quotas"."""
+```
+
+All multiline strings must contain only valid UTF-8 characters.
+
+
+Integer
+-------
+
+Integers are whole numbers. Negative numbers are prefixed with a minus sign.
+Leading zeros are not allowed. Plus sign is not allowed.
+
+```maml
+{
+  int1: 42
+  int2: -100
+}
+```
+
+Arbitrary 64-bit signed integers (from −2^63 to 2^63−1) should be accepted and
+handled losslessly. If an integer cannot be represented losslessly, an error
+must be thrown.
+
+
+Float
+-----
+
+Floats should be implemented as IEEE 754 binary64 values.
+
+A float consists of an integer part (which follows the same rules as integer
+values) followed by a fractional part and/or an exponent part. If both a
+fractional part and an exponent part are present, the fractional part must
+precede the exponent part.
+
+```maml
+[
+  # fractional
+  1.0
+  3.1415
+  -0.01
+  
+  # exponent
+  5e+22
+  1e06
+  -2E-2
+  
+  # both
+  6.626e-34
+]
+```
+
+A fractional part is a decimal point followed by one or more digits.
+
+An exponent part is an E (upper or lower case) followed by an integer part
+(which follows the same rules as integer values but may include leading
+zeros).
+
+The decimal point, if used, must be surrounded by at least one digit on each
+side.
+
+
+Boolean
+-------
+
+Booleans are `true` and `false`. Always lowercase.
+
+```maml
+[ true, false ]
+```
+
+
+Null
+----
+
+Represents the lack of a value. An object with some key and a null value is
+valid and different from not having that key in the object. Always lowercase.
+
+```maml
+null
+```
+
+
+Filename Extension
+------------------
+
+MAML files should use the extension `.maml`.
+
+
+MIME Type
+---------
+
+When transferring MAML files over the internet, the appropriate MIME type is
+`application/maml`.
+
+
+ABNF Grammar
+------------
+
+A formal description of MAML's syntax in ABNF format
+([RFC 5234](https://www.ietf.org/rfc/rfc5234.txt)).
+
+<<< @/maml.abnf