v1.0.0
Опубликовано 1/11/2021 – Текстовая версия

TOML v1.0.0

Tom's Obvious, Minimal Language. (Очевидный, Минималистичный Язык Тома.)

За авторством Tom Preston-Werner, Pradyun Gedam, et al.

Цели

TOML стремится быть минималистичным форматом файлов конфигурации, который легко читаем ввиду очевидной семантики. TOML разработан, чтобы однозначно переводиться в хэш-таблицу. TOML должен легко парситься в структуры данных в широком ряде языков.

Спецификация

  • TOML чувствителен к регистру.
  • Файл TOML должен быть документом, корректно закодированным в UTF-8.
  • Пустота - это табуляция (0x09) или пробел (0x20).
  • Перенос строки - это LF (0x0A) или CRLF (0x0D 0x0A).

Комментарий

Символ "хэштег" обозначает оставшуюся после него часть строки как комментарий, кроме тех случаев, когда он находится внутри строкового типа данных.

# Этот комментарий занимает всю строку
key = "значение"  # Этот комментарий - в конце строки
another = "# Это не комментарий"

Управляющие символы, кроме табуляции (от U+0000 до U+0008, от U+000A до U+001F, U+007F), не разрешены внутри комментариев.

Пара Ключ/Значение

Основной строительный блок в документе TOML - это пара ключ/значение.

Ключи располагаются слева от знака равенства, а значения - справа. Пустота игнорируется с обеих сторон ключей и значений. Ключ, знак равенства и значение обязаны быть на одной строке (однако некоторые значения могут быть разбиты по нескольким строкам).

key = "значение"

Значения обязаны иметь один из приведённых типов.

Отсутствие значения недопустимо.

key = # НЕДОПУСТИМО

После пары ключ/значение должен быть перенос строки (или конец файла). (За исключениями смотрите раздел Встроенная Таблица.)

first = "Tom" last = "Preston-Werner" # НЕДОПУСТИМО

Ключи

Ключ может быть либо простым, либо ключом-цитатой, либо точечным.

Простые ключи должны состоять исключительно из букв ASCII, цифр ASCII, нижних подчёркиваний и тире (A-Za-z0-9_-). Учтите, что простые ключи разрешено составлять из сугубо цифр ASCII, например, 1234, но они всегда будут интерпретироваться, как строки.

key = "значение"
bare_key = "значение"
bare-key = "значение"
1234 = "значение"

Ключи-цитаты следуют тем же правилам, которым следуют и обычные строки либо буквальные строки, и позволяют вам использовать гораздо больший набор названий для ключей, включая русский алфавит. Лучшей практикой считается использовать именно простые ключи, кроме тех случаев, когда альтернатива крайне необходима.

"127.0.0.1" = "значение"
"кодовая страница" = "значение"
"ʎǝʞ" = "значение"
'ключ2' = "значение"
'"значение" в кавычках' = "значение"

Простой ключ обязан быть непустым, однако пустой ключ-цитата разрешён (и всё же это не рекомендуется).

= "нет названия ключа"  # НЕДОПУСТИМО
"" = "пустота"          # ДОПУСТИМО но не рекомендуется
'' = 'пустота'          # ДОПУСТИМО но не рекомендуется

Точечные ключи - это последовательности простых ключей или ключей-цитат, объединённых через точку. Это позволяет группировать похожие свойства:

name = "Апельсин"
physical.color = "оранжевый"
physical.shape = "круглый"
"веб-сайт"."yandex.ru" = true

В JSON-ляндии это бы дало вам такую структуру данных:

{
  "name": "Апельсин",
  "physical": {
    "color": "оранжевый",
    "shape": "круглый"
  },
  "веб-сайт": {
    "yandex.ru": true
  }
}

Насчёт деталей, связанных с таблицами, которые определены через точечные ключи, обратитесь к разделу Таблица ниже.

Пустота между частями, объединёнными точкой, игнорируется. Однако, лучшая практика - не использовать никакую лишнюю пустоту.

fruit.name = "банан"     # это - лучшая практика
fruit. color = "жёлтый"    # то же самое, что fruit.color
fruit . flavor = "банан"   # то же самое, что fruit.flavor

