v1.0.0-rc.3

TOML

[Tom's Obvious Minimal Language]

A config file format
for humans.

# This is a TOML document

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [ 8001, 8001, 8002 ]
data = [ ["delta", "phi"], [3.14] ]
temp_targets = { cpu = 79.5, case = 72.0 }

[servers]

[servers.alpha]
ip = "10.0.0.1"
role = "frontend"

[servers.beta]
ip = "10.0.0.2"
role = "backend"
TOML prioritizes humans

TOML aims to be a minimal configuration file format that:

  • is easy to read due to obvious semantics
  • maps unambiguously to a hash table
  • is easy to parse into data structures in a wide variety of languages
TOML has useful native types
  • Key/Value Pairs
  • Arrays
  • Tables
  • Inline tables
  • Arrays of tables
  • Integers & Floats
  • Booleans
  • Dates & Times, with optional offsets
TOML is widely supported

TOML already has implementations in most of the most popular programming languages in use today: C, C#, C++, Clojure, Dart, Elixir, Erlang, Go, Haskell, Java, Javascript, Lua, Objective-C, Perl, PHP, Python, Ruby, Swift, Scala... and plenty more.

A Quick Tour of TOML

Comments

TOML thinks all config files should support comments.

# This is a TOML comment

# This is a multiline
# TOML comment

Powerful Strings

There are four ways to express strings: basic, multi-line basic, literal, and multi-line literal. Basic strings are surrounded by quotation marks:

str1 = "I'm a string."
str2 = "You can \"quote\" me."
str3 = "Name\tJos\u00E9\nLoc\tSF."

Multi-line basic strings Multi-line basic strings are surrounded by three quotation marks on each side and allow newlines. Include a line ending backslash to automatically trim whitespace preceeding any non-whitespace characters:

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

str2 = """\
  The quick brown \
  fox jumps over \
  the lazy dog.\
  """

str2 becomes "The quick brown fox jumps over the lazy dog." (a single sentence with no line breaks).

Literal strings are surrounded by single quotes. No escaping is performed so what you see is what you get:

path = 'C:\Users\nodejs\templates'
path2 = '\\User\admin$\system32'
quoted = 'Tom "Dubs" Preston-Werner'
regex = '<\i\c*\s*>'

Since there is no escaping, there is no way to write a single quote inside a literal string enclosed by single quotes. That's where multi-line literal strings come in:

re = '''\d{2} apps is t[wo]o many'''
lines = '''
The first newline is
trimmed in raw strings.
All other whitespace
is preserved.
'''

Numbers

Integers, floats, infinity, and even NaN are all supported. You can use scientific notation and even thousands separators.

# integers
int1 = +99
int2 = 42
int3 = 0
int4 = -17

# hexadecimal with prefix `0x`
hex1 = 0xDEADBEEF
hex2 = 0xdeadbeef
hex3 = 0xdead_beef

# octal with prefix `0o`
oct1 = 0o01234567
oct2 = 0o755

# binary with prefix `0b`
bin1 = 0b11010110

# fractional
float1 = +1.0
float2 = 3.1415
float3 = -0.01

# exponent
float4 = 5e+22
float5 = 1e06
float6 = -2E-2

# both
float7 = 6.626e-34

# separators
float8 = 224_617.445_991_228

# infinity
infinite1 = inf # positive infinity
infinite2 = +inf # positive infinity
infinite3 = -inf # negative infinity

# not a number
not1 = nan
not2 = +nan
not3 = -nan 

Dates and Times

TOML features support for dates, times, and datetimes with and without offsets.

#offset datetime
odt1 = 1979-05-27T07:32:00Z
odt2 = 1979-05-27T00:32:00-07:00
odt3 = 1979-05-27T00:32:00.999999-07:00

# local datetime
ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T00:32:00.999999

# local date
ld1 = 1979-05-27

# local time
lt1 = 07:32:00
lt2 = 00:32:00.999999

More Spec

TOML supports even more native types and syntax, read all about it:

Start coding

TOML is already implemented in over 40 programming languages: