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.
- TOML v1.1.0 specification (toml.io)
- TOML repository (github.com)
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!