К отступам такое же отношение, как и к пустоте - они игнорируются.

Определять ключ много раз нельзя.

# НЕ ДЕЛАЙТЕ ТАК
name = "Tom"
name = "Pradyun"

Учтите, что простые ключи и ключи-цитаты эквивалентны:

# ЭТО НЕ СРАБОТАЕТ
spelling = "бордюр"
"spelling" = "поребрик"

До тех пор, пока ключ не был определён напрямую, вы всё ещё можете вписывать значения в него и в элементы внутри него.

# Это превращает ключ "fruit" в таблицу.
fruit.apple.smooth = true

# Так что потом вы можете добавить значение в таблицу "fruit" так:
fruit.orange = 2
# НИЖЕПРИВЕДЁННОЕ НЕДОПУСТИМО

# Здесь значение fruit.apple определяется как целое число.
fruit.apple = 1

# Но потом к fruit.apple относятся так, как будто это таблица.
# Вы не можете превратить целое число в таблицу.
fruit.apple.smooth = true

Определять точечные ключи не по порядку не рекомендуется.

# ДОПУСТИМО, НО НЕ РЕКОМЕНДУЕТСЯ

apple.type = "фрукт"
orange.type = "фрукт"

apple.skin = "тонкий"
orange.skin = "толстый"

apple.color = "красный"
orange.color = "оранжевый"
# РЕКОМЕНДУЕТСЯ

apple.type = "фрукт"
apple.skin = "тонкий"
apple.color = "красный"

orange.type = "фрукт"
orange.skin = "толстый"
orange.color = "оранжевый"

Так как простые ключи могут быть образованы из сугубо цифр ASCII, то, технически, можно сделать точечные ключи, которые выглядят точь-в-точь как числа с плавающей запятой, но на самом деле являются точечными ключами из 2 частей. Не делайте так, если у вас нет хорошей причины на это (скорее всего, нет).

3.14159 = "пи"

Вышеприведённый TOML переводится в следующий JSON.

{ "3": { "14159": "пи" } }

Строка

Здесь есть четыре способа хранить строки: обычный, многострочный обычный, буквальный, и многострочный буквальный. Каждая строка должна состоять исключительно из допустимых символов UTF-8.

