GithubHelp home page GithubHelp logo

toml's Introduction

TOML

Tom's Obvious, Minimal Language.

By Tom Preston-Werner.

Latest tagged version: v0.1.0.

Be warned, this spec is still changing a lot. Until it's marked as 1.0, you should assume that it is unstable and act accordingly.

Objectives

TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.

Example

# This is a TOML document. Boom.

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
organization = "GitHub"
bio = "GitHub Cofounder & CEO\nLikes tater tots and beer."
dob = 1979-05-27T07:32:00Z # First class dates? Why not?

[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true

[servers]

  # You can indent as you please. Tabs or spaces. TOML don't care.
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"

[clients]
data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [
  "alpha",
  "omega"
]

Spec

  • TOML is case sensitive.
  • Whitespace means tab (0x09) or space (0x20).

Comment

Speak your mind with the hash symbol. They go from the symbol to the end of the line.

# I am a comment. Hear me roar. Roar.
key = "value" # Yeah, you can do this.

String

ProTip™: You may notice that this specification is the same as JSON's string definition, except that TOML requires UTF-8 encoding. This is on purpose.

Strings are single-line values surrounded by quotation marks. Strings must contain only valid UTF-8 characters. Any Unicode character maybe be used except those that must be escaped: quotation mark, backslash, and the control characters (U+0000 to U+001F).

"I'm a string. \"You can quote me\". Name\tJos\u00E9\nLocation\tSF."

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)
\/     - slash           (U+002F)
\\     - backslash       (U+005C)
\uXXXX - unicode         (U+XXXX)

Any Unicode character may be escaped with the \uXXXX form.

Other special characters are reserved and, if used, TOML should produce an error. This means paths on Windows will always have to use double backslashes.

wrong = "C:\Users\nodejs\templates" # note: doesn't produce a valid path
right = "C:\\Users\\nodejs\\templates"

For binary data it is recommended that you use Base64 or another suitable encoding. The handling of that encoding will be application specific.

Integer

Integers are bare numbers, all alone. Feeling negative? Do what's natural. 64-bit minimum size expected.

42
-17

Float

Floats are numbers with a single dot within. There must be at least one number on each side of the decimal point. 64-bit (double) precision expected.

3.1415
-0.01

Boolean

Booleans are just the tokens you're used to. Always lowercase.

true
false

Datetime

Datetimes are ISO 8601 dates, but only the full zulu form is allowed.

1979-05-27T07:32:00Z

Array

Arrays are square brackets with other primitives inside. Whitespace is ignored. Elements are separated by commas. Data types may not be mixed.

[ 1, 2, 3 ]
[ "red", "yellow", "green" ]
[ [ 1, 2 ], [3, 4, 5] ]
[ [ 1, 2 ], ["a", "b", "c"] ] # this is ok
[ 1, 2.0 ] # note: this is NOT ok

Arrays can also be multiline. So in addition to ignoring whitespace, arrays also ignore newlines between the brackets. Terminating commas are ok before the closing bracket.

key = [
  1, 2, 3
]

key = [
  1,
  2, # this is ok
]

Hash

There are two ways to make keys. I call them "key groups" and "keys". Both are just regular keys, but key groups only ever have a single hash as their value.

Key groups appear in square brackets on a line by themselves. You can tell them apart from arrays because arrays are only ever values.

[keygroup]

Under that, and until the next key or EOF are the key/values of that key group. Keys are on the left of the equals sign and values are on the right. Keys start with the first non-whitespace character and end with the last non-whitespace character before the equals sign. Key/value pairs within key groups are unordered.

[keygroup]
key = "value"

You can indent keys and their values as much as you like. Tabs or spaces. Knock yourself out. Why, you ask? Because you can have nested hashes. Snap.

Nested hashes are denoted by key groups with dots in them. Name your key groups whatever crap you please, just don't use a dot. Dot is reserved. OBEY.

[key.tater]
type = "pug"

In JSON land, that would give you the following structure:

{ "key": { "tater": { "type": "pug" } } }

You don't need to specify all the superkeys if you don't want to. TOML knows how to do it for you.

# [x] you
# [x.y] don't
# [x.y.z] need these
[x.y.z.w] # for this to work

When converted to a hash table, an empty key group should result in the key's value being an empty hash table.

As long as a superkey hasn't defined a specific key, you may still write to it.

[a.b]
c = 1

[a]
d = 2

You cannot define any key or key group more than once. Doing so is invalid.

# DO NOT DO THIS

[a]
b = 1

[a]
c = 2
# DO NOT DO THIS EITHER

[a]
b = 1

[a.b]
c = 2

Seriously?

Yep.

But why?

Because we need a decent human-readable format that maps to a hash and the YAML spec is like 80 pages long and gives me rage. No, JSON doesn't count. You know why.

Oh god, you're right

Yuuuup. Wanna help? Send a pull request. Or write a parser. BE BRAVE.

Implementations

If you have an implementation, send a pull request adding to this list. Please note the commit SHA1 or version tag that your parser supports in your Readme.

Validators

Language agnostic test suite for TOML parsers

Editor support

Encoder

toml's People

Contributors

aaronblohowiak avatar agh avatar agrison avatar ajwans avatar alex avatar alexkalderimis avatar ambv avatar ayushchd avatar benjaminpaap avatar benolee avatar burntsushi avatar c0mkid avatar cespare avatar craiglittle avatar dirk avatar eik3 avatar elssar avatar emancu avatar felipap avatar gilesbowkett avatar haileys avatar jamesmoss avatar kalta avatar kaos avatar lmno avatar mojombo avatar redhotvengeance avatar ricardobeat avatar rossipedia avatar sutto avatar

Watchers

avatar avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.