Getting started

Introduction

TOML is a minimal config file format that maps unambiguously to a hash table. This sheet covers the syntax used in everyday config files.

Minimal document

title = "TOML example"
owner = "Tom"
dob = 1979-05-27T07:32:00Z

Top-level key/value pairs come first; tables follow under headers.

See: Key/value pair

Comments

# comment
key = "value"  # trailing comment
another = "# not a comment"

See: Comment

Keys

Bare keys

key = "value"
bare_key = "value"
bare-key = "value"
1234 = "value"

Bare keys allow A-Za-z0-9_-; digits alone are still strings.

See: Keys

Quoted keys

"127.0.0.1" = "value"
"character encoding" = "value"
'key2' = "value"

Quote keys with spaces or Unicode; basic and literal string rules apply.

See: Keys

Dotted keys

name = "Orange"
physical.color = "orange"
physical.shape = "round"

Dots build nested tables. Finish one prefix before starting another.

See: Keys

Strings

Basic strings

quote = "She said \"hi\""
tabbed = "Name\tJos\u00E9"
esc = "\e"
cafe = "caf\xE9"

The \e and \xHH escapes are 1.1.0 additions.

See: String

Literal strings

winpath = 'C:\Users\node'
regex = '<\i\c*\s*>'

Literal strings use ' and never process escapes.

See: String

Multi-line basic strings

str1 = """
Roses are red
Violets are blue"""

A newline right after """ is trimmed; a trailing \ joins lines.

See: String

Multi-line literal strings

regex2 = '''\d{2} apples'''
lines = '''
The first newline is
trimmed in literal strings.
'''

See: String

Numbers and booleans

Integers

int1 = +99
int2 = 42
int3 = -17
int5 = 1_000
hex1 = 0xDEADBEEF
oct1 = 0o755
bin1 = 0b11010110

Underscores separate digits; 0x, 0o, and 0b set the base.

See: Integer

Floats

flt1 = 3.1415
flt4 = 5e+22
flt7 = 6.626e-34
sf1 = inf
sf2 = +inf
sf4 = nan

A point or exponent makes a float; inf and nan are lowercase.

See: Float

Booleans

bool1 = true
bool2 = false

See: Boolean

Dates and times

Offset date-time

odt1 = 1979-05-27T07:32:00Z
odt2 = 1979-05-27T00:32:00-07:00
now = 1979-05-27T07:32Z

RFC 3339 with an offset; T may be a space. Omitting seconds, as in now, is a 1.1.0 addition.

See: Offset Date-Time

Local date-time

ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T07:32:00.5

No offset means wall-clock time, not an instant.

See: Local Date-Time

Local date and time

ld1 = 1979-05-27
lt1 = 07:32:00
lt2 = 00:32:00.5

See: Local date, Local time

Arrays

Arrays

integers = [ 1, 2, 3 ]
colors = [ "red", "blue" ]
nested = [ [ 1, 2 ], [3, 4, 5] ]

See: Array

Mixed types

numbers = [ 0.1, 1, 2, 5 ]
contributors = [
  "Foo Bar <foo@example.com>",
  {name="Baz",email="baz@x.io"}
]

See: Array

Multi-line arrays

integers = [
  1,
  2, # trailing comma allowed
]

See: Array

Tables

Standard tables

[table-1]
key1 = "some string"
key2 = 123

[table-2]
key1 = "another string"
key2 = 456

A [table] header applies until the next header or end of file.

See: Table

Nested tables

[dog."tater.man"]
type.name = "pug"

Dotted headers create nested tables; parent tables are implicit.

See: Table

Arrays of tables

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

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

[[table]] appends a table to an array of tables.

See: Array of Tables

Inline tables

Inline tables

name = { first = "Tom", last = "Preston-Werner" }
point = {x=1}

Inline tables are self-contained; keys cannot be added outside braces.

See: Inline Table

Nested inline tables

contact = {
  personal = {
    name = "Donald Duck",
    email = "donald@duckburg.com",
  },
}

Multi-line inline tables and their trailing commas are 1.1.0 additions.

See: Inline Table

0 Comments for this cheatsheet. Write yours!