Обычные строки обрамляются кавычками ("). Каждый символ Юникода может быть использован, кроме тех, которые нужно экранировать: кавычки, обратную косую черту и управляющие символы, не считая табуляции (от U+0000 до U+0008, от U+000A до U+001F, U+007F).

str = "Я строка. \"Вы можете цитировать меня\". Имя\tВячасла\u045E\nГород\tМинск."

Для удобства, некоторые часто используемые символы имеют укороченную управляющую последовательность.

\b         - backspace/возврат на шаг        (U+0008)
\t         - tab/табуляция                   (U+0009)
\n         - line feed/перевод строки        (U+000A)
\f         - form feed/перевод формата       (U+000C)
\r         - carriage return/возврат каретки (U+000D)
\"         - кавычка                         (U+0022)
\\         - обратная косая черта            (U+005C)
\uXXXX     - юникод                          (U+XXXX)
\UXXXXXXXX - юникод                          (U+XXXXXXXX)

Любой символ Юникода может быть экранирован по форме \uXXXX или \UXXXXXXXX. Коды экранирования должны быть допустимыми скалярными значениями Юникода.

Все остальные последовательности экранирования, которые не указаны выше, зарезервированы; если они были использованы, TOML должен выдавать ошибку.

Вы можете нуждаться в хранении отрывков текста (к примеру, файлов перевода) или в разбиении очень длинной строки на несколько строк файла. TOML упрощает это занятие.

Многострочные обычные строки обрамляются тройными кавычками с обеих сторон и разрешают переносы строки. Перенос строки, следующий сразу после открытого разделителя, будет обрезан. Любая другая пустота и символы переноса строки останутся нетронутыми.

str1 = """
Розы красные
Фиалки синие"""

Парсерам TOML следует превратить перенос строки в то, что имеет смысл для их системы.

# На Unix-like ОС вышеприведённая многострочная строка, скорее всего, будет таковой:
str2 = "Розы красные\nФиалки синие"

# На системе Windows та же строка будет эквивалента этой:
str3 = "Розы красные\r\nФиалки синие"

Для написания длинных строк без привлечения лишней пустоты используйте "обратную косую черту, оканчивающую строку". Когда последний непустой символ в строке файла - это неэкранированная \, она будет вырезана вместе со всей пустотой (переносами строки включительно) до следующего непустого символа или разделителя. Все последовательности экранирования, допустимые для обычных строк, также допустимы для многострочных обычных строк.

# Нижеприведённые строки эквивалентны вплоть до байта:
str1 = "Съешь ещё этих мягких французских булок, да выпей чаю."

str2 = """
Съешь ещё этих \


  мягких французских \
    булок, да выпей чаю."""

str3 = """\
       Съешь ещё этих \
       мягких французских \
       булок, да выпей чаю.\
       """

Любой символ Юникода может быть использован, кроме тех, которые необходимо экранировать: обратная косая черта и управляющие символы, не считая табуляцию, перевод строки и возврат каретки (от U+0000 до U+0008, U+000B, U+000C, от U+000E до U+001F, U+007F).

Вы можете вписать один или два слитно символа кавычки где угодно внутри многострочной обычной строки. Они также могут быть вписаны внутри разделителя.

str4 = """Вот две кавычки: "". Достаточно просто."""
# str5 = """Вот три кавычки: """."""  # НЕДОПУСТИМО
str5 = """Вот три кавычки: ""\"."""
str6 = """Вот пятнадцать кавычек: ""\"""\"""\"""\"""\"."""

# "Это", - сказала она, - "совершенно бессмысленное заявление."
str7 = """"Это", - сказала она, - "совершенно бессмысленное заявление.""""

Если вы регулярно работаете с путями в Windows или регулярными выражениями, то постоянное экранирование обратных косых черт становится муторным делом, в котором легко ошибиться. Чтобы помочь, TOML поддерживает буквальные строки, которые совсем не разрешают экранирование.

Буквальные строки обрамляются одинарными кавычками. Как и обычные строки, они обязаны умещаться на одной строке файла:

# Что вы видите, то и получаете.
winpath  = 'C:\Users\nodejs\templates'
winpath2 = '\\ServerX\admin$\system32\'
quoted   = 'Tom "Dubs" Preston-Werner'
regex    = '<\i\c*\s*>'

Так как экранирование здесь не присутствует, нет и возможности написать одинарную кавычку в буквальной строке, обрамлённой одинарными кавычками. К счастью, TOML поддерживает многострочную версию буквальных строк, которая решает эту проблему.

Многострочные буквальные строки обрамляются тройными одинарными кавычками с обеих сторон и разрешают переносы строки. Как и в буквальных строках, никакое экранирование не работает. Перенос строки, следующий за открытым разделителем, будет вырезан. Всё остальное содержание строки между разделителями интерпретируется как есть, без изменений.

regex2 = '''Это [ 2-9]1 яблоко [ м]не понадобится.'''
lines  = '''
Первый перенос строки
обрезается в буквальных.
   Вся остальная пустота
   остаётся нетронутой.
'''

Вы можете вписать 1 или 2 одинарных кавычки где угодно внутри многострочной буквальной строки, но последовательности в три или более одинарных кавычек не разрешены.

quot15 = '''Вот пятнадцать кавычек: """""""""""""""'''

# apos15 = '''Вот пятнадцать апострофов: ''''''''''''''''''  # НЕДОПУСТИМО
apos15 = "Вот пятнадцать апострофов: '''''''''''''''"

# 'Это', - сказала она, - 'до сих пор бессмыслица.'
str = ''''Это', - сказала она, - 'до сих пор бессмыслица.''''

Управляющие символы, кроме табуляции, не разрешены в буквальной строке. Таким образом, для двоичных данных рекомендуется использовать Base64 или другую подходящую кодировку ASCII или UTF-8. Применение тому зависит от программы.

Целое число

Положительные числа можно предварять знаком "плюс". Отрицательные числа предваряются знаком "минус".

int1 = +99
int2 = 42
int3 = 0
int4 = -17

Для больших чисел вы можете использовать нижние подчёркивания, чтобы улучшить читаемость. Каждое нижнее подчёркивание должно быть обрамлено хотя бы одной цифрой с обеих сторон.

int5 = 1_000
int6 = 5_349_221
int7 = 53_49_221  # Индийская система группировки цифр
int8 = 1_2_3_4_5  # ДОПУСТИМО но не рекомендуется

Нули в начале не разрешены. Целые значения -0 и +0 допустимы и приравниваются к нулю без префикса.

Неотрицательные целые числа также можно представить в шестнадцатеричной, восьмеричной или двоичной системе счисления. В этих форматах не разрешён префикс +, а нули в начале, наоборот, разрешены (после префикса). Шестнадцатеричные значения нечувствительны к регистру. Нижние подчёркивания разрешены между цифрами (но не между префиксом и значением).

# шестнадцатеричное с префиксом `0x`
hex1 = 0xDEADBEEF
hex2 = 0xdeadbeef
hex3 = 0xdead_beef

# восьмеричное с префиксом `0o`
oct1 = 0o01234567
oct2 = 0o755 # полезно для разрешений файлов в Unix

# двоичное с префиксом `0b`
bin1 = 0b11010110

Произвольные 64-битные знаковые целые числа (от −2^63 до 2^63−1) должны быть разрешены и обработаны без потерь. Если целое число не может быть выведено без потерь, должна быть выдана ошибка.

Число с плавающей запятой

Числа с плавающей запятой должны быть имплементированы как binary64 значения согласно IEEE 754.

Число с плавающей запятой состоит из целой части (которая следует тем же правилам, что и десятичные целые числа), за которой следует дробная часть и/или экспоненциальная часть. Если присутствуют и дробная, и экспоненциальная часть, то дробная часть должна предшествовать экспоненциальной.

# дробная
flt1 = +1.0
flt2 = 3.1415
flt3 = -0.01

# экспоненциальная
flt4 = 5e+22
flt5 = 1e06
flt6 = -2E-2

# обе
flt7 = 6.626e-34

Дробная часть - это десятичная точка, за которой следует одна или больше цифр.

Экспоненциальная часть - это латинская E (заглавная или строчная), за которой следует целая часть (которая следует тем же правилам, что и десятичные целые числа, но может включать нули в начале).

Если десятичная точка используется, то она должна быть обрамлена хотя бы одной цифрой с каждой стороны.

# НЕДОПУСТИМЫЕ ЧИСЛА С ПЛАВАЮЩЕЙ ЗАПЯТОЙ
invalid_float_1 = .7
invalid_float_2 = 7.
invalid_float_3 = 3.e+20

Так же, как и с целыми числами, вы можете использовать нижние подчёркивания, чтобы улучшить читаемость. Каждое нижнее подчёркивание должно быть обрамлено хотя бы одной цифрой.

flt8 = 224_617.445_991_228

Числа с плавающей запятой -0.0 и +0.0 допустимы и должны переводиться в соответствии с IEEE 754.

Специальные числа с плавающей запятой тоже могут быть использованы. Они всегда в нижнем регистре.

# бесконечность
sf1 = inf  # положительная бесконечность
sf2 = +inf # положительная бесконечность
sf3 = -inf # отрицательная бесконечность

# не число (not a number)
sf4 = nan  # действительная кодировка sNaN/qNaN зависит от имплементации
sf5 = +nan # такое же, как и `nan`
sf6 = -nan # допустимо, но действительная кодировка зависит от имплементации

Булева переменная

Булевы - это просто токены, к которым вы привыкли. Всегда в нижнем регистре.

bool1 = true  # правда
bool2 = false # ложь

Сдвинутые Дата и Время

Чтобы однозначно представлять определённый момент времени, вы можете использовать дату и время, форматированные в соответствии с RFC 3339, со сдвигом.

odt1 = 1979-05-27T07:32:00Z
odt2 = 1979-05-27T00:32:00-07:00
odt3 = 1979-05-27T00:32:00.999999-07:00

Ради читабельности, вы можете заменить разделитель T между датой и временем на символ пробела (как и разрешено разделом 5.6 RFC 3339).

odt4 = 1979-05-27 07:32:00Z

Требуется точность вплоть до миллисекунды. Дальнейшая точность дробных секунд зависит от имплементации. Если значение имеет точность выше, чем ту, что поддерживает имплементация, то лишняя точность должна быть обрезана, не округлена.

Местные Дата и Время

Если вы уберёте сдвиг из форматированных по RFC 3339 дате и времени, они будут представлять данные дату и время безо всякой связи со сдвигом или временной зоной. Они не могут быть сконвертированны в момент времени без дополнительной информации. Конвертация в момент времени, если требуется, зависит от имплементации.

ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T00:32:00.999999

Требуется точность вплоть до миллисекунды. Дальнейшая точность дробных секунд зависит от имплементации. Если значение имеет точность выше, чем ту, что поддерживает имплементация, то лишняя точность должна быть обрезана, не округлена.

Местная Дата

Если вы оставите из форматированных по RFC 3339 дате и времени ту часть, что содержит дату, она будет представлять все данные сутки безо всякой связи со сдвигом или временной зоной.

ld1 = 1979-05-27

Местное Время

Если вы оставите из форматированных по RFC 3339 дате и времени ту часть, что содержит время, оно будет представлять это время суток безо всякой связи со сдвигом или временной зоной.

lt1 = 07:32:00
lt2 = 00:32:00.999999

Требуется точность вплоть до миллисекунды. Дальнейшая точность дробных секунд зависит от имплементации. Если значение имеет точность выше, чем ту, что поддерживает имплементация, то лишняя точность должна быть обрезана, не округлена.

Массив

Массивы - это квадратные скобки со значениями внутри. Пустота игнорируется. Элементы разделяются запятыми. Массивы должны хранить данные тех же типов, которые разрешены в парах ключ/значение. Значения различных типов можно смешивать.

integers = [ 1, 2, 3 ]
colors = [ "красный", "жёлтый", "зелёный" ]
nested_arrays_of_ints = [ [ 1, 2 ], [3, 4, 5] ]
nested_mixed_array = [ [ 1, 2 ], ["a", "b", "c"] ]
string_array = [ "все", 'строки', """одного и того же""", '''типа''' ]

# Массивы со смешанными типами разрешены
numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]
"участники" = [
  "Рога и копыта <hornsandhooves@example.com>",
  { "имя" = "Вася Пупкин", email = "vasyapupkin@example.com", url = "https://example.com/vasyapupkin" }
]

