Формат YAML
Дата оновлення перекладу 2024-05-29
Формат YAML
Компонент Symfony Yaml резалізує обраний піднабір функцій, визначених у специфікації YAML версії 1.2.
Скаляри
Синтаксіс для скалярів схожий на с синтаксіс 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
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 коду:
1
['PHP', 'Perl', 'Python'];
Відображення використовують двокрапку з пробілом після неї (:
), щоб
відмітити кожну пару ключ-значення:
1 2 3
PHP: 5.2
MySQL: 5.1
Apache: 2.2.20
що еквівалентно цьому PHP коду:
1
['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 коду:
1 2 3 4 5 6 7 8 9 10
[
'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=
Функції, особливі для Symfony
Компонент Yaml надає деякі додаткові функції, які не є частиною офіційної специфікації YAML, але можуть бути корисними в додатках Symfony:
!php/const
дозволяє отримати значення константи PHP. Цей тег приймає повне ім'я класу константи як свій аргумент:1 2
data: page_limit: !php/const App\Pagination\Paginator::PAGE_LIMIT
!php/object
дозволяє передати серіалізоване представлення PHP об'єкта (створеного за допомогою функції serialize()), яке буде десеріалізовано при парсуванні YAML-файлу:1 2
data: my_object: !php/object 'O:8:"stdClass":1:{s:3:"bar";i:2;}'
!php/enum
дозволяє використовувати випадок зчислення PHP. Цей тег приймає в якості аргументу повне ім'я класу випадку зчислення:1 2 3 4 5
data: # Ви можете використати типований випадок зчислення... operator_type: !php/enum App\Operator\Enum\Type::Or # ... або ви також можете використати "->value", що використати значення випадку BackedEnum напряму operator_type: !php/enum App\Operator\Enum\Type::Or->value
Цей тег дозволяє опустити зчислення і вказати тільки FQCN зчислення для повернення масиву всіх доступних варіантів зчислення:
1 2
data: operator_types: !php/enum App\Operator\Enum\Type
7.1
Підтримка використання зчислення FQCN без вказівки регістру була представлена у Symfony 7.1.
Функції 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: ~}
).