Вместо предисловия
YAML – это рекурсивный акроним для «YAML Ain’t MarkupLanguage». Это простой для чтения стандарт серилиазации данных для всех языков программирования.
Версии
1.0 2004-01-29
1.1 2005-01-18
1.2 2009-10-01
Примеры
Базовый синтаксис
YAML – это текстовый формат, позволяющий хранить структурированные данные в иерархическом порядке. Он разработан для облегчения чтения оператором и машиной с минимумом накладных расходов. Спецификацию YAML можно найти на yaml.org., там же находится его справочная карта.
Комментарии здесь начинаются с символа «#» и идут до новой строки, они должны быть отделены от других токенов символом пробела. Пробелы не являются свободным местом, а отступы должны представлять собой пробелы, а не табуляции. YAML будет считать, что внутри него содержатся строки с префиксом с большим количеством пробелов, чем у родительского ключа. Причем все строки должны содержать префикс с таким же количеством пробелов, чтобы принадлежать одной карте.
YAML обладает последовательностями и сопоставлениями в качестве типов коллекций, и те, и другие могут быть представлены потоком и в блочном виде. Последовательность скалярных строк в YAML выглядит так:
[ one, two, three ] # flow style
# or block style
– one
– two
– three
Сопоставления содержат пары ключ-значение:
index: 4 # block style
name: nali
# or
{ index: 4, name: nali } # flow style
# or nested (equivalent of { level: { one: { two: fun } } }):
level:
one:
two: fun
Базовые типы YAML
integer: 25
string: “25”
float: 25.0
boolean: true
null type: null
Последовательные данные в YAML
Список уровней одинакового типа:
– Cat
– Dog
– Goldfish
Вложенный список:
–
– Cat
– Dog
– Goldfish
Комментарии
# This comment occupies a whole line
– some item # This comment succeeds content of a line
– http://example.com/#nocomment
– “This # does not introduce a comment.”
– |
This is a block scalar.
A # inside it does not introduce a comment.
# unless it is less indented than the first line (this is one)
«#» предваряет комментарий. Он может появляться вначале строки, либо же идти перед пробелом. После «#» всегда идет пробел. Комментарии никогда не начинаются с «#» внутри скаляров в кавычках . «#» может вводить комментарии в конце скаляров блока, но, в этом случае он должен быть с меньшим отступом, чем базовый отступ блочного скаляра (который обычно определяется отступом его первой непустой линии).
Сопоставления блочного стиля
С неявными ключами:
key: value
another key:
– some
– more
– values
[1, 2, 3]: last value, which has a flow style key
С явными и неявными ключами:
? key
: value
another key:
– some
– more
– values
? [1, 2, 3]
: last value, which has a flow style key
«key», «another key» и «[1, 2, 3]» – это ключи одного и то же сопоставления, несмотря на то, что они используют различные стили ключей.
Вложенные сопоставления:
first level:
second level:
? third level
:
forth level: value of implicit key
? third level, second key
: value of explicit key
?
mapping as: key of
another: mapping
: scalar value of mapping key
first level, second key:
last value
Разделение текстовых строк на несколько строк
- Без кавычек:
Можно просто
разделить длинный кусок текста по примеру этого.
- С кавычками:
“[Будьте аккуратны:
если вам “\нужна\” пунктуация, не ставьте двойные кавычки вокруг нее. Вы можете да\
же разделять без пробелов, используя обратную косую черту.”
- С одинарными кавычками:
‘Это работает
но не на”столько гибко’
- С сохранением символа новой строки «|»:
Тогда делайте
это так с
символом (|). (Такая строка будет иметь три \n символа)
- Если у вас только одна последняя новая строка: «>»
В этой строке будет
только один \n символ в самом конце.
Индикаторы блока. Пользуйтесь «>-», «>+», «|-» и «|+» для более точной настройки.
Символы пропуска
YAML поддерживает три стиля обозначения пропуска:
- Пропуск сущности:
- пробел: “ ”
- двоеточие: “:”
- амперсант: “&”
- Пропуски Unicode:
- пробел: “\u0020”
- одинарная кавычка: “\u0027”
- двойная кавычка: “\u0022”
- Пропуски в кавычках:
- двойная кавычка в одинарной кавычке: ‘Правда ли, что “Я всегда вру” – правдивый аргумент?’
- вложенные двойные кавычки: ” Она сказала: “Я ухожу” “
- Вложенные одинарные кавычки: ‘ He was speechless: ” ‘
Использование анкоров и псевдонимов для включенного контента
Примеры
Создание таблицы «Array of Dictionaries» средставами анкоров YAML как идентификаторов строк
—
person_table:
– &person001
fname: homer
lname: simpson
role: dad
age: 33
– &person002
fname: marge
lname: simpson
role: mom
age: 34
– &person003
fname: peter
lname: griffin
role: dad
age: 34
Проблема: Разработчик хочет представить структуру таблицы в YAML, где где на каждую строку ссылается компактный идентификатор строки.
Решение:
- Использовать анкоры YAML, назначая идентификатор анкора каждой строке в таблице;
- В YAML многоразовые «идентификаторы включения» называются якорями и псевдонимами;
- В YAML многоразовые «идентификаторы включения» состоят из буквенно-цифровых токенов, которым предшествует амперсанд или звездочка.
Обоснование:
- Якоря и псевдонимы YAML позволяют улучшить нормализацию данных;
- Якоря и псевдонимы YAML применяют «DRY» («Don’t repeat yourself», чтобы не повторяться);
- В этом примере можно спроектировать и сохранить структуру таблицы, которая полностью совпадает с с базой данных.
Ловушки:
- Якоря YAML должны быть объявлены до того, как на них можно будет ссылаться с помощью псевдонимов;
- Якоря YAML должны быть уникальными по всему документу;
- Отказ указать уникальные якоря вызовет ошибку в yaml.load ();
- Не все парсеры YAML надежно поддерживают якоря и псевдонимы.
Дополнительную полезную информацию по этому вопросу можно найти здесь.
Использование псевдонимов YAML для перекрестных ссылок на строки из таблицы YAML
—
person_table:
– &person001
fname: homer
lname: simpson
role: dad
age: 33
– &person002
fname: marge
lname: simpson
role: mom
age: 34
– &person003
fname: peter
lname: griffin
role: dad
age: 34
motto_table:
– &motto001
person: *person001
motto: >
D’oh!! YAML is too complicated!
– &motto002
person: *person002
motto: >
Bart! Listen to your father!
– &motto003
person: *person003
motto: >
Hey! YAML is freakin’ sweet!
Проблема: Разработчик хочет сделать перекрестные ссылки на строки с анкорами из одной таблицы и связать их с помощью строк-псевдонимов в другой таблице.
Решение:
- Использовать псевдонимы YAML, которые перекрестно ссылаются на заранее определенные якоря из другой таблицы;
- В YAML многоразовые «идентификаторы включения» называются якорями и псевдонимами;
- В YAML многоразовые «идентификаторы включения» состоят из буквенно-цифровых токенов, которым предшествует амперсанд или звездочка.
Обоснование:
- Якоря и псевдонимы YAML позволяют улучшить нормализацию данных;
- Якоря и псевдонимы YAML применяют DRY (чтобы не повторяться);
- В этом примере можно спроектировать и сохранить структуру таблицы, которая полностью совпадает с с базой данных.
Ловушки:
- В этом конкретном примере yaml.load () будет создавать вложенные словари:
- это называется «nested dictionaries problem» (проблема вложенных словарей);
- в паре имя-значение персоны значение для персоны будет вложенным словарем;
- это может быть нежелательно, поскольку нарушает единообразие структуры таблицы;
- Неправильное указание псевдонимов приведет к отсутствию данных: опечатки приведут к неработающим перекрестным ссылкам;
- YAML не поддерживает включение файлов по ссылке, поэтому должны существовать все псевдонимы и привязки. в том же файле yaml;
- Не все парсеры YAML надежно поддерживают якоря и псевдонимы.
Дополнительную полезную информацию по этому вопросу можно почерпнуть здесь.
Использование ключей слияния YAML для перекрестных ссылок на строки из другой таблицы YAML
—
person_table:
– &person001
fname: homer
lname: simpson
role: dad
age: 33
– &person002
fname: marge
lname: simpson
role: mom
age: 34
– &person003
fname: peter
lname: griffin
role: dad
age: 34
motto_table:
– &motto001
<<: *person001
motto: >
D’oh!! YAML is too complicated!
– &motto002
<<: *person002
motto: >
Bart! Listen to your father!
– &motto003
<<: *person003
motto: >
Hey! YAML is freakin’ sweet!
Проблема:
- Разработчик хочет сделать перекрестные ссылки на строки с привязками из одной таблицы и связать их с помощью строк-псевдонимов в другой таблице;
- Разработчик хочет избежать “проблемы вложенных словарей”.
Решение:
- Использовать псевдонимы YAML с ключами слияния YAML;
- В YAML многоразовые «идентификаторы включения» называются якорями и псевдонимами;
- В YAML многоразовые «идентификаторы включения» состоят из буквенно-цифровых токенов, которым предшествует амперсанд или звездочка.
Обоснование:
- Якоря и псевдонимы YAML позволяют улучшить нормализацию данных;
- Якоря и псевдонимы YAML обеспечивают соблюдение DRY (чтобы не повторяться);
- В этом примере можно спроектировать и сохранить структуру таблицы, которая точно совпадает с базой данных;
- В этом примере ввод данных и размеры файлов могут быть уменьшены.
Ловушки:
- В этом конкретном примере yaml.load () будет создавать вложенные словари:
- в паре имя-значение человека значение для человека будет вложенным словарем;
- это может быть нежелательно, поскольку нарушает единообразие структуры таблицы;
- Неправильное указание псевдонимов приведет к отсутствию данных: опечатки приведут к неработающим перекрестным ссылкам;
- YAML не поддерживает включение файлов по ссылке, поэтому все псевдонимы и якоря должны существовать в том же файле yaml;
- Не все парсеры YAML надежно поддерживают якоря и псевдонимы.
Дополнительную информацию можно почерпнуть здесь и здесь. Также полезно почитать про использование якорей и псевдонимов для транслируемого контента в Интернете здесь.