Массивы могут простираться на несколько строк. Завершающая запятая (также называется конечной запятой) разрешена после последнего значения в массиве. Любое количество переносов строки и комментариев может предшествовать значениям, запятым и закрывающейся скобке. Отступы между значениями в массиве и запятыми считаются пустотой и игнорируются.

integers2 = [
  1, 2, 3
]

integers3 = [
  1,
  2, # это нормально
]

Таблица

Таблицы (также известные как хэш-таблицы или словари) - это коллекции пар ключ/значение. Они определяются заголовками, обрамлёнными квадратными скобками на отдельной строке. Вы можете отличить заголовки от массивов тем, что массивы - это всегда только значения.

[table]

Под ним и до следующего заголовка или конца файла находятся ключи/значения этой таблицы. Пары ключ/значение внутри таблицы не гарантируют никакого установленного порядка расположения.

[table-1]
key1 = "какая-то строка"
key2 = 123

[table-2]
key1 = "другая строка"
key2 = 456

Правила наименования таблиц такие же, как и для ключей (см. определение Ключей выше).

[dog."картошка.муж"]
type.name = "мопс"

В JSON-ляндии это бы дало вам такую структуру данных:

{ "dog": { "картошка.муж": { "type": { "name": "мопс" } } } }

Пустота вокруг ключа игнорируется. Однако, лучшей практикой будет не использовать лишней пустоты.

