Формат 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
>
  Это очень длинное предложение,
  которое длится в YAML несколько строчек,
  но которое будет отображено, как строка
  без разрывов.

Note

Отметьте два пробела перед каждой строчкой в предыдущих примерах. Они не будут отображаться в результирующих PHP строках.

Числа

1
2
# целое число
12
1
2
# октальное число
014
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
array('PHP', 'Perl', 'Python');

Отображения используют двоеточие с пробелом после него (: ), чтобы отметить каждую пару ключ-значение:

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

что эквивалентно этому PHP коду:

1
array('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
array(
    'symfony 1.0' => array(
        'PHP'    => 5.0,
        'Propel' => 1.2,
    ),
    'symfony 1.2' => array(
        '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.