что такое yaml файлы
10 шагов к YAML-дзену
Мы все любим Ansible, но Ansible – это YAML. Для конфигурационных файлов существует масса форматов: списки значений, пары «параметр-значение», INI-файлы, YAML, JSON, XML и множество других. Однако по нескольким причинам из всех них YAML часто считается особенно трудным. В частности, несмотря на его освежающий минимализм и впечатляющие возможности для работы с иерархическими значениями, синтаксис YAML может раздражать своим Python-образными подходом к отступам.
Если вас бесит YAML, вы можете – и должны! – предпринять 10 следующих шагов, чтобы снизить свое раздражение до приемлемого уровня и полюбить YAML. Как и положено настоящему списку, наша десятка советов будет нумероваться с нуля, медитацию и духовные практики добавляем по желанию 😉
0. Заставьте ваш редактор работать
Неважно, какой у вас текстовый редактор – для него наверняка существует хотя бы один плагин для работы с YAML. Если у вас такого нет, немедленно найдите и установите. Потраченное на поиск и настройку время будет многократно окупаться каждый раз, когда вам придется редактировать YAML.
Например, редактор Atom поддерживает YAML по умолчанию, а вот для GNU Emacs придется установить дополнительные пакеты, например, yaml-mode.
Emacs в режиме YAML и отображения пробелов.
Если в вашем любимом редакторе нет режима YAML, то часть проблем можно решить, поработав с настройками. Например, штатный для GNOME текстовый редактор Gedit не имеет режима YAML, но по умолчанию подсвечивает синтаксис YAML и позволяет настроить работу с отступами:
Настройка отступов в Gedit.
А плагин drawspaces для Gedit отображает пробелы в виде точек, устраняя неясности с уровнями отступа.
Иными словами, потратьте время на изучение своего любимого редактора. Выясните, что он сам или его сообщество разработки предлагают для работы с YAML, и используйте эти возможности. Вы точно об этом не пожалеете.
1. Используйте линтер (linter)
В идеале языки программирования и языки разметки используют предсказуемый синтаксис. Компьютеры хорошо справляются с предсказуемостью, поэтому еще в 1978 году возникла концепция линтера. Если за 40 лет своего существования она прошла мимо вас и вы до сих пор не пользуетесь YAML-линтером, то самое время попробовать yamllint.
Установить yamllint можно с помощью штатного менеджера пакетов Linux. Например, в Red Hat Enterprise Linux 8 или Fedora это делается так:
Затем вы просто запускаете yamllint, передавая ему YAML-файл для проверки. Вот как это выглядит, если передать линтеру файл с ошибкой:
Цифры слева – это не время, а координаты ошибки: номер строки и столбца. Описание ошибки может вам ни о чем не говорить, зато вы точно знаете, где она находится. Просто посмотрите на это место в коде, и, скорее всего, все станет ясно.
Когда yamllint не находит ошибок в файле, на экран ничего не выводится. Если вас пугает такая тишина и хочется немного больше обратной связи, то можно запускать линтер с условной командой echo через двойной амперсанд (&&), вот так:
В POSIX двойной амперсанд срабатывает тогда и только тогда, когда предшествующая команда возвращает 0. А yamllint как раз возвращает количество найденных ошибок, поэтому вся эта условная конструкция и работает.
2. Пишите на Python, а не на YAML
Если вас реально бесит YAML, просто не пишите на нем, в буквальном смысле. Бывает, что YAML – это единственный формат, который воспринимается приложением. Но и в этом случае необязательно создавать YAML-файл. Пишите на том, что вам нравится, а потом конвертируйте. Например, для Python есть отличная библиотека pyyaml и целых два способа конвертирования: самоконвертирование и конвертирование через скрипты.
Самоконвертирование
В этом случае файл с данными заодно является и Python-скриптом, который генерирует YAML. Этот способ лучше всего подходит для небольших наборов данных. Вы просто пишите JSON-данные в переменную Python, предваряете это директивой import, а в конце файла добавляете три строчки для реализации вывода.
Теперь запускаем это файл на Python-е и на выходе получаем файл output.yaml:
Конвертирование через скрипты
В этом случае сначала пишем на JSON-е, а затем запускаем конвертор в виде отдельного Python-скрипта, который на выходе дает YAML. По сравнению с предыдущим этот способ лучше масштабируется, поскольку конвертирование отделено данных.
Для начала создадим JSON-файл example.json, например, его можно взять на json.org:
Затем создадим простой скрипт-конвертор и сохраним его под именем json2yaml.py. Этот скрипт импортирует оба модуля — YAML и JSON Python, а также загружает указанный пользователем файл JSON, выполняет конвертирование и пишет данные в файл output.yaml.
Сохраните этот скрипт в system path и запускайте по мере необходимости:
3. Парсите много и часто
Иногда на проблему полезно взглянуть под другим углом. Если вам трудно представить взаимосвязи между данными в YAML, можно временно преобразовать их в нечто более привычное.
Например, если вам удобно работать со словарными списками или с JSON, то YAML можно преобразовать в JSON всего двумя командами в интерактивной оболочке Python. Допустим, у вас есть YAML-файл mydata.yaml, тогда вот как это будет выглядеть:
На эту тему можно найти массу других примеров. Кроме того, в наличии множество онлайн-конвертеров и локальных парсеров. Так что не стесняйтесь переформатировать данные, когда видите в них только непонятную мешанину.
4. Читайте спеки
Возвращаясь к YAML после долгого перерыва, полезно зайти на yaml.org и перечитать спецификации (спеки). Если у вас трудности с YAML, но до спецификации руки так и не дошли, то пора эту ситуацию исправлять. Спеки на удивление легко написаны, а требования к синтаксису иллюстрируются большим количеством примеров в Главе 6.
5. Псевдоконфиги
При написании книги или статьи всегда полезно сперва набросать предварительный план, хотя бы в виде оглавления. Так же и с YAML. Скорее всего, вы представляете, какие данные надо записать в файл YAML, но не очень понимаете, как связать их друг с другом. Поэтому прежде чем ваять YAML, нарисуйте псевдоконфиг.
Псевдоконфиг похож на псевдокод, где не надо заботиться о структуре или отступах, отношениях «родитель-потомок», наследовании и вложенности. Так и здесь: вы рисуете итерации данных по мере того, как они возникают у вас в голове.
Псевдоконфиг с перечислением программистов (Martin и Tabitha) и их навыков (языков программирования: Python, Perl, Pascal и Lisp, Fortran, Erlang, соответственно).
Нарисовав псевдоконфиг на листе бумаги, внимательно проанализируйте его и, если все в порядке, оформите в виде валидного YAML-файла.
6. Дилемма «табуляция или пробелы»
Вам придется решить дилемму «табуляция или пробелы?». Не в глобальном смысле, а лишь на уровне вашей организации, или хотя бы проекта. Неважно, будет ли при этом использоваться пост-обработка скриптом sed, настройка текстовых редакторов на машинах программистов или же поголовное взятие расписок о строгом соблюдении указаний линтера под угрозой увольнения, но все члены вашей команды, которые так или иначе касаются YAML, в обязательном порядке должны использовать только пробелы (как того требует спецификация YAML).
В любом нормальном текстовом редакторе можно настроить автозамену табуляции на заданное количество пробелов, поэтому бунта приверженцев клавиши Tab можно не бояться.
Как хорошо известно каждому ненавистнику YAML, на экране не видно разницы между табуляцией и пробелами. А когда чего-то не видно, об этом, как правило, вспоминают в последнюю очередь, после того, как перебрали, проверили и устранили все остальные возможные проблемы. Час времени, убитый на поиск кривой табуляции или блока пробелов, просто вопиет о том, что вам над срочно создать политику использования того или другого, а затем реализовать железобетонную проверку ее соблюдения (например, через Git-хук для принудительного прогона через линтер).
7. Лучше меньше да лучше (или больше – это меньше)
Некоторые люди любят писать на YAML, поскольку он подчеркивает структуру. При этом они активно используют отступы, чтобы выделять блоки данных. Это такое своего рода жульничество для имитации языков разметки, в которых используются явные разделители.
Вот пример такой структурированности из документации Ansible:
Кому-то такой вариант помогает разложить в голове структуру YAML, других он наоборот раздражает массой ненужных, на их взгляд, отступов.
Но если вы являетесь владельцем YAML-документа и отвечаете за его сопровождение, то вы и только вы должны определять, как использовать отступы. Если вас раздражают большие отступы, сведите их к минимуму, который только возможен согласно спецификации YAML. Например, вышеприведенный файл из документации Ansible без каких бы то ни было потерь можно переписать вот так:
8. Используйте заготовки
Если при заполнении файла YAML вы постоянно повторяете одни и те же ошибки, имеет смысл вставить в него шаблон-заготовку в виде комментария. Тогда в следующий раз можно будет просто скопировать эту заготовку и вписать туда реальные данные, например:
9. Используйте что-то другое
Если приложение не держит вас мертвой хваткой, то, возможно, стоит сменить YAML на другой формат. Со временем конфигурационные файлы могут перерастать себя и тогда лучше преобразовать их в простые скрипты на Lua или Python.
YAML – отличная штука, которую многие любят за минимализм и простоту, но это далеко не единственный инструмент в вашем арсенале. Так что иногда от него можно отказаться. Для YAML легко найти библиотеки парсинга, поэтому, если вы предложите удобные варианты миграции, ваши пользователи относительно безболезненно переживут такой отказ.
Если же без YAML никак не обойтись, то возьмите на вооружение эти 10 советов и победите свою неприязнь к YAML раз и навсегда!
YAML для веб-разработчиков
Перевод статьи «Yaml for Web Developers».
Все чаще и чаще веб-разработчикам, чтобы стать лучшими профессионалами и меньше зависеть от окружающих в каких-то простых вещах из смежных сфер деятельности, приходится самим изучать эти вещи.
Зачем люди используют файлы такого типа? Каковы преимущества этих файлов? Как эта штука работает?
Цель этой статьи — познакомить вас с со структурой YAML, чтобы вы при необходимости смогли прочитать и понять такой файл и внести нужные изменения.
Ведь все мы чувствуем себя очень неловко и раздражаемся, когда что-то нужно сделать, а мы даже не понимаем, что это такое.
Прежде всего, что такое YAML?
Как написано на официальном сайте,
«YAML (рекурсивный акроним, означающий «YAML — это не язык разметки») это дружественный к человеку стандарт сериализации данных для всех языков программирования».
Этот формат часто используется для конфигурационных файлов, а это МНОГОЕ объясняет, верно?
Кучи конфигов, в которых никто не мог разобраться, очень утомляли людей, пока кто-то однажды не сказал:
«А что, если бы можно было писать файлы конфигурации, как кулинарные рецепты? Я имею в виду, с минимальным количеством очень понятного текста».
И — бум! — в мае 2001 года был создан YAML.
YAML vs JSON
Сюрприз! (или нет): YAML это надмножество для нашего хорошего знакомого — JSON.
«Надмножество это язык программирования, содержащий все функции данного языка, но при этом расширенный или улучшенный и включающий также другие функции», — Font.
Если бы мне нужно было провести какие-то аналогии, я бы сказал, что в мире фронтенда YAML это нечто вроде TypeScript, а JSON — вроде JavaScript.
Чтобы лучше понять, как это возможно, давайте рассмотрим пример:
Если бы нам нужно было переписать tsconfig.json в синтаксисе YAML, чтобы обеспечить такой же результат, файл выглядел бы следующим образом:
Примечание: это только пример! tsconfig нельзя писать на YAML!
Надеюсь, эти примеры помогли вам начать понимать саму идею.
Концепции, типы и синтаксис
А теперь давайте углубимся в концепцию языка.
Отступы
В YAML отступы имеют значение. Уровни вложенности здесь определяются пробельными отступами (т. е., tab использовать нельзя).
Если вы, как и я, используете tab повсеместно, установите какой-нибудь плагин в вашей IDE для замены табов на пробелы (например, editorconfig). Благодаря этому вы будете спокойно нажимать tab, а символ табуляции будет заменяться пробелами.
Поскольку отступы имеют значение, если перед первым объявлением нет отступов, YAML будет считать его корнем вашего файла (нулевым уровнем):
Это как первая фигурная скобка в JSON:
Ключ/значение
Как и JSON/JS, YAML использует синтаксис key/value. Делать это можно по-разному:
Комментарии
Чтобы написать комментарий, перед сообщением нужно просто поставить знак решетки.
Это очень удобно, когда нужно задокументировать какое-то решение или оставить примечание. К сожалению, в JSON это недоступно.
Списки
Есть два способа писать списки:
Как в JSON: массив из строк
Вы же помните, что YAML это надмножество JSON? Мы можем использовать синтаксис последнего:
Синтаксис с дефисами
Более распространенный вариант (и, пожалуй, рекомендуемый).
Строки
В YAML есть несколько способов объявления строки:
А в JSON есть только один способ — при помощи двойных кавычек:
Числа
Как и в языках программирования, здесь есть два вида чисел: Integer (целые числа) и Float (числа с плавающей запятой):
Якоря
Якорь это механизм создания группы данных (объекта), которую можно вставить в другие объекты и расширить за счет других объектов.
Давайте представим, что вам нужно создать конфигурацию для вашей CI. Она будет иметь и продакшен-, и стейджинг-среду. Как вы догадываетесь, настройки там будут практически одинаковые.
В мире JSON нам пришлось бы дублировать эти конфиги:
Но копипаст раздражает, особенно если приходится потом вносить изменения в разных местах.
Якоря решают эту проблему. Мы можем:
1. Создать наш якорь.
2. Вставить созданный якорь на уровне, где мы хотели бы видеть эти значения.
Выглядит проще, правда? И поддерживать легче.
Если вы скопируете этот код и вставите его в онлайн-конвертер «YAML в JSON», вы увидите тот же код, который я показывал в качестве примера на JSON, но внутри дополнения из base config:
JSON-синтаксис (да, JSON)
Как уже объяснялось, надмножество языка это базовый язык ПЛЮС некоторые дополнительные функции. Это означает, что файл YAML можно писать в стиле JSON:
Сомневаетесь? Скопируйте код и вставьте сюда.
Если вы конвертируете этот YAML в JSON, вы получите ту же структуру:
Окружение Shell/Bash
В этих файлах вам нужно описать, как должна работать машина/docker, что должно быть установлено, запущено и т. д.
Зачастую все эти окружения это Linux, а значит, вы также имеете доступ к самому окружению.
В GitLab CI, например, вы можете определить для глобального окружения переменные, к которым хотите иметь доступ в течение всего процесса:
Некоторые другие платформы также вводят другие значения, такие как имя ветки, время сборки, автор, а также секретные ключи, определенные вне конфигурации:
Заключение
Надеюсь, теперь вы немного лучше разбираетесь в том, что такое YAML, и сможете более уверенно читать и писать такие файлы.
Имейте в виду, что используемая вами платформа может накладывать собственные ограничения на то, к чему вы можете иметь доступ. Например, конфигурации Travis отличаются от GitLab CI или CircleCI.
Чтобы понять, что возможно, а что — нет, всегда в первую очередь ориентируйтесь на документацию используемой платформы.
YAML за 5 минут: синтаксис и основные возможности
Авторизуйтесь
YAML за 5 минут: синтаксис и основные возможности
YAML — это язык для сериализации данных, который отличается простым синтаксисом и позволяет хранить сложноорганизованные данные в компактном и читаемом формате. Рассказываем, как это пригодится для DevOps и виртуализации.
Что такое YAML?
YAML — это язык для хранения информации в формате понятном человеку. Его название расшифровывается как, «Ещё один язык разметки». Однако, позже расшифровку изменили на — «YAML не язык разметки», чтобы отличать его от настоящих языков разметки.
Язык похож на XML и JSON, но использует более минималистичный синтаксис при сохранении аналогичных возможностей. YAML обычно применяют для создания конфигурационных файлов в программах типа Инфраструктура как код (Iac), или для управления контейнерами в работе DevOps.
Чаще всего с помощью YAML создают протоколы автоматизации, которые могут выполнять последовательности команд записанные в YAML-файле. Это позволяет вашей системе быть более независимой и отзывчивой без дополнительного внимания разработчика.
Всё больше и больше компаний используют DevOps и виртуализацию, поэтому YAML — это must have для современного разработчика. Кроме того, YAML легко интегрировать, благодаря поддержке Python (используя PyYAML библиотеку, Docker или Ansible) и других популярных технологий.
YAML vs JSON vs XML
YAML (.yml)
Применение: YAML лучше всего подходит для приложений с большим объемом данных, которые используют DevOps конвейеры или виртуальные машины. Кроме того, улучшение читаемости данных пригодится в командах, где разработчики часто с ними взаимодействуют.
Применение: JSON используется в веб-разработке — это лучший формат для сериализации и передачи данных через HTTP-соединение.
Применение: XML идеален для сложных проектов, которым требуется тонкий контроль над валидацией, схемой и пространством имён. Язык обладает плохой читаемостью, требует большей пропускной способности и ёмкости хранилища, но обеспечивает беспрецедентный контроль.
Характерные особенности YAML
Поддержка мультидокументов
Вы можете объединить несколько YAML-документов в один YAML-файл для облегчения организации файлов и парсинга данных.
Документы разделяются тремя дефисами (—):
Поддержка комментариев
YAML позволяет добавлять комментарии после символа #, как в Python:
Легко читаемый синтаксис
В синтаксисе YAML-файлов используется система отступов, как в Python. Необходимо использовать пробелы, а не табуляцию, чтобы избежать путаницы.
Это избавляет от лишних символов, которые есть в JSON и XML (кавычки, скобки, фигурные скобки).
В итоге читаемость файла значительно повышается.
Явная и неявная типизация
Отсутствие исполняемых файлов
YAML не содержит исполняемых файлов. Поэтому можно безопасно обмениваться YAML-файлами с третьей стороной.
Чтобы использовать исполняемые файлы, YAML нужно интегрировать с другими языками, например Perl или Java.
Синтаксис YAML
В языке есть несколько базовых концепций, которые позволяют обрабатывать большинство данных.
Пары ключ-значение
Большинство данных в YAML-файле хранятся в виде пары ключ-значение, где ключ — это имя пары, а значение — связанные данные.
Скаляры и маппинг
Скаляр представляет собой одно значение, которому соответствует имя.
YAML поддерживает стандартные типы: int и float, boolean, string и null.
Строки
Строка — это коллекция символов, которая может содержать слово или предложение. Можно использовать либо |, для отдельных строк, либо >, для параграфов.
Кавычки в YAML не нужны.
Последовательности
Последовательности — это структуры данных похожие на списки или массивы, которые хранят несколько значений под одним ключом. Они определяются с помощью отступов или [].
Однострочные последовательности выглядят лаконичнее, но хуже читаются.
Словари
Словари — это коллекции пар ключ-значение, которые хранятся под одним ключом. Они позволяют разделить данные на логические категории.
Словари могут содержать более сложные структуры, что позволяет хранить сложные реляционные данные.
Yaml для веб разработчиков
Нам, веб-разработчикам, нужно все больше и больше узнавать о различных областях, чтобы стать лучшими профессионалами и меньше зависеть от других специалистов в простых вещах.
Почему люди используют этот тип файлов? В чем от них выгода? Как это работает?
Итак, цель этой статьи — познакомить вас со структурой YAML и дать вам больше уверенности в том, чтобы понимать, читать и изменять этот формат, когда вам это нужно.
Что такое YAML?
YAML (сокращение от YAML Ain’t Markup Language — YAML не является языком разметки) — это удобный для людей стандарт сериализации данных для всех языков программирования
Часто используется для записи файлов конфигурации, что многое объясняет, верно?
В какой то момент времени возникла усталость от множество форматов разных конфигов, которые никто не мог понять, пока кто-то просто не сказал:
Бум, и в мае 2001 года был создан Yaml.
YAML против JSON
Удивительно (хотя вроде и не совсем), Yaml — это расширенная версия нашего известного друга JSON.
«Yaml — это язык разметки, который содержит все функции разметки JSON и был расширен для включения других функций».
Если бы я мог дать вам представление о том, что это значит, я бы сказал:
В мире фронтенда Yaml и JSON можно сравнить как TypeScript и JavaScript
Чтобы лучше понять, давайте посмотрим на этот пример конфига:
Это пример tsconfig.json, он очень легко читаться, мы можем легко определить, что к чему, но … у него есть некоторые ограничения, например:
Но, если вы используете другой язык программирования, файлы JS не вариант. И именно в этот момент Yaml начинает сиять.
Если бы нам пришлось переписать tsconfig.json в синтаксисе YAML и получить такой же результат, это было бы так:
Обратите внимание, что это только пример. Вы не можете написать свой tsconfig в YAML!😜
Я надеюсь, что вы поняли идею из этих примеров.
Концепции, Типы, и синтаксис
Теперь давайте немного углубимся в концепцию языка.
Отступы
В Yaml отступы очень важны. Он использует отступы для разделения информации. Помнить нужно использовать только пробелы, табы не допускаются.
Если вы похожи на меня и используете табы для всего, установите какой-нибудь плагин в вашей IDE, чтобы заменить все пропуски на пробелы (например, editorconfig). Это может делаться автоматически, когда вы нажимаете на пропуск, он автоматически заменяется пробел! 😉
Root (Начало)
Поскольку здесь важен отступ, отсутствия отступа перед первым объявлением YAML поймет, что это корень (уровень 0) вашего файла:
Как и в JSON с первым символом < фигурной скобки:
Ключ/Значение
Как и в JSON/JS, YAML также использует синтаксис ключ/значение, и вы можете использовать его различными способами:
Комментарии
Чтобы написать комментарий, вы просто можете использовать #, а затем ваше сообщение.
Это круто, чтобы документировать какое-то решение или сделать заметку в конфиге. К сожалению, мы не можем так эе сделать это в JSON.
Списки
Есть 2 способа написания списков:
Синтаксис JSON: массив строк
Помните, Yaml — это расширенный JSON? мы можем использовать его синтаксис:
Синтаксис дефиса
Наиболее распространенный (и, вероятно, рекомендуется)
Строки
Есть несколько способов объявить строку в Yaml:
В то время как в JSON у нас есть только один способ использовать двойные кавычки:
В качестве предложения предпочитайте использовать кавычки, если вы хотите использовать какой-либо специальный символ, такой как _, @ и т. Д.
Номера
Как и в любом языке программирования, у нас есть 2 типа чисел: целое число и число с плавающей запятой:
Якоря узла (переменные)
Якорь — это механизм для создания группы данных (объекта), который может быть введен или расширен из других объектов.
Давайте представим, что вам нужно создать конфигурацию для вашего CI. Он будет иметь версию для production, и для staging (промежуточную) сред. Обе версии будут иметь почти одинаковые базовые настройки.
В мире JSON нам пришлось бы дублировать эти конфиги:
Копирование и вставка очень раздражают, особенно когда вам нужно что-то изменить во всех местах, где это использовалось.
Якоря, решают эту проблему. Мы можем:
Выглядит очень просто, верно? И это также проще в обслуживании.
Если вы скопируете этот код и вставите его в онлайн-инструмент «Конвертер Yaml в JSON», вы увидите тот же код, который я упоминал ранее в примере JSON, но с добавлением базовой конфигурации:
Синтаксис JSON (да, JSON)
Как объяснялось ранее, расширенный язык является таким же как базовый язык, плюс некоторые дополнительные функции, что означает, что мы можем написать файл Yaml в формате JSON.
Сомневаетесь? Скопируйте этот код и вставьте его сюда
Если вы преобразуете этот YAML в JSON, у вас будет такая же структура:
Shell/Bash окружение
Как я говорил в начале этой статьи, очень часто файлы .yml используются как файлы конфигурации для многих вещей, но особенно для среды CI/CD.
Для использования CI/CD вам нужно будет описать, как должен работать компьютер/docker, что должно быть установлено, запущено и т. д.
Обычно все это делается через среды — Linux, что означает, что у вас также будет доступ к самой среде.
Например, в GitLab CI вы можете указать на глобальном уровне переменные среды, которые должны быть доступными для всех процессов:
Обратите внимание, что синтаксис для использования переменных $ не из YAML, а из shell/bash.
GitLab CI делает все, что вы определили в переменных, и создает переменные оболочки.
Некоторые другие платформы также вводят другие значения, такие как ref, имя ветки (branch name), время сборки (build time), авторы (author), а также секретные ключи (secret keys), определенные вне конфигурации:
В приведенном выше примере мы используем переменную внешней среды $CI_COMMIT_REF_NAME, которую предоставляет платформа GitLab CI, которая описывает имя ветви или тега, для которого построен проект.
Заключение
Я надеюсь, что теперь вы знаете немного больше о YAML и, по крайней мере, будуте чувствовать себя более комфортно при чтении и записи своих файлов.
Всегда читайте документацию по платформе, над которой вы работаете, чтобы узнать, что можно или не нужно делать! 🙂