Руководство для начинающих yaml

Lists in YAML

Lists, sequences, collections — represents a collection of an ordered data where each element can be accessed by its index.

For example:

# SIMPLE LIST- element1- element2

Nested lists in YAML

Similarly to the examples above — lists can include nested lists:

# SIMPLE LIST- element1- element2# nested list-  - element1

Or can be a named list:

---itemname:  - valuename

In doing so lists can also contain scalars or dictionaries:

---itemname:  - valuename  - scalar: "value"  - dict: {item1: "value1", item2: "value2"}

Lists — YAML vs JSON

List in YAML:

---- item1- item2- item3

List in JSON:

Nested list in YAML:

---- item1- item2- item3-  - nested1

Nested list in JSON:

Python and YAML-lists

Here are all similar to scalar’s example:

Эквивалентная нотация

В YAML есть много эквивалентных способов описания:

Тут несколько слов предостережения:

Это интерпретируется как . Писать надо или .

В общем, я рекомендую использовать и точно так же, как для булевых значений в JSON, но YAML поддерживает одиннадцать способов записи булевых значений. При желании применить кавычки для строк я бы также рекомендовал пользоваться , как в JSON. Запомнить “no” все равно нужно, но, по крайней мере, для новичков в YAML файл будет выглядеть более привычно.

Есть и другие примеры, которые столь же коварны:

отображается на , так как ведущий ноль запускает восьмеричную нотацию.
отображается на . Мне сообщали, что это значение автоматически преобразуется в секунды, поскольку интерпретируется как длительность: 4*60 + 30 = 270 . Интересно, что этот паттерн до сих пор работает с .

ruamel.yaml

ruamel.yaml is a YAML 1.2 loader/dumper package for Python.

documentation:
version:	0.17.17
updated:	2021-10-31
repository:
pypi:

The 0.16.13 release was the last that was tested to be working on Python 2.7.
The 0.17 series will still be tested on Python 3.5, but the 0.18 will not. The
0.17 series will also stop support for the old PyYAML functions, so a `YAML()` instance
will need to be created.

The 0.17 series will also see changes in how comments are attached during
roundtrip. This will result in backwards incompatibilities on the `.ca` data and
it might even be necessary for documented methods that handle comments.

Please adjust your dependencies accordingly if necessary. (`ruamel.yaml<0.17`)

Starting with version 0.15.0 the way YAML files are loaded and dumped
has been changing, see the API doc for details. Currently existing
functionality will throw a warning before being changed/removed.
For production systems already using a pre 0.16 version, you should
pin the version being used with «ruamel.yaml<=0.15« if you cannot
fully test upgrading to a newer version. For new usage
pin to the minor version tested ( ruamel.yaml<=0.17) or even to the
exact version used.

New functionality is usually only available via the new API, so
make sure you use it and stop using the ruamel.yaml.safe_load(),
ruamel.yaml.round_trip_load() and ruamel.yaml.load() functions
(and their ….dump() counterparts).

Теги документа YAML и типы Python.

Теги используются для обозначения типа узла YAML. Стандартные теги YAML определены в http://yaml.org/type/index.html.

Теги могут быть неявными:

# YAML
boolean true
integer 3
float 3.14

# Python
{'boolean' True, 'integer' 3, 'float' 3.14}

А могут быть явными:

# YAML
boolean !!bool "true"
integer !!int "3"
float !!float "3.14"

# Python
{'boolean' True, 'integer' 3, 'float' 3.14}

В следующей таблице описывается, как узлы с разными тегами преобразуются в объекты Python.

Тэг YAML	Тип Python
Стандартный тэг YAML











Специфичные для Python теги












Сложные теги Python

Функции и модули.

Чтобы представить статические объекты Python, такие как функции или классы, необходимо использовать сложный тег .

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

!!python/name:yaml.dump

Аналогично, модули представляются с помощью тега :

!!python/module:yaml

Пользовательские объекты Python.

Любой сериализуемый объект может быть сериализован с помощью тега :

!!python/object:module.Class { attribute value, ... }

Для поддержки протокола pickle предусмотрены две дополнительные формы тега :

!!python/object/new:module.Class
args argument, ...
kwds {key value, ...}
state ...
listitems item, ...
dictitems key value, ...

!!python/object/apply:module.function
args argument, ...
kwds {key value, ...}
state ...
listitems item, ...
dictitems key value, ...

Если только поле непустое, то вышеприведенные записи можно сократить:

!!python/object/new:module.Class argument, ...

!!python/object/apply:module.function argument, ...

Синтаксис YAML¶

Как и Python, YAML использует отступы для указания структуры документа.
Но в YAML можно использовать только пробелы и нельзя использовать знаки
табуляции.

Еще одна схожесть с Python: комментарии начинаются с символа # и
продолжаются до конца строки.

Список

Список может быть записан в одну строку:

switchport mode access, switchport access vlan, switchport nonegotiate, spanning-tree portfast, spanning-tree bpduguard enable

Или каждый элемент списка в своей строке:

- switchport mode access
- switchport access vlan
- switchport nonegotiate
- spanning-tree portfast
- spanning-tree bpduguard enable

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

Словарь также может быть записан в одну строку:

{ vlan 100, name IT }

Или блоком:

vlan 100
name IT

Строки

Строки в YAML не обязательно брать в кавычки. Это удобно, но иногда всё
же следует использовать кавычки. Например, когда в строке используется
какой-то специальный символ (специальный для YAML).

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

command "sh interface | include Queueing strategy:"

Чтение файлов

В этом разделе мы увидим, как читать файлы YAML в Python. Начнем с создания двух файлов в формате YAML.

Содержимое первого файла выглядит следующим образом:

# fruits.yaml file

apples: 20
mangoes: 2
bananas: 3
grapes: 100
pineapples: 1

Содержимое второго файла выглядит следующим образом:

# categories.yaml file

sports:

  - soccer
  - football
  - basketball
  - cricket
  - hockey
  - table tennis

countries:

  - Pakistan
  - USA
  - India
  - China
  - Germany
  - France
  - Spain

Вы можете видеть, что файлы fruit.yaml и category.yaml содержат разные типы данных. Первый содержит информацию только об одном объекте, то есть о фруктах, а второй содержит информацию о видах спорта и странах.

Давайте теперь попробуем прочитать данные из двух файлов, которые мы создали с помощью скрипта Python. Метод load() из модуля yaml можно использовать для чтения файлов YAML. Взгляните на следующий скрипт:

# process_yaml.py file

import yaml

with open(r'E:\data\fruits.yaml') as file:
    # The FullLoader parameter handles the conversion from YAML
    # scalar values to Python the dictionary format
    fruits_list = yaml.load(file, Loader=yaml.FullLoader)

    print(fruits_list)

Вывод:

{ 'apples': 20, 'mangoes': 2, 'bananas': 3, 'grapes': 100, 'pineapples': 1 }

В приведенном выше скрипте мы указали yaml.FullLoader в качестве значения для параметра Loader, который загружает полный язык YAML, избегая выполнения произвольного кода. Вместо использования функции загрузки и последующей передачи yaml.FullLoader в качестве значения параметра Loader вы также можете использовать функцию full_load(), как мы увидим в следующем примере.

Давайте теперь попробуем прочитать второй файл YAML аналогичным образом, используя скрипт Python:

# read_categories.py file

import yaml

with open(r'E:\data\categories.yaml') as file:
    documents = yaml.full_load(file)

    for item, doc in documents.items():
        print(item, ":", doc)

Поскольку в файле category.yaml 2 документа, мы выполнили цикл, чтобы прочитать их оба.

Вывод:

sports : 
countries :

Как видно из последних двух примеров, библиотека автоматически обрабатывает преобразование данных в формате YAML в словари и списки Python.

Scalars

Basic data type — scalars, just a key:value as programming variables:

---key1: "value1"key2: "value2"

Using quotes for values recommended to avoid possible issues with special characters:

$ cat example.yml---key1: “value1”key2: “value2”key3: %value3

Validate it:

$ yamllint example.ymlexample.yml4:7 error syntax error: found character ‘%’ that cannot start any token

Still, you can skip quotes for boolean true/false values and for integer types.

Scalars — YAML vs JSON

For example — scalar in YAML:

---key: "value"

And JSON:

{    "key": "value"}

Python

The YAML-scalars in Python example:

>>> import yaml>>> yaml.load("""… key: “value”… """){'key': 'value'}

Or from a file:

Examples of YAML

By integrating their software with YAML, Red Hat developed Ansible, an open source software provisioning, configuration management, and application deployment tool. Ansible temporarily connects to servers via Secure Shell (SSH) to perform management tasks using playbooks which are blocks of YAML code that automate manual tasks.

