timerring/toml-simple-docs.md

## toml-simple-docs.md

      
    Raw
  

              toml-simple-docs.md
            
          
    Toml simple docs


Tom's Obvious, Minimal Language. See details on toml.io.

Specification


TOML is case-sensitive.
# is the comment symbol.
key = "value" is the key-value pair.

Keys

bare_key = "value"
"quoted key" = "value" # also can be literal keys
Dotted keys

physical.shape = "round"
site."google.com" = true
equals to the JSON
{
  "physical": { "shape": "round" },
  "site": { "google.com": true }
}

You can not defining a key multiple times. (The bare key and quoted key are equivalent)
If a key is not defined, you will create the key and corresponding value.
You can not change the type of a key, such as fruit.apple = "red" then fruit = 1 is invalid.

String

string = "I'm a string. \"You can quote me\". Name\tJosé\nLocation\tSF."
str1 = """
Roses are red
Violets are blue"""
which is equivalent to:
# On a Unix system, the above multi-line string will most likely be the same as:
str2 = "Roses are red\nViolets are blue"
# On a Windows system, it will most likely be equivalent to:
str3 = "Roses are red\r\nViolets are blue"
# Those are surrounded by single quotes must appear on a single line. 
# You can not write a single quote inside it.
winpath  = 'C:\Users\nodejs\templates'
# Multi-line literal strings are surrounded by triple quotes. 
# And there is no escape sequence.
regex2 = '''
I [dw]on't need \d{2}
apples
'''
The 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)

Integer

int4 = -17
# use underscores to enhance readability
int5 = 1_000
# hexadecimal with prefix `0x`
hex1 = 0xDEADBEEF
# octal with prefix `0o`
oct1 = 0o01234567
# binary with prefix `0b`
bin1 = 0b11010110
Float

flt7 = 6.626e-34
# infinity
sf1 = inf  # positive infinity which is equivalent to +inf
sf3 = -inf # negative infinity
sf4 = nan  # actual sNaN/qNaN encoding is implementation-specific
Boolean

bool1 = true # lowercase
bool2 = false
Array

nested_mixed_array = [ [ 1, 2 ], ["a", "b", "c"] ]
# Mixed-type arrays are allowed
numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]
contributors = [
  "Foo Bar <foo@example.com>",
  { name = "Baz Qux", email = "bazqux@example.com", url = "https://example.com/bazqux" }
]
# Arrays can span multiple lines.
integers3 = [
  1,
  2, # this is ok
]
Table


Tables (also known as hash tables or dictionaries) are collections of key/value pairs.


You cannot define a table more than once.


# DON'T DO THIS
[fruit]
apple = "red"
[fruit.apple]
texture = "smooth"
Naming rules for tables are the same as for keys
[dog."tater.man"]
type.name = "pug"
You don't need to specify all the super-tables if you don't want to.
[x.y.z.w]
[x] # defining a super-table afterward is ok
Unlike other tables, the root table is nameless and cannot be relocated.
# Top-level table begins.
name = "Fido"
breed = "pug"

# Top-level table ends.
[owner]
name = "Regina Dogman"
You can create sub-tables but you cannot redefine the table which has already been created.
[fruit]
apple.color = "red"
apple.taste.sweet = true

# [fruit.apple]  # INVALID which has already been created.
# [fruit.apple.taste]  # INVALID same with above.

[fruit.apple.texture]  # you can add sub-tables
smooth = true
Inline Table


The terminating comma is not permitted.
No newline is allowed between braces.
Inline tables are fully self-contained and define all keys and sub-tables within them. Keys and sub-tables cannot be added outside the braces. Also cannot redefine.

animal = { type.name = "pug" }
# which is equivalent to 
# [animal]
# type.name = "pug"
Array of Tables


The first instance of that header defines the array and its first table element, and each subsequent instance creates and defines a new table element in that array.
The tables are inserted into the array in the order encountered.

[[products]]
name = "Hammer"
sku = 738594937

[[products]]  # empty table within the array

[[products]]
name = "Nail"
sku = 284758393

color = "gray"
Which is equivalent in json
{
  "products": [
    { "name": "Hammer", "sku": 738594937 },
    { },
    { "name": "Nail", "sku": 284758393, "color": "gray" }
  ]
}
Any reference to an array of tables points to the most recently defined table element of the array.
This allows you to define sub-tables, and even sub-arrays of tables, inside the most recent table.
[[fruits]]
name = "apple"

[fruits.physical]  # sub table
color = "red"
shape = "round"

[[fruits.varieties]]  # nested array of tables
name = "red delicious"

[[fruits.varieties]]
name = "granny smith"

[[fruits]]
name = "banana"

[[fruits.varieties]]
name = "plantain"
{
  "fruits": [
    {
      "name": "apple",
      "physical": {
        "color": "red",
        "shape": "round"
      },
      "varieties": [
        { "name": "red delicious" },
        { "name": "granny smith" }
      ]
    },
    {
      "name": "banana",
      "varieties": [
        { "name": "plantain" }
      ]
    }
  ]
}
Important
Don't remix the subtable and the array of tables.

[[fruit]]
name = "apple"

[[fruit]]
name = "banana"

[fruits.physical] # INVALID
color = "red"
shape = "round"

# Because the parse do not know which one is its parent. And which fruit should be appended the physical property.
No results found