Как таблицы TOML становятся объектами JSON: [таблица], [[массив]] и ключи с точками

Откуда взялось гнездование? — плоский файл TOML, преобразованный в глубоко вложенный JSON, и заголовки, которые его вызвали.

Файл TOML может выглядеть почти плоским, поскольку вложенность заключена в скобки. `[a.b.c]` открывает промежуточные таблицы, поэтому `d = 1` под ним становится `{"a":{"b":{"c":{"d":1}}}}`. Фигурные скобки JSON делают видимой иерархию, которую TOML выражает через путь к активной таблице.

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

Заголовки [таблицы] — как заголовок открывает вложенный объект и как [a.b.c] неявно создает промежуточные объекты.

Заголовок в одинарной скобке открывает таблицу. `[owner]` направляет следующие назначения в `owner`; `[owner.contact]` создает или вводит вложенный объект контакта. Промежуточные объекты не обязательно должны иметь отдельные заголовки. Их существование следует из сегментов пути в заголовке.

Присвоения перед любым заголовком остаются в корне. Более поздние таблицы не перемещают их задним числом. При просмотре преобразованной JSON указывайте полный путь к свойству, а не физическое расстояние между строками: текущая таблица TOML остается активной до тех пор, пока ее не изменит другой заголовок.

[[массив таблиц]] — почему повторяющийся заголовок в двойных скобках добавляет объекты в массив и порядок, который он сохраняет

Заголовок в двойной скобке добавляет таблицу к массиву. Два раздела `[[server]]` становятся `server: [{...},{...}]` в исходном порядке. Поля под каждым заголовком принадлежат этому элементу массива до тех пор, пока не начнется другой заголовок, что делает повторную конфигурацию явной в JSON.

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

Ключи с точками и встроенные таблицы — a.b = 1 и { x = 1 } как еще два способа выразить одну и ту же вложенность.

Назначения с точками обеспечивают другое обозначение пути: `a.b.c = true` дает ту же форму вложенного объекта, что и соответствующие заголовки таблиц. Встроенные таблицы, такие как `point = { x = 1, y = 2 }`, немедленно становятся вложенными объектами. Эти формы могут описывать схожие деревья, но при этом выглядеть для рецензента совершенно по-разному.

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

Типы, которые переносятся, и типы, которые этого не делают — целые числа, числа с плавающей запятой, логические значения и строки сопоставляются напрямую; дата-время становятся строками, а JSON null не имеет источника TOML

Строки, безопасные целые числа, числа с плавающей запятой, логические значения, массивы и таблицы сопоставляются напрямую. Четыре временных типа TOML не становятся их исходными строками, подобными RFC 3339, и предупреждение называет каждый путь и вид. Позже автор цитирует эти строки, а не воссоздает токены даты и времени.

Подписанные 64-битные целые числа TOML могут превышать безопасный диапазон целых чисел JavaScript. smol-toml возвращает такие значения, как BigInt, когда это необходимо; ToolAcre преобразует их в десятичные строки и выдает предупреждение, а не округляет цифры. Это позволяет сохранить орфографию за счет изменения типа JSON.

Рабочий пример: список pyproject.toml — [проект], [project.optional-зависимости] и список [[tool.plugins]] преобразован в JSON с трассировкой каждого уровня.

Попробуйте `name = "demo"`, `[project]`, `dependencies = ["a", "b"]`, `[project.optional]`, `test = ["vitest"]`, затем две таблицы `[[tool.plugins]]` с разными именами. JSON помещает имя в корень, объединяет проект и необязательный элемент и создает массив плагинов под инструментом.

Добавьте `released = 1979-05-27` и `huge = 9223372036854775807`. Первой становится строка `1979-05-27`; второй становится десятичной строкой. Оба предупреждения идентифицируют измененные пути, делая типы, не относящиеся к JSON, доступными для просмотра вместо разрешения автоматического приведения даты или числа.

Чего это не касается — преобразование JSON обратно в идиоматический TOML с разумной группировкой заголовков, что предполагает выбор стиля, который ни одно правило полностью не определяет.

JSON-to-TOML поддерживается для корневого объекта, но не воссоздает идиоматические выборы или комментарии автора. Ключи с нулевым значением опускаются; null внутри массива становится пустой строкой для сохранения позиций. Корневой массив, скалярный или нулевой, отклоняется, поскольку документ TOML должен быть таблицей.

Такое поведение исправляет изложенное в схеме предположение о том, что обратное преобразование находится за пределами области действия. Конвертер записывает TOML, но точность стиля выходит за рамки его обещаний. Различие имеет значение: поддерживаемая сериализация — это не то же самое, что побайтовое восстановление исходного файла или выбор макета, который предпочитает сопровождающий.

Запись JSON обратно в TOML поддерживается, но комментарии, типы даты и времени и авторский стиль не возвращаются.

Прочитайте заголовки TOML как пути и двойные скобки как операции добавления. Представление JSON полезно для отслеживания результирующего дерева, а предупреждения отображают дату и время и широкие целые числа, пересекающие границу типа. Не вызывайте операцию без потерь при появлении любого предупреждения.

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

Окончательное сравнение должно разделить три вопроса, которые легко спутать. Во-первых, сохранились ли проанализированные значения? Во-вторых, превратился ли какой-либо тип, содержащий только TOML, в строку JSON или исчезли какие-либо значения NULL? В-третьих, организован ли недавно сериализованный TOML таким образом, чтобы его мог понять сопровождающий? Первые два можно проверить по значениям и предупреждениям; третий нуждается в человеческом рассмотрении. Разделение этих проверок не позволяет технически допустимой сериализации называться точной миграцией, когда ее типы или авторская структура изменились.