In the example below, the playbook has been defined.

This job indicates that it should only be run on the hosts in the webservers group and that the job should be run as the remote user, root. There are three tasks in this playbook:

The first task updates Apache to the latest version using Red Hat’s yum command.
The second task uses template to copy over the apache configuration file. Once the configuration file is written, the Apache service is restarted.
The third task starts the Apache service, just in case it did not come back up.

Now that the playbook has been written, it has to be run from the command line. Although the paths will vary based on the environment, the playbook can be run using this command:

ansible-playbook -i hosts/groups verify_apache.yml

The option indicates which file contains the list of servers in the webservers group, which will limit the servers the playbook executes on.

Разметка документа YAML.

Разметка документа YAML начинается с тройного тире . Значения могут быть любого типа: например, номер телефона является числовым, а имя пользователя — строковым. Отступ используется для обозначения вложенности элементов внутри последовательности. Дефис предшествует каждому вложенному внутри элементу. Комментарии в YAML начинаются с символа (как в Python). Документ YAML заканчивается необязательным тремя точками , также он может иметь несколько документов внутри одного файла YAML.

Пример явного документа YAML:

# Документ YAML начинается с ---
# Комментарии начинаются с #
---
  UserName Alicia
  Password pinga123* 
  phone (495) 555-32-56
  room 10
  TablesList
        - EmployeeTable
        - SoftwaresList
        - HardwareList 
...

Пример неявного документа YAML:

UserName Alicia
Password pinga123* 
phone (495) 555-32-56
room 10
TablesList
      - EmployeeTable
      - SoftwaresList
      - HardwareList

Пример нескольких документов в одном файле :

---
- Ada
- APL
- ASP

- Assembly
- Awk
---
- Basic
---
- C
- C#    # Note that comments are denoted with ' #' (space then #).
- C++
- Cold Fusion
...

Lists in YAML

Lists, sequences, collections — represents a collection of an ordered data where each element can be accessed by its index.

For example:

# SIMPLE LIST- element1- element2

Nested lists in YAML

Similarly to the examples above — lists can include nested lists:

# SIMPLE LIST- element1- element2# nested list-  - element1

Or can be a named list:

---itemname:  - valuename

In doing so lists can also contain scalars or dictionaries:

---itemname:  - valuename  - scalar: "value"  - dict: {item1: "value1", item2: "value2"}

Lists — YAML vs JSON

List in YAML:

---- item1- item2- item3

List in JSON:

Nested list in YAML:

---- item1- item2- item3-  - nested1

Nested list in JSON:

Python and YAML-lists

Here are all similar to scalar’s example:

Синтаксис YAML

В YAML есть несколько основных концепций, которые составляют большую часть данных.

Пары ключ-значение

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

Скаляры и отображение

Скаляры представляют собой одно сохраненное значение. Скаляры назначаются именам клавиш с помощью сопоставления. Вы определяете сопоставление с именем, двоеточием и пробелом, а затем значением, которое оно должно содержать.

YAML поддерживает общие типы, такие как целые числа и числовые значения с плавающей запятой, а также нечисловые типы Логическое и строковое.

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

String

Строки — это набор символов, представляющих предложение или фразу. Вы либо используете , чтобы печатать каждую строку как новую строку, либо , чтобы печатать ее как абзац.

Строки в YAML не обязательно заключать в двойные кавычки.

Последовательность

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

Блочный стиль использует пробелы для структурирования документа. Его легче читать, но он менее компактен по сравнению со стилем потока.

Стиль потока позволяет записывать последовательности в строке с использованием квадратных скобок, аналогично объявлению массива в таких языках программирования, как Python или JavaScript. Стиль потока более компактен, но его труднее читать с первого взгляда.

Словари

Словари — это коллекции пар «ключ-значение», все вложенные в одну и ту же подгруппу. Они помогают разделить данные на логические категории для последующего использования.

Словари определяются как сопоставления: вы вводите имя словаря, двоеточие и пробел, за которыми следует 1 или несколько клавиш с отступом — пары значений.

Gotchas

While you can put just about anything into an unquoted scalar, there are some exceptions.
A colon followed by a space (or newline) is an indicator for a mapping.
A space followed by the pound sign starts a comment.

Because of this, the following is going to result in a YAML syntax error:

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

windows_drive c

…but this will work:

windows_path c:\windows

You will want to quote hash values using colons followed by a space or the end of the line:

foo 'somebodysaidIshouldputacolonhere:soIdid'

windows_drive 'c:'

…and then the colon will be preserved.

Alternatively, you can use double quotes:

foo "somebodysaidIshouldputacolonhere:soIdid"

windows_drive "c:"

The difference between single quotes and double quotes is that in double quotes
you can use escapes:

foo "a\tTABanda\nNEWLINE"

The list of allowed escapes can be found in the YAML Specification under “Escape Sequences” (YAML 1.1) or “Escape Characters” (YAML 1.2).

The following is invalid YAML:

foo: "an escaped \' single quote"

Further, Ansible uses “` var `” for variables. If a value after a colon starts
with a “{“, YAML will think it is a dictionary, so you must quote it, like so:

foo "{{ variable }}"

If your value starts with a quote the entire value must be quoted, not just part of it. Here are some additional examples of how to properly quote things:

foo "{{ variable }}/additional/string/literal"
foo2 "{{ variable }}\\backslashes\\are\\also\\special\\characters"
foo3 "evenifit'sjustastringliteralitmustallbequoted"

Not valid:

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

In addition to and there are a number of characters that are special (or reserved) and cannot be used
as the first character of an unquoted scalar: .

You should also be aware of . In YAML, they are allowed at the beginning of a string if a non-space
character follows, but YAML processor implementations differ, so it’s better to use quotes.

In Flow Collections, the rules are a bit more strict:

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

flow mapping { key "you{shoulduse,quoteshere" }

Boolean conversion is helpful, but this can be a problem when you want a literal yes or other boolean values as a string.
In these cases just use quotes:

non_boolean "yes"
other_string "False"

YAML converts certain strings into floating-point values, such as the string
1.0. If you need to specify a version number (in a requirements.yml file, for
example), you will need to quote the value if it looks like a floating-point
value:

version "1.0"

YAML syntax validation

To check YAML syntax in Linux the can be used.

Install it:

$ sudo pacman -S yamllint

And check file:

$ yamllint monitoring.ymlmonitoring.yml1:1 warning missing document start “ — -” (document-start)20:34 error trailing spaces (trailing-spaces)22:32 error trailing spaces (trailing-spaces)23:37 error trailing spaces (trailing-spaces)33:7 error wrong indentation: expected 8 but found 6 (indentation)35:9 error wrong indentation: expected 10 but found 8 (indentation)36:11 error wrong indentation: expected 12 but found 10 (indentation)

Alsothuht this file used by Ansible without any problems — there are still some issues in its formatting.

Разметка списков в документе YAML.

В контексте блока, элементы списков обозначаются через тире , а затем пробел:

# YAML
- The Dagger 'Narthanc'
- The Dagger 'Nimthanc'
- The Dagger 'Dethanc'

# Python
"TheDagger'Narthanc'", "TheDagger'Nimthanc'", "TheDagger'Dethanc'"

Последовательности блоков могут быть вложенными:

# YAML
-
  - HTML
  - LaTeX
  - SGML
  - VRML
  - XML
  - YAML
-
  - BSD
  - GNU Hurd
  - Linux

# Python

   'HTML', 'LaTeX', 'SGML', 'VRML', 'XML', 'YAML'], 
   'BSD', 'GNUHurd', 'Linux'

Нет необходимости начинать вложенную последовательность с новой строки:

# YAML
- 1.1
- - 2.1
  - 2.2
- - - 3.1
    - 3.2
    - 3.3

# Python
1.1, 2.1, 2.2], ]]

Последовательность блоков может быть вложена в словарь блоков

Обратите внимание, что в этом случае нет необходимости делать отступы для блока с последовательностью

# YAML
left hand
- Ring of Teleportation
- Ring of Speed

right hand
- Ring of Resist Fire
- Ring of Resist Cold
- Ring of Resist Poison

# Python
{
    'righthand' 'RingofResistFire', 'RingofResistCold', 'RingofResistPoison'],
    'lefthand' 'RingofTeleportation', 'RingofSpeed'
}

Пример 2. Чтение содержимого из файла YAML

В данном примере мы будем использовать файл client.yaml, созданный ранее.

Напишем следующий код для чтения отсортированного на основе ключей содержимого файла client.yaml .

Функция используется для чтения полного содержимого нашего файла. Эта функция вернет содержимое файла в виде списка словарей Python. Затем функция преобразует список в поток YAML, который мы после выведем в консоль.

# Import YAML module

