Синтаксис YAML

Основы YAML

Практически каждый YAML-файл для Ansible начинается со списка. Каждый элемент в списке представляет собой список пар ключ-значение, обычно называемый «хешем» или «словарём». Поэтому нам нужно знать, как записывать списки и словари в 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 не использует их слишком часто, но вы также можете указать булево значение (истина/ложь) в нескольких формах:

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

Для булевых значений в словарях используйте строчные «true» или «false», если вы хотите обеспечить совместимость с параметрами yamllint по умолчанию.

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

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 playbooks.

Особенности

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

Из-за этого следующее приведёт к ошибке синтаксиса 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:"

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

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

Список разрешённых экранирований можно найти в спецификации YAML в разделе «Последовательности экранирования» (YAML 1.1) или «Символы экранирования» (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"