TOML

From Wikipedia, the free encyclopedia
Jump to navigation Jump to search
TOML
TOML Logo.svg
Filename extension
.toml
Internet media typeNot registered[1]
Developed byTom Preston-Werner
Community
Initial release23 February 2013; 9 years ago (2013-02-23)
Latest release
v1.0.0
January 11, 2021; 17 months ago (2021-01-11)
Type of formatData interchange
Open format?Yes
Websitetoml.io Edit this at Wikidata

TOML is a file format for configuration files. It is intended to be easy to read and write due to obvious semantics which aim to be "minimal", and is designed to map unambiguously to a dictionary. Its specification is open-source, and receives community contributions. TOML is used in a number of software projects,[2][3][4] and is implemented in many programming languages.[2] The name "TOML" is an acronym for "Tom's Obvious, Minimal Language"[5] referring to its creator, Tom Preston-Werner.

Syntax[edit]

TOML's syntax primarily consists of key = "value" pairs, [section names], and # comments. TOML's syntax somewhat resembles that of .INI files, but it includes a formal specification, whereas the INI file format suffers from many competing variants.

Its specification includes a list of supported data types: String, Integer, Float, Boolean, Datetime, Array, and Table.

Example[edit]

# 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 to other formats[edit]

The following table draws on the TOML specification to make a comparison to other popular configuration formats.

Format comparison
Format Formal standard Human-readable Allows comments Syntax typing[6][7]
CUE[8] Yes[citation needed] Yes[citation needed] Yes Yes
INI No, multiple dialects Yes[9] Yes No
JSON Yes[10] Yes[citation needed] No Yes
TOML No, formal specification[11] Yes[citation needed] Yes Yes
YAML No, formal specification[12] Yes[citation needed] Yes Yes
XML Yes[13] Not particularly[citation needed] Yes No

Criticism[edit]

Since its first release TOML has received several critiques. The following is not a consensus. The StrictYAML project lists the following points as problematic in TOML:[14]

  • TOML is verbose; it is not DRY and it is syntactically noisy
  • TOML's hierarchies are difficult to infer from syntax alone
  • Overcomplication: Like YAML, TOML has too many features
  • In TOML the syntax determines the data types ("syntax typing")

The libconfini project has since released a more extensive critique of TOML from the INI perspective,[15] listing the following points (among others) as problematic:

  • TOML lets the configuration file decide about data types (syntax typing), when de facto it is the client application that decides. Any mismatching type will be either ignored or converted to the expected type (depending on the parser) anyway
  • TOML re-introduces what human-friendly languages normally try to get rid of: a verbose syntax and the necessity of using quotes for strings
  • TOML syntax is always case-sensitive, despite the fact that there are situations where configuration files must be case-insensitive (as, for instance, configuration files that map a FAT32 filesystem or HTML tags)
  • TOML uses square brackets for arrays even though square brackets are already reserved for table names; furthermore any special syntax for arrays brings the language back to syntax typing
  • A TOML table must be populated in a single step; merging multiple TOML files is problematic
  • TOML arbitrarily introduces a syntax for dates
  • TOML allows (but discourages) the empty string as a key
  • TOML's rules cannot be inferred from the content, therefore editing a TOML file requires prior knowledge of the language
  • TOML is backward-incompatible with INI

See also[edit]

References[edit]

  1. ^ There is a mime type proposal for TOML consisting in application/toml, but this has never been officially registered among IANA's Media Types.
  2. ^ a b "toml-lang/toml". GitHub. 23 May 2022.
  3. ^ "The Manifest Format - The Cargo Book". doc.rust-lang.org.
  4. ^ Drew DeVault (2021-07-28). "My wish-list for the next YAML". YAML is both universally used, and universally reviled. It has a lot of problems, but it also is so useful in solving specific tasks that it’s hard to replace. Some new kids on the block (such as TOML) have successfully taken over a portion of its market share, but it remains in force in places where those alternatives show their weaknesses.
  5. ^ "toml-lang/toml". January 15, 2021 – via GitHub.
  6. ^ Syntax typing refers to the use of syntax to designate data types. In languages that allow syntax typing, type declaration will be syntax-based – e.g. true will be a boolean while "true" will be a string – whereas in languages that do not allow syntax typing it will be semantics-based – e.g. true and "true" will be both recognizable as booleans, while microwave and "microwave" will be both recognizable as strings (this will require the parser to have some prior expectations about the type of a particular field, but this is often the case in configuration files).
  7. ^ Opinions on whether syntax typing in configuration formats is a good or a bad feature vary among authors. with some considering it a disadvantage (see for example What is wrong with TOML § Syntax typing) and others favoring it.
  8. ^ "About".
  9. ^ Robichaux, Paul (9 September 2000). Managing The Windows 2000 Registry Paperback (1st ed.). O'Reilly Media. p. 2. ISBN 9781565929432. Microsoft chose a simple, human-readable ASCII format for INI files; not only did this ease the task of writing programs to use these files, but it also made it possible for end users to inspect and change their contents.
  10. ^ "The JavaScript Object Notation (JSON) Data Interchange Format".
  11. ^ "TOML Specification".
  12. ^ "YAML™ Specification Index".
  13. ^ "Extensible Markup Language (XML) 1.0 (Fifth Edition)".
  14. ^ What is wrong with TOML?
  15. ^ An INI critique of TOML

External links[edit]