import yaml

# Load YAML data from the file

with open('client.yaml') as fh:
    read_data = yaml.load(fh, Loader=yaml.FullLoader)

# Print YAML data before sorting

print(read_data)

# Sort YAML data based on keys

sorted_data = yaml.dump(read_data)

# Print YAML data after sorting

print(sorted_data)

При запуске этого кода получим следующий вывод:

- email: kamal@gmail.com
  mobile: 01843456790
  name: Kamal Hossain
- email: sakil@gmail.com
  mobile: 1858717459
  name: Sakil Ahamed
- email: mizan@gmail.com
  mobile: 01936784534
  name: Mizanur Rahman

После преобразования содержимого файла client.yaml в список словарей Python каждый словарь был преобразован в элемент YAML-контента, как и в предыдущем примере. Значение параметра функции по умолчанию — . Поэтому в выводе мы видим контент YAML, отсортированный по ключам.

Lists in YAML

Lists, sequences, collections — represents a collection of an ordered data where each element can be accessed by its index.

For example:

# SIMPLE LIST- element1- element2

Nested lists in YAML

Similarly to the examples above — lists can include nested lists:

# SIMPLE LIST- element1- element2# nested list-  - element1

Or can be a named list:

---itemname:  - valuename

In doing so lists can also contain scalars or dictionaries:

---itemname:  - valuename  - scalar: "value"  - dict: {item1: "value1", item2: "value2"}

Lists — YAML vs JSON

List in YAML:

---- item1- item2- item3

List in JSON:

Nested list in YAML:

---- item1- item2- item3-  - nested1

Nested list in JSON:

Python and YAML-lists

Here are all similar to scalar’s example:

Работа с YAML

С YAML легче работать, потому что он удаляет скобки запятые, которые мешают чтению контента.

Сам сайт YAML написан с использованием YAML, который, как можно сразу увидеть, не предназначен для кодирования веб-страниц.

YAML — это попытка создать более удобный для восприятия формат обмена данными. Он похож на JSON (который на самом деле является подмножеством YAML), но использует пробелы, двоеточия и дефисы для обозначения структуры.

Многие компьютеры принимают данные в формате YAML или JSON. Этот синтаксис обычно используется в файлах конфигурации и во все большем количестве платформ (например, Jekyll), поэтому рекомендуется его знать.

Scalars

Basic data type — scalars, just a key:value as programming variables:

---key1: "value1"key2: "value2"

Using quotes for values recommended to avoid possible issues with special characters:

$ cat example.yml---key1: “value1”key2: “value2”key3: %value3

Validate it:

$ yamllint example.ymlexample.yml4:7 error syntax error: found character ‘%’ that cannot start any token

Still, you can skip quotes for boolean true/false values and for integer types.

Scalars — YAML vs JSON

For example — scalar in YAML:

---key: "value"

And JSON:

{    "key": "value"}

Python

The YAML-scalars in Python example:

>>> import yaml>>> yaml.load("""… key: “value”… """){'key': 'value'}

Or from a file:

Модуль PyYAML¶

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

pip install pyyaml

Работа с ним аналогична модулям csv и json.

Чтение из YAML

Попробуем преобразовать данные из файла YAML в объекты Python.

Файл info.yaml:

- BS 1550
  IT 791
  id 11
  name Liverpool
  to_id 1
  to_name LONDON
- BS 1510
  IT 793
  id 12
  name Bristol
  to_id 1
  to_name LONDON
- BS 1650
  IT 892
  id 14
  name Coventry
  to_id 2
  to_name Manchester

Чтение из YAML (файл yaml_read.py):

import yaml
from pprint import pprint

with open('info.yaml') as f
    templates = yaml.safe_load(f)

pprint(templates)

Результат:

$ python yaml_read.py

Формат YAML очень удобен для хранения различных параметров, особенно,
если они заполняются вручную.

Запись в YAML

Запись объектов Python в YAML (файл yaml_write.py):

import yaml

trunk_template = 
    'switchport trunk encapsulation dot1q', 'switchport mode trunk',
    'switchport trunk native vlan 999', 'switchport trunk allowed vlan'


access_template = 
    'switchport mode access', 'switchport access vlan',
    'switchport nonegotiate', 'spanning-tree portfast',
    'spanning-tree bpduguard enable'


to_yaml = {'trunk' trunk_template, 'access' access_template}

