Дата оновлення перекладу 2022-05-03

Формат YAML

Відповідно офіційному сайту YAML, YAML - це “дружній для людини стандарт серіалізації даних для всіх мов програмування”. Компонент Symfony Yaml реалізує піднабір специфікації YAML. В особливості, він реалізує мінімальний набір функцій, необхідних для використання YAML у якості формату конфігурації файлу.

Скаляри

Синтаксіс для скалярів схожий на с синтаксіс PHP.

Рядки

Рядки в YAML можуть бути укладені як в одинарні так і подвійні лапки. В деяких випадках, вони також можуть бути без лапок:

1
2
3
4
5
Строка в YAML

'Рядок в одинарних лапках в YAML'

"Рядок в подвійних лапках в YAML"

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

При використанні рядків з одинарними лапками, будь-які лапки всередині їх змісту мають бути продубльовані для екранування:

1
'Одинарні лапки '' всередині рядку з одинарними лапками'

Рядки, що містять будь-які з наступних символів, мають бути в лапках. Незважаючи на те, що ви можете використовувати подвійні лапки, для цих символів зручніше використовувати одинарні, що допомагає уникнути екранування зворотнього слешу \:

  • :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `

Стиль подвійних лапок надає спосіб виразити довільні рядки, використовуючи \ для екранування символів та послідовностей. Наприклад, це дуже корисно, коли вам необхідно вбудувати \n або символ Unicode в рядок.

1
"Рядок з подвійними лапками в YAML\n"

Якщо рядок містить будь-які з наступних символів управління, він має бути екранований подвійними лапками:

  • \0, \x01, \x02, \x03, \x04, \x05, \x06, \a, \b, \t, \n, \v, \f, \r, \x0e, \x0f, \x10, \x11, \x12, \x13, \x14, \x15, \x16, \x17, \x18, \x19, \x1a, \e, \x1c, \x1d, \x1e, \x1f, \N, \_, \L, \P

Нарешті, існують інші випадки, коли рядки повинні мати лапки, незалежно від того, ви використовуєте подвійні чи одинарні:

  • Коли рядок - true або false (інакше він буде розглянутий як булеве значення);
  • Коли рядок - null або ~ (інакше він буде розглянутий, як значення null);
  • Коли рядок виглядає як число, наприклад ціле число (наприклад, 2, 14, і т.д.), плаваюче число (наприклад, 2.6, 14.9) та експоненційне число (наприклад, 12e7 і т.д.) (інакше він буде розглянутий, як числове значення);
  • Коли рядок виглядає як дата (наприклад, 2014-12-31) (інакше він буде автоматично перетворений у часову відмітку Unix).

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

1
2
3
|
  \/ /| |\/| |
  / / | |  | |__

Як варіант, рядки можуть бути написані в згорнутому стилі, відміченому >, де кожний розрив рядку замінюється пробілом:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
>
  Це дуже довге речення, яке розтягується в YAML
  на декілька рядків.

# Це буде розібрано наступним чином: (відмітьте завершальний \n)
# "Це дуже довге речення, яке розтягується в YAML на декілька рядків.\n"

>-
  Це дуже довге речення, яке розтягується в YAML
  на декілька рядків.

# Це буде розібрано наступним чином: (без завершального \n)
# "Це дуже довге речення, яке розтягується в YAML на декілька рядків."

Note

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

Числа

1
2
# ціле число
12
1
2
# октальне число
0o14

Deprecated since version 5.1: В YAML 1.1, октальні числа використовують нотацію 0..., в той час як в YAML 1.2 нотація змінюється на 0o.... Symfony 5.1 додала підтримку для нотації YAML 1.2 та відмовіилася від підтримки нотації YAML 1.1.

1
2
# шістнадцяткове число
0xC
1
2
# плаваюче число
13.4
1
2
# експоненційне число
1.2e+34
1
2
# нескінченність
.inf

Null

Null в YAML можуть бути виражені за допомогою null або ~.

Булеві значення

Булеві значення в YAML виражені за допомогою true та false.

Дати

YAML використовує стандарт ISO-8601 для виразу дат:

1
2001-12-14T21:59:43.10-05:00
1
2
# проста дата
2002-12-14

Колекції

Файл YAML рідко використовується для опису звичайного скаляру. В більшості випадків, він описує колекцію. Колекції YAML можуть бути послідовністю (індексовані масиви в PHP) або відображенням елементів (асоціативні масиви в PHP).

Послідовності використовують дефіс з пробілом після нього:

1
2
3
- PHP
- Perl
- Python

Попередній файл YAML еквівалентний наступному PHP коду:

['PHP', 'Perl', 'Python'];

Відображення використовують двокрапку з пробілом після неї (:), щоб відмітити кожну пару ключ-значення:

1
2
3
PHP: 5.2
MySQL: 5.1
Apache: 2.2.20

що еквівалентно цьому PHP коду:

['PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20'];

Note

У відображенні ключ може бути будь-яким валідним скаляром.

Кількість пробілів між двокрапкою та значенням не має різниці:

1
2
3
PHP:    5.2
MySQL:  5.1
Apache: 2.2.20

YAML використовує відступ з одним або більше пробілами для опису вкладених колекцій:

1
2
3
4
5
6
'symfony 1.0':
  PHP:    5.0
  Propel: 1.2
'symfony 1.2':
  PHP:    5.2
  Propel: 1.3

Вищеописаний YAML еквівалентний наступному PHP коду:

[
    'symfony 1.0' => [
        'PHP'    => 5.0,
        'Propel' => 1.2,
    ],
    'symfony 1.2' => [
        'PHP'    => 5.2,
        'Propel' => 1.3,
    ],
];

Вам необхідно пам’ятати одну важливу річ при використанні відступів в файлі YAML: Відступ має бути зроблений одним або більше пробілами, але не табулятором.

Вы можете вкладывать последовательности и отображения так, как вам хочется:

1
2
3
4
5
6
'Chapter 1':
  - Introduction
  - Event Types
'Chapter 2':
  - Introduction
  - Helpers

YAML може також використовувати вільні стилі для колекцій, використовуючи повні індикатори, а не відступи, для вказування спектру.

Послідовність може бути написана у вигляді переліку в квадратних дужках ([]), розділеного комами:

1
[PHP, Perl, Python]

Відображення може бути написане у вигляді переліку ключей / значень у фігурниих дужках ({}), розділеного комами:

1
{ PHP: 5.2, MySQL: 5.1, Apache: 2.2.20 }

Ви можете змішувати та поєднувати стилі для досягнення кращої читаності:

1
2
'Chapter 1': [Introduction, Event Types]
'Chapter 2': [Introduction, Helpers]
1
2
'symfony 1.0': { PHP: 5.0, Propel: 1.2 }
'symfony 1.2': { PHP: 5.2, Propel: 1.3 }

Коментарі

Коментарі можуть бути додані в YAML за допомогою префіксу у вигляді хешу (#):

1
2
3
# Коментар до рядку
"symfony 1.0": { PHP: 5.0, Propel: 1.2 } # Коментар наприкінці рядка
"symfony 1.2": { PHP: 5.2, Propel: 1.3 }

Note

Коментарі просто ігноруються аналізатором YAML і не повинні мати відступів відповідно поточному рівню вкладення в колекцію.

Чітке типізування

Специфікація YAML визначає деякі теги для чіткої установки типу будь-яких даних:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
данные:
    # це значення аналізується як рядок (не перетворюється в дату та час)
    start_date: !!str 2002-12-14

    # це значення аналізується як плаваюче число (буде 3.0 замість 3)
    price: !!float 3

    # це значення аналізується як бінарні дані, закодовані в base64
    picture: !!binary |
        R0lGODlhDAAMAIQAAP//9/X
        17unp5WZmZgAAAOfn515eXv
        Pz7Y6OjuDg4J+fn5OTk6enp
        56enmleECcgggoBADs=

Функції YAML, які не підтримуються

Наступні функції YAML не підтримуються компонентом Symfony Yaml:

  • Мульти-документи (маркери --- та ...);
  • Складні ключі маршрутизації, складні значення, що починаються з ?;
  • Значення, теговані як ключі;
  • Наступні теги та типи: !!set, !!omap, !!pairs, !!set, !!seq, !!bool, !!int, !!merge, !!null, !!timestamp, !!value, !!yaml;
  • Теги (директива TAG; наприклад: %TAG ! tag:example.com,2000:app/) та посилання на теги (наприклад: !<tag:example.com,2000:app/foo>);
  • Використання послідованого синтаксису для елементів маршрутизації (наприклад: {foo, bar}; замість цього використовуйте {foo: ~, bar: ~}).

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.