toml README

The project's README from github.com/toml-lang/toml. As one markdown file: README.md.

TOML logo

TOML

Tom's Obvious, Minimal Language.

By Tom Preston-Werner, Pradyun Gedam, et al.

This repository contains the in-development version of the TOML specification. You can find the released versions at https://toml.io.

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.

title = "TOML Example"

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

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

[servers]

  # Indentation (tabs and/or spaces) is allowed but not required
  [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"
]

Comparison with Other Formats

TOML shares traits with other file formats used for application configuration and data serialization, such as YAML and JSON. TOML and JSON both are simple and use ubiquitous data types, making them easy to code for or parse with machines. TOML and YAML both emphasize human readability features, like comments that make it easier to understand the purpose of a given line. TOML differs in combining these, allowing comments (unlike JSON) but preserving simplicity (unlike YAML).

Because TOML is explicitly intended as a configuration file format, parsing it is easy, but it is not intended for serializing arbitrary data structures. TOML always has a hash table at the top level of the file, which can easily have data nested inside its keys, but it doesn't permit top-level arrays or floats, so it cannot directly serialize some data. There is also no standard identifying the start or end of a TOML file, which can complicate sending it through a stream. These details must be negotiated on the application layer.

INI files are frequently compared to TOML for their similarities in syntax and use as configuration files. However, there is no standardized format for INI and they do not gracefully handle more than one or two levels of nesting.

Further reading:

Get Involved

Documentation, bug reports, pull requests, and all other contributions are welcome!

Wiki

We have an Official TOML Wiki that catalogs the following:

Please take a look if you'd like to view or add to that list. Thanks for being a part of the TOML community!

toml (toml-lang/toml)

key-value
Searching Database…

20.6K ·GitHub
Toml
What is this?TOML (Tom's Obvious, Minimal Language) is a minimal configuration file format designed to be readable at a glance, with semantics obvious enough to map cleanly onto a hash table. This repository holds the in-development TOML specification itself.
So is this a tool, a library — what exactly am I looking at?Neither — this repo is the specification, the document that defines the syntax. The software lives in separate TOML libraries written for many programming languages.
How do I start using TOML, then?You don't install anything from this repo — TOML is a text format you write by hand and parse with a library for your language. The Official TOML Wiki is the starting point: it catalogs implementations, editor support and converters.
What can't TOML do?Two things to know: the top level is always a hash table — no top-level arrays or floats — so some data cannot be serialized directly, and files have no standard start/end markers, which complicates streaming.
Why create TOML when JSON and YAML already existed?Because none of them combined both strengths: JSON is simple but forbids comments, while YAML is readable but complex. TOML was designed to give application configuration both at once.
Why not just use INI files for configuration?INI looks similar but has no standardized format and does not gracefully handle more than one or two levels of nesting — TOML is standardized and nests data under its keys.
Is the TOML spec still evolving?Yes — this repository hosts the in-development version of the specification, while stable released versions are published separately, so changes land here first.
Is TOML really named after a person called Tom?Yes — it stands for Tom's Obvious, Minimal Language, after creator Tom Preston-Werner; Pradyun Gedam and other contributors maintain the spec today.
What are similar projects?swift-evolution, proposals, fantasy-land, spec, ecma262, rfcs, interop, api-guidelines
Which topics is it in?language-design, minimal, interoperability, toml, standards, config, parsing, key-value, specification, configuration, data-structures, reference
Creator
toml-lang
Size
2.4 MB
Stars
20.6K
Updated
CommitSep 10Release1.1.0Dec 24
Age
13y
Commits · 90 Days