toml

TOML File Format Specification

Overview

TOML (Tom's Obvious, Minimal Language) is a configuration file format that's easy to read and write due to its simple and minimal syntax. It's designed to map easily to data structures in programming languages. Here’s a comprehensive guide to the TOML format.

Basic Structure

Key-Value Pairs: Represented as key = "value".
Sections: Defined using square brackets [section].

Data Types

String
- Basic Strings: Enclosed in double quotes.
```
key = "value"
```
- Multiline Strings: Enclosed in triple double quotes.
```
key = """
This is a
multiline string.
"""
```
- Literal Strings: Enclosed in single quotes.
```
key = 'value'
```
- Multiline Literal Strings: Enclosed in triple single quotes.
```
key = '''
This is a
multiline literal string.
'''
```
Integer
- Decimal integers without leading zeros.
```
key = 42
```
Float
- Decimal numbers with a fractional part.
```
key = 3.14
```
Boolean
- Either true or false.
```
key = true
```
Datetime
- ISO 8601 format.
```
key = 1979-05-27T07:32:00Z
```
Array
- Elements separated by commas, enclosed in square brackets.
```
key = [ "alpha", "beta" ]
```

Tables

Tables are collections of key-value pairs and are denoted by square brackets. Nested tables can be represented by dot-separated keys.

[table]
key = "value"

[table.subtable]
key = "value"

Inline Tables

For small tables, you can use inline tables.

table = { key = "value", key2 = "value2" }

Arrays of Tables

Arrays of tables are used to define multiple tables with the same keys.

[[products]]
name = "Hammer"
sku = 738594937

[[products]]
name = "Nail"
sku = 284758393
color = "gray"

Comments

Lines starting with # are comments.

# This is a comment
key = "value"  # This is an inline comment

Example TOML File

# Example TOML file
title = "TOML Example"

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

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

[servers]
  [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"
]

Best Practices

Consistent Formatting: Keep formatting consistent for readability.
Use Comments: Provide comments to describe sections and key-value pairs.
Group Related Keys: Use tables to group related configuration keys.
Avoid Redundancy: Use nested tables and arrays to avoid repeating similar structures.

This guide should help you understand and write TOML files effectively, ensuring your configuration is clear and well-organized.