[a.b.c]            # это - лучшая практика
[ d.e.f ]          # то же, что и [d.e.f]
[ g .  h  . i ]    # то же, что и [g.h.i]
[ j . "ʞ" . 'l' ]  # то же, что и [j."ʞ".'l']

Отступы считаются за пустоту и игнорируются.

Вам не нужно определять все таблицы выше по уровню, если вы не хотите. TOML знает, как это сделать за вас.

# [x] вам
# [x.y] не
# [x.y.z] нужны эти
[x.y.z.w] # чтобы это работало

[x] # определять над-таблицы позже - это нормально

Пустые таблицы разрешены, и просто не хранят внутри никаких пар ключ/значение. Это разрешено. Это не хранит данные.

Как и ключи, вы не можете определить таблицу больше одного раза. Это недопустимо.

# НЕ ДЕЛАЙТЕ ТАК

[fruit]
apple = "красный"

[fruit]
orange = "оранжевый"
# И ТАК ТОЖЕ НЕ ДЕЛАЙТЕ

[fruit]
apple = "красный"

[fruit.apple]
texture = "гладкий"

Определять таблицы не по порядку не рекомендуется.

# ДОПУСТИМО НО НЕ РЕКОМЕНДУЕТСЯ
[fruit.apple]
[animal]
[fruit.orange]
# РЕКОМЕНДУЕТСЯ
[fruit.apple]
[fruit.orange]
[animal]

