Формат YAML

В соответствии с официальным сайтом YAML, YAML - это "дружелюбный для человека стандарт сериализации данных для всех языков программирования".

Даже если формат YAML может описать сложную структуру вложенных данных, эта статья описывает только минимальный набор функций, необходимых для использования YAML в качестве формата конфигурации файла.

YAML - это простой язык, который описывает данные. Как и PHP, он имеет синтаксис для простых типов вроде строк, белвых значений, float или целых чисел. Но, в отличие от PHP, он различает массивы (последовательности) и хеши (отображения).

Скаляры

Синтаксис для скаляров схож с синтаксисом 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 редко используется для описания обычного скаляра. В большинстве случаев, он описывает коллекцию. Коллекция может быть последовательностью или отображением элементов. И то, и то преобразуется в 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 и не должны иметь отступов в соответствии с текущим уровнем вложения в коллекцию.

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