Шпаргалка у форматі TOON

Якщо вам коли-небудь здавалося, що JSON надто багатослівний (усі ті фігурні дужки!), а YAML надто «магічний» і непередбачуваний, ви можете просто закохатися в TOON. Цей формат забезпечує унікальний баланс між зручністю для читання людиною та швидкістю машинного аналізу. Він розроблений, щоб бути щільним, явним і неймовірно швидким для аналізу.

Незалежно від того, переносите ви дані чи просто намагаєтеся налагодити файл конфігурації, ця шпаргалка охоплює основний синтаксис, який вам потрібно знати.

Філософія: менше шуму, більше даних

Перше, що ви помітите, це те, що TOON дуже схожий на YAML, але поводиться як JSON. Він відмовляється від відкриваючих і закриваючих дужок на користь відступів і нових рядків, завдяки чому ваші дані одразу виглядають чистішими.

Об'єкти та вкладення

У JSON ви звикли загортати все у фігурні дужки. У TOON структура мається на увазі за допомогою відступу.

JSON:

{ 
"проект": { 
"метадані": { 
"name": "Альфа-Центавра", 
"статус": "активний" 
}, 
"віхи": [ 
{ 
"phase": "дизайн", 
"пріоритет": 1 
}, 
{ 
"phase": "тестування", 
"пріоритет": 2 
} 
] 
} 
} 

ТУН:

проект: 
метадані: 
Назва: Альфа-Центавра 
статус: активний 
етапи[2]{фаза,пріоритет}: 
дизайн,1 
тестування,2 

Зауважте, що ключі не потребують лапок, якщо вони не містять спеціальних символів, а ієрархія візуально очевидна.

Сила масивів

Ось де TOON дійсно відрізняється від інших форматів. TOON вимагає, щоб ви оголосили довжину масиву в самому ключі. Спочатку це може здатися дивним, але це дозволяє синтаксичному аналізатору попередньо виділяти пам’ять, що робить його неймовірно швидким.

Примітивні масиви

Для простих списків рядків або чисел TOON використовує компактний синтаксис, розділений комами.

Синтаксис:

key[length]:item1,item2,item3 

Якщо у вас є кореневий масив (весь файл — це лише список), він виглядає так:

Табличні масиви (вбивча функція)

Це функція, яка зазвичай вражає розробників. Якщо у вас є масив об’єктів, які мають однакові ключі (наприклад, рядки в базі даних), TOON дозволяє визначити схему один раз у заголовку, а потім просто перерахувати значення. Це видаляє величезну кількість надлишкового вмісту в JSON.

Синтаксис:

key[rows]{col1,col2}: 

JSON:

{ 
"інвентар": [ 
{ 
"sku": "KB-99", 
"кількість": 50, 
"прохід": 4, 
"reorder": false 
}, 
{ 
"sku": "MS-12", 
"кількість": 12, 
"прохід": 7, 
"reorder": правда 
}, 
{ 
"sku": "MN-44", 
"кількість": 8, 
"прохід": 2, 
"reorder": правда 
} 
] 
} 

ТУН:

inventory[3]{sku,qty,aisle,reorder}: 
КБ-99,50,4,неправда 
МС-12,12,7,правда 
МН-44,8,2,правда 

Цей підхід «CSV-inside-YAML» робить великі набори даних неймовірно читабельними та компактними.

Змішані та вкладені масиви

Іноді дані неоднакові. Якщо ваш масив містить різні типи даних (числа, змішані з об’єктами), або якщо він містить складні вкладені об’єкти, TOON повернеться до синтаксису в стилі маркування з використанням дефісів.

Ви навіть можете мати масиви всередині масивів. Зверніть увагу, що внутрішній масив також оголошує свою довжину:

Цитата: коли це використовувати

Однією з найприємніших речей TOON є те, що вам рідко потрібні цитати. Ви можете написати Hello 世界 👋, не загортаючи його в "". Однак, оскільки TOON намагається вивести типи (числа, логічні значення), існують спеціальні правила, коли ви повинні використовувати лапки.

Список "Обов'язково процитувати".

Ви повинні взяти свій рядок у подвійні лапки """, якщо:

1. Це виглядає як число або логічне значення: Якщо вам потрібен рядок "123" або "true", візьміть його в лапки. Інакше вони стають числом 123 і логічним значенням true.

2. Він містить розділювачі: Якщо у вашому рядку є кома , (або інший активний роздільник), візьміть його в лапки.

3. У нього є пробіли по краях: Пробіли на початку або в кінці вимагають лапок.

4. Він містить спеціальні символи: такі символи, як :, ", \, [, ], {, }.

5. Він порожній: Порожній рядок представлено як "".

Приклади:

Вихідні послідовності

Будьте простими. TOON розпізнає лише п’ять escape-послідовностей у рядках. Все інше недійсне.

• \\ (зворотна коса риска)

• \" (подвійні лапки)

• \n (новий рядок)

• \r (повернення каретки)

• \t (табуляція)

Розширені заголовки та роздільники

Що робити, якщо ваші дані повні ком? Ви не хочете брати в лапки кожне поле. TOON дозволяє змінювати роздільник у заголовку масиву.

Ви можете використовувати Tab або Pipe (|), помістивши їх у дужки.

Приклад розділювача вертикальної лінії:

Додавши | у заголовок, синтаксичний аналізатор шукатиме труби замість ком, зберігаючи ваш синтаксис чистим.

Складання ключів

Якщо у вас є глибоке вкладення, але лише один шлях даних, вам не потрібно робити відступ п’ять разів. Ви можете використовувати крапкову нотацію (Key Folding), щоб згладити структуру.

Стандартне вкладення:

користувач: 
профіль: 
налаштування: 
сповіщення: 
електронна адреса: правда 
sms: помилка 

Складений (чистіший):

user.profile.settings.notifications: 
електронна адреса: правда 
sms: помилка 

Швидка довідка з типів

TOON зіставляється безпосередньо з типами JSON, але він витончено обробляє специфічні для JavaScript крайові випадки, щоб забезпечити дійсний вихід.

• Числа: зберігаються як канонічні десяткові дроби. "1.0" стає "1".

• Infinity / NaN: Вони стають null (оскільки JSON їх не підтримує).

• Дати: перетворено на рядки ISO в лапках.

• Undefined/Functions: Перетворено на null.

• Порожні об’єкти: представлено як нічого (порожній вихід).

• Порожні масиви: представлено як key[0]:.

TOON — це формат, який винагороджує за точність. Може знадобитися деякий час, щоб звикнути до підрахунку елементів масиву, але виграш у читабельності та розмірі файлу вартий зусиль. Щасливого кодування!