Таблица самого высокого уровня, также называемая корневой таблицей, начинается с начала документа и заканчивается перед первым табличным заголовком (или на конце файла). В отличие от остальных таблиц, она безымянная и не может быть перемещена.

# Корневая таблица начинается.
name = "Fido"
breed = "pug"

# Корневая таблица заканчивается.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04

Точечные ключи определяют таблицу для каждой части ключа перед последней, если таковые таблицы не были определены ранее.

fruit.apple.color = "красный"
# Определяет таблицу с названием fruit
# Определяет таблицу с названием fruit.apple

fruit.apple.taste.sweet = true
# Определяет таблицу с названием fruit.apple.taste
# fruit и fruit.apple уже были определены

Так как таблицы нельзя определять больше одного раза, переопределять таблицы с помощью заголовка [table] не разрешено. Также не разрешено использовать точечные ключи, чтобы переопределять таблицы, уже определённые в форме [table]. Однако, форма [table] может использоваться, чтобы определять под-таблицы в таблицах, определённых через точечные ключи.

[fruit]
apple.color = "красный"
apple.taste.sweet = true

# [fruit.apple]  # НЕДОПУСТИМО
# [fruit.apple.taste]  # НЕДОПУСТИМО

[fruit.apple.texture]  # вы можете добавлять под-таблицы
smooth = true

Встроенная Таблица

Встроенные таблицы предоставляют более компактный синтаксис для выражения таблиц. Они особенно полезны для сгруппированных данных, которые иначе могут быстро стать очень объёмными. Встроенные таблицы полностью определяются внутри фигурных скобок: { и }. Внутри скобок может появиться ноль или больше пар ключ/значение, разделённых запятой. Пары ключ/значение принимают ту же форму, что и в стандартных таблицах. Все типы данных разрешены, включая сами встроенные таблицы.

Встроенные таблицы предполагается определять на одной строке. Завершающая запятая (также называется конечной запятой) не разрешена после последней пары ключ/значение во встроенной таблице. Переносы строки не разрешены между фигурными скобками, только если они не допустимы в пределах какого-то из значений. Даже при этом крайне не рекомендуется разрывать встроенную таблицу на несколько строк. Если вы чувствуете себя охваченными этим желанием, это значит, что вам следует использовать стандартные таблицы.

name = { first = "Tom", last = "Preston-Werner" }
"точка" = { x = 1, y = 2 }
animal = { type.name = "мопс" }

Вышеприведённые встроенные таблицы идентичны стандартным, написанным ниже:

[name]
first = "Tom"
last = "Preston-Werner"

["точка"]
x = 1
y = 2

[animal]
type.name = "мопс"

Встроенные таблицы полностью независимы и определяют все ключи и под-таблицы внутри себя. Ключи и под-таблицы невозможно добавить вне скобок.

[product]
type = { name = "Гвоздь" }
# type.edible = false  # НЕДОПУСТИМО