with open('sw_templates.yaml', 'w') as f
    yaml.dump(to_yaml, f, default_flow_style=False)

with open('sw_templates.yaml') as f
    print(f.read())

Файл sw_templates.yaml выглядит таким образом:

access
- switchport mode access
- switchport access vlan
- switchport nonegotiate
- spanning-tree portfast
- spanning-tree bpduguard enable
trunk
- switchport trunk encapsulation dot1q
- switchport mode trunk
- switchport trunk native vlan 999
- switchport trunk allowed vlan

Literal Block Scalar

YAML supports the ability to add multiline literal block scalars and has three types of it: the common one, using the “» and the «».

The common format looks like:

---string: This    is    some text    without newlines

Results in Python console:

>>> yaml.load(open(‘yaml-example.yml’)){‘string’: ‘This is some text without newlines’}

Using the | ( — will save all newlines and closing spaces:

---string: |    This    is    some text    with newlines

Result is:

>>> yaml.load(open(‘yaml-example.yml’)){‘string’: ‘This\nis\nsome text\nwith newlines\n’}

And using the > ():

---string: >    This    is    some text    without newlines

Will return whole text in one line + closing newline symbol:

>>> yaml.load(open(‘yaml-example.yml’)){‘string’: ‘This is some text without newlines\n’}

But still, you have to adhere to the same spaces formatting.

Also, check the great answer on the StackOverflow here>>>:

Dictionaries

Dictionaries, also called mappings is similar to scalars type and contains a key:value data but unlike scalars which are basic type — dictionary can include nested elements, for example, a list:

---key1: "value1"key2:  - value2  - value3

Or another nested dictionary:

---key1: "value1"key2:  - value2  - value3key3:  key4: "value4"  key5: "value5"  key6:    key7: "value7"

Dictionary — JSON vs YAML

Dictionary in YAML:

---key1: "value1"key2:  - value2  - value3

Dictionary in JSON:

{    "key1": "value1",    "key2": }

Python

>>> yaml.load(open(‘yaml-example.yml’)){‘key1’: ‘value1’, ‘key2’: }>>> type(yaml.load(open(‘yaml-example.yml’)))<class ‘dict’>

And all usual to Python’s dictionaries operations are supported:

>>> dict = yaml.load(open(‘yaml-example.yml’))>>> type(dict)<class ‘dict’>>>> dict.update({‘key3’:’value3'})>>> print(dict){‘key1’: ‘value1’, ‘key2’: , ‘key3’: ‘value3’}

API

Here we cover the most ‘useful’ methods. If you need advanced details (creating
your own tags), see examples
for more info.

const yaml = require('js-yaml');
const fs   = require('fs');

// Get document, or throw exception on error
try {
  const doc = yaml.load(fs.readFileSync('/home/ixti/example.yml', 'utf8'));
  console.log(doc);
} catch (e) {
  console.log(e);
}

load (string )

Parses as single YAML document. Returns either a
plain object, a string, a number, or , or throws on error. By default, does
not support regexps, functions and undefined.

options:

(default: null) — string to be used as a file path in
error/warning messages.
(default: null) — function to call on warning messages.
Loader will call this function with an instance of for each warning.
(default: ) — specifies a schema to use.
- — all supported YAML types.
(default: false) — compatibility with JSON.parse behaviour. If true, then duplicate keys in a mapping will override values rather than throwing an error.

NOTE: This function does not understand multi-document sources, it throws
exception on those.

NOTE: JS-YAML does not support schema-specific tag resolution restrictions.
So, the JSON schema is not as strictly defined in the YAML specification.
It allows numbers in any notation, use and as , etc.
The core schema also has no such restrictions. It allows binary notation for integers.

loadAll (string )

Same as , but understands multi-document sources. Applies
to each document if specified, or returns array of documents.

const yaml = require('js-yaml');

yaml.loadAll(data, function (doc) {
  console.log(doc);
});

dump (object )

Serializes as a YAML document. Uses , so it will
throw an exception if you try to dump regexps or functions. However, you can
disable exceptions by setting the option to .

options:

(default: 2) — indentation width to use (in spaces).
(default: false) — when true, will not add an indentation level to array elements
(default: false) — do not throw on invalid types (like function
in the safe schema) and skip pairs and single values with such types.
(default: -1) — specifies level of nesting, when to switch from
block to flow style for collections. -1 means block style everwhere
— «tag» => «style» map. Each tag may have own set of styles.
(default: ) specifies a schema to use.
(default: ) — if , sort keys when dumping YAML. If a
function, use the function to sort the keys.
(default: ) — set max line width. Set for unlimited width.
(default: ) — if , don’t convert duplicate objects into references
(default: ) — if don’t try to be compatible with older
yaml versions. Currently: don’t quote «yes», «no» and so on, as required for YAML 1.1
(default: ) — if flow sequences will be condensed, omitting the space between . Eg. , and omitting the space between and quoting the key. Eg. Can be useful when using yaml for pretty URL query params as spaces are %-encoded.
( or , default: ) — strings will be quoted using this quoting style. If you specify single quotes, double quotes will still be used for non-printable characters.
(default: ) — if , all non-key strings will be quoted even if they normally don’t need to.
— callback called recursively on each key/value in source object (see docs for ).

The following table show availlable styles (e.g. «canonical»,
«binary»…) available for each tag (.e.g. !!null, !!int …). Yaml
output is shown on the right side after (default setting) or :

Example:

dump(object, {
  'styles': {
    '!!null': 'canonical' // dump null as ~
  },
  'sortKeys': true        // sort object keys
});

Отличие YAML от JSON

YAML имеет некоторые особенности, отсутствующие в JSON. В YAML-файлах можно комментировать строки, используя знак #. YAML также позволяет использовать то, что называется «якоря». Например, предположим, есть два схожих определения. Можно написать определение один раз и использовать указатель для ссылки на оба:

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

В руководстве по OpenAPI не будем использовать эти уникальные функции YAML, но их стоит отметить, поскольку JSON и YAML не совсем эквивалентны. Подробнее о других различиях между JSON и YAML см. В разделе «Изучение YAML за несколько минут». Чтобы узнать больше о YAML, можно посмотреть справочник YAML.

YAML также используется в Jekyll. Можно изучить учебник автора по YAML в контексте Jekyll для более подробной информации.

Indentations

The main headache on the YAML is the indentations.

In this, in a whole file, the number of spaces (spaces — ever TABs!) must be the same.

I.e. if in one place two spaces are used — then the whole file must use two spaces.

Even more — the agreement is to use two spaces, although can be any — just has to be the same everywhere.

For example:

---parent_key:    key1: "value1"    key2: "value2"    key3: "%value3"

Will be valid form, but the next example:

---parent_key1:    key1: "value1"    key2: "value2"    key3: "%value3"parent_key2:  key1: "value1"  key2: "value2"  key3: "%value3"

Will not.

While in Python which is ofter is scolded because of the spaces dependency such formatting can be used, although will be standard’s violation:

#!/usr/bin/env pythondef a():    print("A")def b():  print("B")a()b()

Results:

$ python spaces.pyAB

Indentations

The main headache on the YAML is the indentations.

In this, in a whole file, the number of spaces (spaces — ever TABs!) must be the same.

I.e. if in one place two spaces are used — then the whole file must use two spaces.

Even more — the agreement is to use two spaces, although can be any — just has to be the same everywhere.

For example:

---parent_key:    key1: "value1"    key2: "value2"    key3: "%value3"

Will be valid form, but the next example:

---parent_key1:    key1: "value1"    key2: "value2"    key3: "%value3"parent_key2:  key1: "value1"  key2: "value2"  key3: "%value3"

Will not.

While in Python which is ofter is scolded because of the spaces dependency such formatting can be used, although will be standard’s violation:

#!/usr/bin/env pythondef a():    print("A")def b():  print("B")a()b()

Results:

$ python spaces.pyAB

Literal Block Scalar

YAML supports the ability to add multiline literal block scalars and has three types of it: the common one, using the “» and the «».

The common format looks like:

---string: This    is    some text    without newlines

Results in Python console:

>>> yaml.load(open(‘yaml-example.yml’)){‘string’: ‘This is some text without newlines’}

Using the | ( — will save all newlines and closing spaces:

---string: |    This    is    some text    with newlines

Result is:

>>> yaml.load(open(‘yaml-example.yml’)){‘string’: ‘This\nis\nsome text\nwith newlines\n’}

And using the > ():

---string: >    This    is    some text    without newlines

Will return whole text in one line + closing newline symbol:

>>> yaml.load(open(‘yaml-example.yml’)){‘string’: ‘This is some text without newlines\n’}

But still, you have to adhere to the same spaces formatting.

Also, check the great answer on the StackOverflow here>>>: