Первый раз, когда TOML укусил меня, это был не синтаксис Это был порядок У меня был объект настроек JSON из старой службы Node, я хотел, чтобы это было как config.toml для переписывания Rust, и я сделал то, что каждый делает в первый раз: я вручную напечатал таблицы. через десять минут парсер бросал ошибку, которую я не понял, указывая на линию, которая выглядела идеально хорошо. Проблема заключалась в том, что три клавиши сидели ниже a [table] заголовок, принадлежавший выше него. TOML имеет правило, что JSON не делает, и как только вы споткнетесь на нем, вы никогда его не забудете.
я строю Toolz.devи я отправил туда длинную полку конвертеров формата, поэтому я написал конвертер JSON в TOML, чтобы удалить всю эту категорию ошибок. Вы вставляете JSON, вы получаете TOML, который повторно анализирует те же данные, и заказ обрабатывается для вас. Это руководство - это то, что мне хотелось бы прочитать в тот день: что такое TOML, где JSON и TOML не согласны и как конвертировать между ними, не теряя ничего, что вас волнует.
TL;DR: TOML - это типизированный формат конфигурации, используемый Cargo, Poetry, Hugo и многими инструментами Rust and Go. Преобразование JSON в TOML в основном механическое, но три вещи требуют суждения: порядок таблиц (ключи перед подтаблицами, всегда), как вы пишете массивы объектов (массивы таблиц против встроенных таблиц) и что происходит с JSON
null, что TOML не имеет возможности выразить. The Конвертер JSON в TOML делает все три явными и полностью запускается в вашем браузере.
Что такое TOML и зачем мне конвертировать в него JSON?
TOML означает Tom's Очевидный, Минимальный язык. Он читается как старый файл INI, но в отличие от INI он имеет реальную спецификацию с напечатанными значениями, первоклассными датами и определенной грамматикой. Эта спецификация является причиной победы: формат конфигурации, который человек может прочитать с первого взгляда, который машина каждый раз анализирует одинаково, без двусмысленности относительно того, является ли port = 8080 является строкой или числом Это число, потому что TOML говорит так.
Вы достигаете преобразования JSON в TOML, когда машина дала вам JSON, а инструмент хочет TOML. Это происходит больше, чем вы думаете. API возвращает блок настроек как JSON, и он вам нужен pyproject.toml. У тебя есть старый config.json и вы перемещаете проект в стек, который читается config.toml. Вы создали некоторые данные программно, они вышли как JSON, потому что это именно то JSON.stringify производит, а потребитель - Cargo или Hugo или сервис Go с использованием библиотеки TOML.В каждом случае данные идентичны. отличается только сериализация.
Обратное направление тоже существует, но это другая работа. Если вы идете другим путем, то Форматтер JSON стоит сначала открыть для себя возможность проверить здравомыслие JSON и JSON в YAML конвертер охватывает другой распространенный формат конфигурации. Это руководство о переходе JSON в TOML.
Как конвертер отображает JSON на TOML?
В JSON всего несколько фигур, и у каждой есть дом в TOML. Понимание сопоставления - это лучшее понимание инструмента.
ДЖСОН объект становится TOML таблица. Объектом верхнего уровня является корневая таблица, поэтому преобразователь настаивает на том, чтобы входными данными был объект. Вложенные объекты становятся [table] заголовки с пунктирным путем, так что { "database": { "pool": { "max": 10 } } } становится а [database.pool] раздел с max = 10 внутри него.
ДЖСОН массив объектов становится TOML массив таблиц, написано с помощью двойной скобки [[name]] заголовок, один блок на элемент. это идиоматический шаблон TOML для списка записей: список серверов, список зависимостей, список целей сборки. каждый элемент получает свой [[servers]] блок.
Каждый скалярный отображает напрямую. строка JSON становится базовой строкой TOML в двойных кавычках, с экранированными управляющими символами. Номер JSON становится целым числом TOML, если это целое число и плавающее в противном случае. логическое значение JSON становится true или false. Это простые случаи, и конвертер никогда не ошибается.
ДЖСОН массив скаляров становится встроенным массивом TOML: ["admin", "editor"] остается ["admin", "editor"]. Смешанные массивы и вложенные массивы также записываются в ряд, потому что это единственное место, где они подходят.
Почему заказ ключей так важен в TOML?
Это правило, которое ловит всех, поэтому стоит прямо заявить.В TOML, в пределах любой таблицы, все эти пары ключ/значение #39;s должны появиться перед любым из его подзаголовков таблицы. Если вы напишете a [server] заголовок, затем некоторые ключи, затем еще один ключ, принадлежащий корневой таблице, синтаксический анализатор считывает этот случайный ключ как часть [server] вместо. В лучшем случае он попадает не в то место; в худшем случае файл не может проанализировать.
В JSON такого правила нет. В JSON порядок ключей даже не значим, а объекты и скаляры свободно смешиваются внутри одних и тех же скобок. Таким образом, наивное преобразование JSON в TOML, которое перемещает объект в порядке вставки и излучает каждую клавишу по мере его прохождения, приведет к сломанному TOML в тот момент, когда скаляр следует за вложенным объектом.
Преобразователь решает это, делая два прохода над каждой таблицей, Сначала он излучает все простые ключи, скаляры и встроенные массивы. только тогда он излучает заголовки подтаблицы и массива таблиц, рекурсируя в каждый. Ваш порядок ключей сохраняется внутри каждой группы, что вы хотите, но требуемая перестановка между двумя группами происходит автоматически. вам никогда не нужно думать об этом, и вы никогда не получите ошибку, которую я получил.
Когда массивы объектов должны быть таблицами, а не встроенными?
Вот один подлинный выбор. массив объектов может быть записан двумя способами в TOML, и оба действительны.
Первый - это массив таблиц, форма с двойной скобкой. Это многословно и читаемо, один блок на запись, и это то, как выглядит большинство TOML в дикой природе. Если вы видели a Cargo.toml с несколькими [[bin]] записи, вы это видели.
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
Второй - ан рядный стол внутри нормального массива, который упаковывает каждый объект в одну строку.
servers = [
{ name = "web", ip = "10.0.0.1" },
{ name = "api", ip = "10.0.0.2" },
]
Оба туда и обратно к одним и тем же данным. какой вы хотите, зависит от цели и от вкуса. массивы таблиц читаются лучше для записей, которые человек будет редактировать, и они являются соглашением для большинства конфигураций инструментов. встроенные таблицы более компактны и ближе к форме исходного JSON, который некоторые люди предпочитают, когда список короткий или объекты крошечные. конвертер по умолчанию использует массивы таблиц и дает переключатель для переключения. Если вы не уверены, оставьте его по умолчанию: это то, как обычно выглядит файл TOML.
Что происходит с JSON null в TOML?
У TOML нет нуля. Нет ни ключевого слова, ни пустого значения, ничего. Это продуманное дизайнерское решение по формату, и это единственное место, где JSON для TOML действительно проигрыш.
Так что конвертер должен сделать выбор, и он позволяет сделать его. по умолчанию, ключ, значение которого null опускается, и инструмент перечисляет выпавшие клавиши в заметке под выводом, так что ничего не исчезает бесшумно. если вы предпочитаете сохранить клавишу, вы можете переключиться на запись null как пустой строки, которая сохраняет клавишу ценой изменения ее типа. ни то, ни другое не идеально, потому что нет идеального ответа. важно то, что выбор виден, а не похоронен.
Нули внутри массивов всегда опускаются с предупреждением, потому что массив TOML вообще не может содержать нуль. Если у вашего JSON есть [1, null, 3], ТОМЛ будет [1, 3] и инструмент скажет вам, что он удалил один. Если эти нули несут значение, это сигнал изменить форму данных перед преобразованием, а не после.
Почему мое число потеряло десятичную дробь или набрало единицу?
Этот удивляет людей, которые заботятся о типах. JSON не различает 5 из 5.0. Оба анализируются на один и тот же IEEE 754 дважды, и к тому времени JSON.parse сделано нет следа конечного нуля. Итак, когда преобразователь видит число 5, у него нет возможности узнать, что вы имели в виду поплавок, и с тех пор 5 является целым числом, оно записывает целое число TOML.
TOML, с другой стороны, отличает целые числа от плавающих, и некоторые инструменты заботятся о разнице. Если вам нужно значение, напечатанное в виде плавающего значения, исправление состоит в том, чтобы придать ему дробную часть в источнике, 5.1 или 5.0 написано таким образом, что выживает, или чтобы редактировать единичное значение после преобразования Это односимвольное изменение и оно редко, но стоит знать, почему это происходит, а не предполагать, что конвертер ошибается Это не неправильно. JSON просто выбросил информацию до того, как конвертер когда-либо увидел ее.
Обратный случай отображается с очень большими или очень маленькими числами, где JavaScript's String() производит обозначения экспоненты типа 1e+21. TOML принимает это как плавающее значение, поэтому оно преобразуется нормально, но форма числа может выглядеть иначе, чем то, что вы набрали. Опять же, значение идентично; изменился только рендеринг.
Как работают голые и цитируемые ключи?
TOML позволяет писать ключ обнаженным, если он состоит только из букв, цифр, подчеркиваний и тире. Все остальное, ключ с точкой, пробелом, косой чертой, символом Юникода, должно цитироваться. Конвертер проверяет каждый ключ и цитирует только те, которые в нем нуждаются, поэтому user-name остается голым и "user.name" получает кавычки, чтобы остановить чтение точки как пути таблицы. вам не нужно думать об этом, но если вы видите кавычки вокруг ключа в выводе, именно поэтому: ключ содержал символ, который в противном случае изменил бы его значение.
Работающий пример
Вот образец, который загружает инструмент, поэтому вы можете увидеть каждое правило одновременно. JSON:
{
"title": "Toolz config",
"version": 2,
"enabled": true,
"owner": { "name": "Liton", "roles": ["admin", "editor"] },
"database": { "host": "localhost", "port": 5432, "pool": { "min": 2, "max": 10 } },
"servers": [
{ "name": "web", "ip": "10.0.0.1" },
{ "name": "api", "ip": "10.0.0.2" }
]
}
становится TOML, где первыми стоят корневые скаляры, вложенные объекты становятся пунктирными таблицами по порядку, а массив серверов становится двумя [[servers]] блоки:
title = "Toolz config"
version = 2
enabled = true
[owner]
name = "Liton"
roles = ["admin", "editor"]
[database]
host = "localhost"
port = 5432
[database.pool]
min = 2
max = 10
[[servers]]
name = "web"
ip = "10.0.0.1"
[[servers]]
name = "api"
ip = "10.0.0.2"
Обратите внимание, что title, version а enabled пишутся перед любым заголовком, roles остается встроенным массивом, поскольку это массив строк, и [database.pool] сидит под [database] как пунктирный путь Каждое правило в этом руководстве видно в девяти строках вывода.
Какой инструмент для какого преобразования?
ТОМЛ - это один формат в семье, и правильный инструмент зависит от того, с чего вы начинаете и заканчиваете Вот как я об этом думаю.
| У тебя есть | Вы хотите | обычай |
|---|---|---|
| JSON | Конфигурация TOML | JSON в TOML |
| JSON | Конфигурация YAML | json в yaml |
| бахвалиться | JSON | ЯМЛ в JSON |
| JSON | хм-лиг | json в xml |
| Месси JSON | Читаемый JSON | Форматтер JSON |
Шаблон заключается в том, что форматы конфигурации являются взаимозаменяемыми представлениями одних и тех же данных, а нужный вам преобразователь назван в честь направления, в котором вы идете. TOML, YAML и JSON выражают вложенные данные ключа/значения; разница в том, какой из них читает ваш целевой инструмент.
Безопасно ли конвертировать файл конфигурации онлайн?
Конфиг-файлы - это именно то, что вам следует тщательно вставлять на веб-сайт, поскольку они часто содержат строки подключения, токены и другие секреты. The Конвертер JSON в TOML полностью работает в вашем браузере.JSON вы вставляете анализируется в памяти на вашем устройстве, TOML производится там, и ничего не отправляется на сервер, записывается в журнал, или сохраняется.Вы можете посмотреть это сами: открыть свою вкладку сети, запустить преобразование, и увидеть, что ни один запрос не погас. Он также продолжает работать без соединения, как только страница загрузилась, что является практическим доказательством того, что работа локальная.Если вы заботитесь о том, куда ваши данные идут, и с файлом конфигурации вы должны, это свойство имеет значение. это один и тот же принцип за каждым инструментом на сайте, и причина, по которой я написал об этом подробно в примечании на Конфиденциальность данных в онлайн-инстру, йо-
Где это вписывается в реальный рабочий процесс
Преобразование формата редко является всей задачей Это шаг Вы вытягиваете объект настройки из API, вы конвертируете его, вы бросаете его в проект. значение конвертера на стороне клиента заключается в том, что он вставляет в этот поток без трения: нет загрузки, нет учетной записи, нет ожидания на сервере, не интересно, находятся ли ваши секреты сейчас в ком-то и #39;s logs.Это та же причина, по которой я сохраняю все Toolz.dev установите клиентскую сторону, и я вернусь к этой теме Инструменты повышения производительности разработчик записывайте, потому что инструменты, к которым вы обращаетесь двадцать раз в день, - это те, к которым складываются двухсекундная поездка туда и обратно и вопрос конфиденциальности.
TOML заслужил свое место в этом потоке, будучи скучным в лучшем виде. Он анализирует одно и то же повсюду, хорошо читает, и его один острый край, правило упорядочения, - это именно то, что конвертер должен вам записать. Вставьте свой JSON, выберите, как вы хотите, чтобы массивы и нули обрабатывались, и скопируйте TOML, который просто работает.
Часто задаваемые вопросы
Как конвертировать JSON в TOML?
Вставьте свой объект JSON в конвертер и нажмите Convert. инструмент сериализует объекты в таблицы TOML, массивы объектов в массивы таблиц и все остальные значения в строке, затем дает вам стандартный TOML для копирования. JSON верхнего уровня должен быть объектом, потому что документ TOML всегда является таблицей.
Для чего используется ТОМЛ?
TOML - это формат файла конфигурации, предназначенный для простого чтения и однозначного анализа. Это формат конфигурации для Rust's Cargo (Cargo.toml), упаковки Python (pyproject.toml), Hugo и многих инструментов Go и Rust. Люди преобразуют JSON в TOML, чтобы передать сгенерированную машиной конфигурацию инструменту, который ожидает TOML.
Что происходит с нулевыми значениями JSON в TOML?
У TOML нет нулевого типа, поэтому JSON null нельзя представить напрямую По умолчанию этот конвертер отбрасывает нулевые ключи и добавляет примечание с их перечислением; вместо этого вы можете переключиться на запись их как пустых строк. Null внутри массивов всегда отбрасываются, потому что массив TOML не может содержать null.
В чем разница между массивом таблиц и встроенной таблицей?
Массив таблиц использует повторяющиеся заголовки с двумя скобками, по одному блоку на запись, и является идиоматическим способом TOML для записи списка объектов, таких как список серверов или зависимостей. встроенная таблица упаковывает объект в одну строку, поскольку набор ключей равен парам значений в скобках. Этот инструмент по умолчанию использует массивы таблиц, но вместо этого позволяет выбирать встроенные.
Почему мой номер JSON 5.0 стал 5 в TOML?
JSON не сохраняет разницу между 5 и 5,0, поэтому синтаксический анализ читается как число 5. Поскольку 5 - это целое число, конвертер записывает его как целое число TOML. Если вам нужно, чтобы оно было набрано как плавающее, добавьте дробную часть в исходный код или отредактируйте единичное значение после преобразования.
Сохраняет ли конвертер мой порядок ключей?
Да. ключи излучаются в том порядке, в котором они появляются в JSON, с одной необходимой перестановкой: внутри каждой таблицы простые ключи записываются перед любыми заголовками подтаблицы или массива таблиц. это правило синтаксиса TOML, а не выбор переупорядочения, и без него файл не анализировался бы.
Мой json загружен на сервер?
Нет. Все преобразование происходит в вашем браузере с использованием простого JavaScript. Ваш JSON, включая любые секреты или учетные данные в файле конфигурации, никогда не передается, не регистрируется и не сохраняется, а конвертер продолжает работать без подключения после загрузки страницы.
Почему там написано, что верхний уровень должен быть объектом?
Документ TOML определяется как таблица, что означает, что он должен начинаться с набора пар ключ/значение. Голый массив JSON или скаляр не имеет таблицы, на которую можно было бы сопоставить. сначала оберните его в объект, например поместите свой массив под именованный ключ, и он преобразуется.