Точно так же, встроенные таблицы нельзя использовать, чтобы добавлять ключи и под-таблицы в уже определённую таблицу.

[product]
type.name = "Гвоздь"
# type = { edible = false }  # НЕДОПУСТИМО

Массив Таблиц

Последний неописанный синтаксис позволяет создавать массивы таблиц. Их можно определять, используя заголовок, облачённый в двойные квадратные скобки. Первая инстанция этого заголовка определяет массив и таблицу, которая является его первым элементом. Каждая последующая инстанция определяет новую таблицу-элемент в этом массиве. Таблицы входят в массив в порядке появления.

[[products]]
name = "Молоток"
sku = 738594937

[[products]]  # пустая таблица внутри массива

[[products]]
name = "Гвоздь"
sku = 284758393

color = "серый"

В JSON-ляндии это бы дало вам такую структуру данных:

{
  "products": [
    { "name": "Молоток", "sku": 738594937 },
    { },
    { "name": "Гвоздь", "sku": 284758393, "color": "серый" }
  ]
}

Любая ссылка на массив таблиц указывает на таблицу, являющуюся самым новым определённым элементом этого массива. Это позволяет вам определять под-таблицы, а также под-массивы таблиц внутри самой новой таблицы.

[[fruits]]
name = "яблоко"

[fruits.physical]  # под-таблица
color = "красный"
shape = "круглый"

[[fruits.varieties]]  # вложенный массив таблиц
name = "красное вкусное"

[[fruits.varieties]]
name = "гренни смит"


[[fruits]]
name = "банан"

[[fruits.varieties]]
name = "плантан"

Вышеприведённый TOML переводится в следующий JSON.

{
  "fruits": [
    {
      "name": "яблоко",
      "physical": {
        "color": "красный",
        "shape": "круглый"
      },
      "varieties": [
        { "name": "красное вкусное" },
        { "name": "гренни смит" }
      ]
    },
    {
      "name": "банан",
      "varieties": [
        { "name": "плантан" }
      ]
    }
  ]
}

Если родитель таблицы или массива таблиц - это элемент массива, то он должен быть определён до дочернего элемента. Попытки обратить этот порядок должны выдавать ошибку в процессе парсинга.

# НЕДЕЙСТВИТЕЛЬНЫЙ ДОКУМЕНТ TOML
[fruit.physical]  # под-таблица, но к какому родительскому элементу
                  # она должна относиться?
color = "красный"
shape = "круглый"

[[fruit]]  # парсер должен выдавать ошибку после обнаружения, что "fruit" - это
           # массив, а не таблица
name = "яблоко"

Попытки добавить элемент к статично определённому массиву, даже если этот массив пуст, должны выдавать ошибку в процессе парсинга.

# НЕДЕЙСТВИТЕЛЬНЫЙ ДОКУМЕНТ TOML
fruits = []

[[fruits]] # Не разрешено

Попытки определить обычную таблицу с тем же именем, что и у уже определённого массива, должны выдавать ошибку в процессе парсинга. Попытки переопределить обычную таблицу как массив также должны выдавать ошибку парсинга.

# НЕДЕЙСТВИТЕЛЬНЫЙ ДОКУМЕНТ TOML
[[fruits]]
name = "яблоко"

[[fruits.varieties]]
name = "красное вкусное"

# НЕДОПУСТИМО: Эта таблица конфликтует с массивом таблиц повыше
[fruits.varieties]
name = "гренни смит"

[fruits.physical]
color = "красный"
shape = "круглый"

# НЕДОПУСТИМО: Этот массив таблиц конфликтует с таблицей повыше
[[fruits.physical]]
color = "green"

Вы также можете использовать встроенные таблицы там, где это разрешено:

"точки" = [ { x = 1, y = 2, z = 3 },
           { x = 7, y = 8, z = 9 },
           { x = 2, y = 4, z = 8 } ]

Расширения Имён Файлов

Имена файлов TOML должны иметь расширение .toml.

Тип MIME

При передаче файлов TOML по интернету, соответствующий тип MIME - это application/toml.

В формате ABNF

Формальное описание синтакса TOML доступно в качестве отдельного файла ABNF.