DOCSEARCHbyAlgolia
Submit Docs

BurntSushi/toml

repository·master·Indexed 26 days ago

https://github.com/burntsushi/toml

A Go package providing a reflection-based interface for encoding and decoding TOML data, compatible with TOML v1.1.0. It includes tools for parsing TOML into Go structs, marshaling Go values to TOML, and a CLI validator called tomlv. The library supports custom unmarshaling via encoding.TextUnmarshaler and the UnmarshalTOML interface, as well as custom encoding via the Marshaler interface. It also provides utility tools like toml-test-decoder and toml-test-encoder for validating parsers and encoders against the official test suite.

Tokens
7.9K
Snippets
24
Records
65
Agent score
89%

What's inside toml

  1. TOML v1.0.0 Specification Overview

    master

    TOML (Tom's Obvious, Minimal Language) is a minimal configuration file format designed to map unambiguously to a hash table.

    Core Rules:

    • Case-sensitivity: TOML is case-sensitive.
    • Encoding: Files must be valid UTF-8 encoded Unicode documents.
    • Whitespace: Whitespace consists of tabs (0x09) or spaces (0x20).
    • Newlines: Newlines are LF (0x0A) or CRLF (0x0D 0x0A).
    • Comments: A hash symbol (#) marks the rest of the line as a comment, except when inside a string. Control characters (other than tab) are not permitted in comments.

  2. TOML Language Preliminaries

    master

    TOML (Tom's Obvious, Minimal Language) is a configuration file format designed to map unambiguously to hash tables.

    Key constraints:

    • Case-sensitivity: TOML is case-sensitive.
    • Whitespace: Whitespace consists of tabs (U+0009) and spaces (U+0020).
    • Newlines: Newlines are LF (U+000A) or CRLF (U+000D U+000A).
    • Encoding: Files must be valid UTF-8 encoded Unicode documents.

  3. Use comments in TOML

    master

    Comments start with a hash symbol (#) and continue to the end of the line. Comments are ignored by parsers and are not part of keys or values unless they are inside a string.

    Rules:

    • Control characters (U+0000 to U+0008, U+000A to U+001F, U+007F) are not permitted in comments.
    • Comments should be used for human communication; parsers must not modify data based on comments.
    # This is a full-line comment
key = "value"  # This is a comment at the end of a line
another = "# This is not a comment"

  4. Define Bare, Quoted, and Dotted Keys

    master

    TOML supports three types of keys:

    1. Bare keys: Contain only ASCII letters, digits, underscores, and dashes (A-Za-z0-9_-). They are always interpreted as strings.
    2. Quoted keys: Use basic strings (") or literal strings ('). They allow a much broader set of characters (e.g., spaces, dots, or special symbols).
    3. Dotted keys: A sequence of bare or quoted keys joined by dots (.), used to create nested structures (tables).

    Best Practices:

    • Use bare keys whenever possible.
    • Avoid using multi-line strings for quoted keys.
    • Avoid defining dotted keys out-of-order.
    • Avoid using dotted keys that look like floats (e.g., 3.14159) as they map to nested tables rather than a single float key.
    # Bare keys
key = "value"
bare_key = "value"
bare-key = "value"
1234 = "value"

# Quoted keys
"127.0.0.1" = "value"
"character encoding" = "value"
'key2' = "value"

# Dotted keys (creates nested tables)
name = "Orange"
physical.color = "orange"
physical.shape = "round"
site."google.com" = true

  5. Use Key/Value Pairs in TOML

    master

    The primary building block of TOML is the key/value pair. Keys are on the left of the equals sign and values are on the right. Whitespace around keys and values is ignored. Each pair must be on the same line (though some values can span multiple lines) and must be followed by a newline or EOF.

    Invalid usage:

    • Providing no value: key =
    • Multiple pairs on one line: first = "Tom" last = "Preston-Werner"
    key = "value"

  6. Create Key/Value Pairs

    master

    The primary building block of TOML is the key/value pair. Keys are on the left of the equals sign (=) and values are on the right.

    Requirements:

    • The key, equals sign, and value must be on the same line (though some values can span multiple lines).
    • There must be a newline or EOF after a key/value pair.
    • Unspecified values are invalid.

    Valid Types for Values:

    • String, Integer, Float, Boolean, Offset Date-Time, Local Date-Time, Local Date, Local Time, Array, Inline Table.
    key = "value"

  7. Use toml-test-decoder to validate TOML data

    master
    The toml-test-decoder tool implements the interface required by the toml-test suite to validate a TOML parser. It works by reading TOML data from stdin and mapping it to a JSON format on stdout. This is useful for testing the correctness of a TOML parser against the official test suite requirements.

  8. Use toml-test-encoder to validate TOML encoders

    master
    The toml-test-encoder tool implements the interface required by the toml-test suite to validate TOML encoders. It works by reading JSON data from stdin and mapping it to a TOML format on stdout. This can be used as part of a testing pipeline to ensure an encoder correctly handles various data structures.

  11. Avoid Invalid TOML Patterns

    master

    The following patterns will cause parse-time errors:

    1. Redefining a table: Defining the same [table] header twice.
    2. Conflicting types: Defining a table with the same name as an existing array (or vice versa).
    3. Out-of-order sub-tables: Attempting to define a sub-table (e.g., [fruit.physical]) before its parent array element (e.g., [[fruit]]) has been defined.
    4. Appending to static arrays: Attempting to use [[array]] syntax on a key that was already defined as a standard array (e.g., fruits = []).
    5. Inline table limitations: Trying to add keys to a table that was defined as an inline table.
    # INVALID: Redefining table
[fruit]
apple = "red"
[fruit]
orange = "orange"

# INVALID: Subtable before parent array element
[fruit.physical]
color = "red"
[[fruit]]
name = "apple"

# INVALID: Appending to static array
fruits = []
[[fruits]]

# INVALID: Type conflict (Array vs Table)
[[fruits]]
name = "apple"
[fruits.varieties]
name = "granny smith"

# INVALID: Type conflict (Table vs Array)
[[fruits.physical]]
color = "green"
[fruits.physical]
color = "red"

  12. Avoid invalid key definitions in TOML

    master

    When writing TOML, ensure you avoid these common errors:

    • Duplicate Keys: Defining the same key multiple times in the same scope is invalid.
    • Type Mismatches in Nesting: You cannot treat a value as a table if it has already been defined as a non-table type (e.g., an integer).
    • Empty Bare Keys: A bare key cannot be empty.
    • Multiple Pairs on one line: Each key/value pair must be followed by a newline or EOF (except within inline tables).
    • Multi-line Quoted Keys: You cannot use multi-line strings to define a key name.
    # INVALID: Duplicate keys
name = "Tom"
name = "Pradyun"

# INVALID: Trying to turn an integer into a table
fruit.apple = 1
fruit.apple.smooth = true

# INVALID: Multiple pairs on one line
first = "Tom" last = "Preston-Werner"

# INVALID: Empty bare key
= "no key name"