Синтаксис YAML

Основы YAML

В Ansible почти каждый файл YAML начинается со списка. Каждый элемент списка представляет собой набор пар ключ/значение, который обычно называют «хешем» или «словарём». Поэтому нам нужно знать, как записывать списки и словари в YAML.

В YAML есть ещё одна небольшая особенность. Все файлы YAML (независимо от того, связаны они с Ansible или нет) могут начинаться с --- и заканчиваться .... Это часть формата YAML, обозначающая начало и конец документа.

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

---
# A list of tasty fruits
- Apple
- Orange
- Strawberry
- Mango
...

Словарь представляется в простой форме key: value (после двоеточия должен идти пробел):

# An employee record
martin:
  name: Martin D'vloper
  job: Developer
  skill: Elite

Возможны и более сложные структуры данных, например списки словарей, словари со списками в качестве значений или сочетание того и другого:

# Employee records
- martin:
    name: Martin D'vloper
    job: Developer
    skills:
      - python
      - perl
      - pascal
- tabitha:
    name: Tabitha Bitumen
    job: Developer
    skills:
      - lisp
      - fortran
      - erlang

При желании словари и списки можно записывать и в сокращённой форме:

---
martin: {name: Martin D'vloper, job: Developer, skill: Elite}
fruits: ['Apple', 'Orange', 'Strawberry', 'Mango']

Они называются «потоковыми коллекциями».

В Ansible они используются нечасто, но также можно указывать логическое значение (true/false) в нескольких формах:

create_key: true
needs_agent: false
knows_oop: True
likes_emacs: TRUE
uses_cvs: false

Чтобы обеспечить совместимость со стандартными настройками yamllint, используйте строчные ‘true’ или ‘false’ для логических значений в словарях.

Значения могут занимать несколько строк с помощью | или >. При переносе на несколько строк с помощью «литерального блочного скаляра» | сохраняются символы новой строки и все завершающие пробелы. «Свёрнутый блочный скаляр» > преобразует символы новой строки в пробелы; его используют, чтобы длинную строку было проще читать и редактировать. В обоих случаях отступы игнорируются. Например:

include_newlines: |
            exactly as you see
            will appear these three
            lines of poetry

fold_newlines: >
            this is really a
            single line of text
            despite appearances

Хотя в приведённом выше примере с > все символы новой строки преобразуются в пробелы, есть два способа сохранить символ новой строки:

fold_some_newlines: >
    a
    b

    c
    d
      e
    f

Кроме того, это можно обеспечить, добавив символы новой строки \n:

fold_same_newlines: "a b\nc d\n  e\nf\n"

Объединим всё, что мы узнали, в произвольном примере YAML. Он не имеет отношения к Ansible, но поможет вам почувствовать особенности этого формата:

---
# An employee record
name: Martin D'vloper
job: Developer
skill: Elite
employed: True
foods:
  - Apple
  - Orange
  - Strawberry
  - Mango
languages:
  perl: Elite
  python: Elite
  pascal: Lame
education: |
  4 GCSEs
  3 A-Levels
  BSc in the Internet of Things

Этого достаточно, чтобы начать писать плейбуки Ansible.

Подводные камни

Хотя в скаляр без кавычек можно поместить почти что угодно, есть некоторые исключения. Двоеточие, за которым следует пробел (или символ новой строки), ": " обозначает начало отображения. Пробел, за которым следует знак решётки " #", начинает комментарий.

Поэтому следующий пример приведёт к ошибке синтаксиса YAML:

foo: somebody said I should put a colon here: so I did

windows_drive: c:

…а этот вариант будет работать:

windows_path: c:\windows

Значения, содержащие двоеточие с последующим пробелом или концом строки, следует заключать в кавычки:

foo: 'somebody said I should put a colon here: so I did'

windows_drive: 'c:'

…тогда двоеточие будет сохранено.

Кроме того, можно использовать двойные кавычки:

foo: "somebody said I should put a colon here: so I did"

windows_drive: "c:"

Разница между одинарными и двойными кавычками заключается в том, что в двойных кавычках можно использовать escape-последовательности:

foo: "a \t TAB and a \n NEWLINE"

Список допустимых escape-последовательностей можно найти в спецификации YAML в разделе «Escape Sequences» (YAML 1.1) или «Escape Characters» (YAML 1.2).

Следующий пример не является допустимым YAML:

foo: "an escaped \' single quote"

Кроме того, Ansible использует «{{ var }}» для переменных. Если значение после двоеточия начинается с «{», YAML воспримет его как словарь, поэтому его нужно заключить в кавычки, например:

foo: "{{ variable }}"

Если значение начинается с кавычки, в кавычки нужно заключить всё значение, а не только его часть. Вот ещё несколько примеров правильного использования кавычек:

foo: "{{ variable }}/additional/string/literal"
foo2: "{{ variable }}\\backslashes\\are\\also\\special\\characters"
foo3: "even if it is just a string literal it must all be quoted"

Неверно:

foo: "E:\\path\\"rest\\of\\path

Помимо ' и " есть ряд специальных (или зарезервированных) символов, которые нельзя использовать в качестве первого символа скаляра без кавычек: [] {} > | * & ! % # ` @ ,.

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

В потоковых коллекциях правила немного строже:

a scalar in block mapping: this } is [ all , valid

flow mapping: { key: "you { should [ use , quotes here" }

Преобразование логических значений полезно, но может создать проблему, если вам нужно представить строкой литерал yes или другие логические значения. В таких случаях просто используйте кавычки:

non_boolean: "yes"
other_string: "False"

YAML преобразует некоторые строки в числа с плавающей точкой, например строку 1.0. Если нужно указать номер версии (например, в файле requirements.yml), заключите значение в кавычки, если оно похоже на число с плавающей точкой:

version: "1.0"