Yaml — король мета-описаний

На Хабре, было несколько статей о Yaml, но мне кажется все они однобоки и не раскрывают его истинную природу. Я попробую это исправить и рассказать о Yaml в положительном контексте. Не буду вновь описывать детали синтаксиса стандартного Yaml, в Интернете есть много материалов на эту тему. Их можно найти и на Хабре, в том числе, по ссылкам из этой статьи. Материал ориентирован на тех, кто знаком с Yaml, но возможно чувствует неприязнь к формату.

За последние 30 лет активно развивающего IT, устоялись три основных формата для представления иерархических данных, т.е. деревьев:

1. XML/HTML - особенность формата в том, что узлами являются объекты, а это архи необходимо, в первую очередь, для кодирования богатых "человеческих визуализаций". Отсюда и постфикс "ML" - язык разметки. Этот формат используется для веб-сайтов или, например, для хранения данных MS Excel. Узлы представляются объектами из-за наличия атрибутов тегов, а также необходимостью прохода по дереву во всех направлениях. В начале 2000-х годов, XML более широко использовался для передачи данных между удаленными хостами, но часто был вытеснен JSON, так как последний намного более прост, а мощь XML (как и сложность) оказались не востребованы.

2. JSON - также представляет иерархические данные, но узловыми ключами не могут быть объекты, а только скаляры: строки или целые числа. Особенность формата в том, в том, что он имеет минимальное количество правил, необходимых для практической реализации парсеров. Отсюда его популярность, в том числе, для обмена сообщениями между удаленными хостами. JSON часто не читают люди, а кодирование и декодирование происходит автоматически.

3. YAML - также не может содержать в узловых ключах объекты, а только скаляры. Этот формат включает, как подмножество, JSON, часто используется для конфигураций, и ориентирован в большей степени для чтения-записи человеком, чем JSON. В этой статье, сравниваются два последних формата, но имхо, нужно акцентировать, что Yaml предназначен для человека, а JSON не только. И ставить вопрос "кто круче" не очень корректно.

Ситуация с Yaml, наверно самая сложная и запутанная, например в этом посте-нытье рассказывается как всё плохо. Но негативные обстоятельства можно и нужно обратить вспять. Для этого следует всё расставить по своим местам. С момента появления Yaml прошло 23 года, но он активно используется в различных языках программирования для конфигураций, в том числе, флагманском PHP-framework Symfony. По-моему этого факта достаточно, чтобы утверждать, что Yaml имеет свой "рай", просто его нужно понять. Наверно до Yaml нужно дорасти, я например, написал свой парсер Yaml и многое понял из того о чём пишу, только в прошлом году, хотя занимаюсь программированием уже давно.

Я считаю, в стандартной архитектуре Yaml, действительно присутствует удивительный факап. Первичная идея - гениальная, но конечные детали - неудовлетворительны. Как говорится "начали за здравие, закончили за упокой"... Тем не менее, за 23 года жизни Yaml устоялся факт его локального применения. Жизнестойкость и локальность объясняется так: он действительно красив, минималистичен и выразителен, но его парсер всегда будет более сложен, объёмен и менее эффективен чем у JSON. Производительность - не проблема, так как компилированные данные всегда можно поместить в кэш. Я назвал Yaml королем мета-описаний, потому что, считаю синтаксис Yaml таким, который вобрал в себя все самые мощные способы представления иерархических структур, которые будут выглядеть красиво и выразительно для человека. По сути, Yaml удобно использовать не только для конфигураций, но и для программирования. Но об этом позже.

Я не нашел в Wikipedia четкого термина для "мета-описаний", поэтому опишу, что я под этим подразумеваю. Иногда, в программировании, бывает эффективно придумать какой-то собственный формат представления данных, который будет отражать алгоритмические особенности парсера, работающего с таким форматом. Данные в таком произвольном формате, я и называю мета-описаниями. Например, среди моих прошлых работ, имеется PHP имплементация CSS framework Tailwind. Для генерации всех(!) утилит Tailwind используется до 200 мета-описаний. Это пример одного мета-описания для генерации 42-х утилит "Grid Column Start / End":

- MetaName: col #grid
  ForMenu: 2col span-start-end
  Body: |
    auto|span-full|start-auto|end-auto|@num
    grid-column: auto
    .auto
    grid-column: 1 / -1
    .span-full
    grid-column-start: auto
    .start-auto
    grid-column-end: auto
    .end-auto
    span-~num!=: span {0} / span {0}|start-~num!=-start: {0}|end-~num!=-end: {0}
    grid-column{@}
    .@num

В консоли можно протестировать как Vesper (это моя имплементация Tailwind) генерирует утилиты, вот три примера:

>php vendor/bin/sky venus tw col-auto
.col-auto {
  grid-column: auto;
}

>php vendor/bin/sky venus tw col-span-2
.col-span-2 {
  grid-column: span 2 / span 2;
}

>php vendor/bin/sky venus tw col-start-2
.col-start-2 {
  grid-column-start: 2;
}

Кстати, эта статья включает работу программиста на PHP. Для тех, кто хочет подробнее ознакомиться с моей работой, доступно к установке пустое демо-приложение "Hole". Предостережение: Coresky - это экспериментальный фреймворк, подробнее в спойлере:

Hidden text

Это значит, что я использую фреймворк только для разработки новых архитектурных решений и не рекомендую его использовать для публичной части Интернета. Проделана огромная работа благодаря только лишь эндорфинам и удовольствию творчества. Много кропотливой, не творческой работы не сделано и вы легко найдете ошибки. Отчасти они присутствуют из-за того, что я всё еще продолжаю делать обратно несовместимые изменения новых версий к старым. Тем не менее то, о чём я пишу в этой статье - отлично работает. Большая часть кода имеет статус release-candidate.

>composer create-project coresky/hole
  # и можно сразу запустить PHP-DEV-WEB сервер:
>cd hole
>php vendor/bin/sky s

Исправим стандартный Yaml

Смотрите, для передачи данных между хостами существуют JSON и XML, а Yaml мы будем использовать только локально. Поэтому нет проблем, чтобы написать свой собственный парсер. Давайте исправим архитектурный факап, чтобы минимизировать досадные "подводные камни" и с другой стороны, раскроем всю потенциальную мощь Yaml. Конечно, необходимо стараться максимально сохранить стандартный Yaml, это упростит изучение Coresky модификации. Пакет Composer symfony/yaml как и многие другие популярные имплементации также не поддерживают стандарт полностью. Например, обычно, не поддерживается множественный Yaml документ. В Coresky, парсер Yaml это один файл, содержащий 577 строк. Я использую технику разбивки на токены, тогда как в Symfony используются регулярные выражения.

Неявная типизация. С проблемой Норвегии - это ерунда какая-то.. Давайте оставим рабочими только три литерала, которые являются стандартными в JSON и соответствуют по типу в PHP: true, false, null. Целые числа оставим только десятичные, а также с плавающей точкой float, в полном соответствии с синтаксисом PHP. Двоичные, шестнадцатеричные INT и всю остальную неявную типизацию убираем. Для этого дела лучше применить функции трансформации или операторы. Об этом ниже.

Явная типизация. Здесь, нужно расширить стратегию и использовать соответствующие термины "оператор" или "функция преобразования". В Coresky имеется собственный компилятор представлений - Jet, который является потомком Laravel/Blade, в нём используются операторы, начинающиеся с символа амперсанд. Используем такой же подход и в Yaml. Для имплементации большинства функций трансформации требуется буквально пару строк кода на PHP. То как трансформируются значения записано в нотации стандартного JSON:

# @base64 тоже что и !!binary в стандартном Yaml
img: @base64 |
  R0lGODdhDQAIAIAAAAAAANnZ2SwAAAAADQAIAAACF4SDGQ
  ar3xxbJ9p0qa7R0YxwzaFME1IAADs=
array: @csv(:) a:b:c # трансформируется в массив: ["a", "b", "c"]
hi: @hex2bin > # трансформируется в строку: "Hello word!"
  48 65 6C 6C 6F 20 77 6F 72 64
  21
# десятичные числа в спец-нотации:
card: @dec 1234_5678_9012_3456 # >>> 1234567890123456
big-number: @dec 1 000 000 000 # >>> 1000000000
phone: @dec 2-777-222-22-22    # >>> 27772222222
# двоичное число:
five: @bin 101 # >>> 5
# Search-And-Replace, используется функция PHP preg_replace(..)
sar: @sar(|=+| is ) a========1, b==2 # >>> "a is 1, b is 2"
# @left(string), @right(string) - дописать "string" слева или справа
key: @left(left-) value # >>> "left-value"
# и так далее ..

Операторы можно указывать только вначале значений Yaml или JSON нотаций. Для одного значения, можно указать несколько операторов и они могут применяться каскадно для всех значений под-массива. Порядок выполнения - справа налево и снизу вверх. Для частной отмены каскадного выполнения, можно использовать @deny:

one: @right( RR)
  two: @bin
    - 0b11
    - 101 # можно и без префикса 0b
    - @deny @left(LL ) 1010
  three: four
color: @left(#) @each @bang(. ) @sar(| +| ) > # not in cascade
  aliceblue.f0f8ff     antiquewhite.faebd7
  beige.f5f5dc         bisque.ffe4c4
# для кодирования цветов мы указали только информационную "соль"
# вот почему Yaml - король метаопределений

{
  "one": {
    "two": ["3 RR", "5 RR", "LL 1010"],
    "three": "four RR"
  },
  "color": {
    "aliceblue": "#f0f8ff",
    "antiquewhite": "#faebd7",
    "beige": "#f5f5dc",
    "bisque": "#ffe4c4"
  }
}

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

one:
  two: [1, 3]
three: @path(one.two.1) # this value will eq. to 3

Множественный Yaml. Должен иметь именованные части! Тогда можно будет свободно компоновать Yaml-данные и применять принцип DRY. Компилятор Jet поддерживает маркеры частей файлов. Используем эту же стратегию и в Coresky Yaml:

#.run =========================
- @inc(.test) # @inc это include
- 2
#.run

#.test =========================
+ 123
#.test

<?php

# функция yml(..) выполняет inline-yaml, может кешировать компилированный PHP
# и передавать переменные, подобно как это делается в Jet (Blade)
print_r(yml('+ @inc(run) filename.yml'));

# stdout: array(0 => 123, 1 => 2)

Гибридные массивы PHP. В стандартной Yaml нотации есть одна неразбериха: для того чтобы указать значение со строковым ключом на нижнем уровне иерархии - обязательно нужен отступ, а для перечислений отступ необязателен:

aaa:
  bbb: # { "aaa": { "bbb": null } }    отступ ==> глубина

aaa:
bbb: #  { "aaa": null, "bbb": null }   <--- здесь глубина не изменилась

aaa:
  - bbb # { "aaa": [ "bbb" ] }      отступ ==> глубина

aaa:
- bbb # { "aaa": [ "bbb" ] }    <--- здесь глубина изменилась хотя нет отступа!!!

# Исправим синтаксис для предыдущего примера в Coresky вот так:
aaa:
- bbb # { "aaa": null, "0": "bbb" }

Yaml компилируется в PHP массив, а массивы в PHP могут быть гибридными. Разрешим совмещать в Yaml нотации строковые ключи и ключи перечислений (дефис). Это расширит потенциал использования Yaml. Ниже представлен действующий код для генерации HTML формы системной конфигурации Coresky для Root-Admin-Section:

#.system
- <fieldset><legend>Primary settings</legend>
- ['', [[<b><u>Production</u></b>, li]]]
trace_root: [Debug mode on production for `root` profile, chk]
trace_cli: [Use X-tracing for CLI, chk]
error_403: [Use 403 code for `die`, chk]
empty_die: [Empty response for `die`, chk]
gate_404: [Gate errors as 0.404 (soft), chk]
log_error: [Log ERROR, radio, [Off, On]]
log_crash: [Log CRASH, radio, [Off, On]]
- [Hard cache, {
    cache_act: ['', radio, [Off, On]],
    cache_sec: ['Default TTL, seconds', number, style="width:100px", 300]
  }]
- </fieldset>
- <fieldset><legend>"Visitor's & users settings"</legend>
- [Cookie name, {
    c_name: ['', '', '', sky],
    c_upd: ['Cookie updates, minutes', number, style="width:100px", 60]
  }]
visit: ['One visit break after, off minutes', number, '', 5]
reg_req: [Users required for registrations, radio, [Both, Login, E-mail]]
- </fieldset>
#.system

Coresky Yaml - младший брат Jet

В Coresky имеется функционал для генерации HTML форм из массивов PHP. Теперь формы можно определять с помощью Yaml. Добавим операторы @php и @preflight, ниже пример кода Yaml и соответствующий компилированный PHP кэш-файл:

#.test =======================================
+ @preflight($v_1, &$v_2) |
  return SomeClass::method_1($v_1, $v_2);
- string
- @php OtherClass::method_2($__return)
- {a: b, c: @php(OtherClass::method_3([1, $v_3])), x: y} # json notation
#.test

<?php

# preflight code
$__return = call_user_func(function() use ($v_1, &$v_2) {
  return SomeClass::method_1($v_1, $v_2);
});

# other yaml after compile
return array(
  0 => 'string',
  1 => OtherClass::method_2($__return),
  2 => array(
    'a' => 'b',
    'c' => OtherClass::method_3([1, $v_3]),
    'x' => 'y'
  ),
);

В операторе @php, код PHP можно указать или в параметре (в скобках) или в значении (после оператора). В первом примере выше, в последней строке, подсветка синтаксиса Yaml неверно сработала: всё что указано в скобках оператора @php, не является данными JSON нотации, а является кодом PHP. Если @preflight имеет скобки, то код будет выполняться в изолированной области видимости, которая организуется с помощью Closure и call_user_func, а если скобок нет - то без изоляции.

Вызов такого кода, и передачу переменных, можно выполнить с помощью функции Coresky yml(..):

<?php

$array = yml('cache_filename', '+ @inc(test) filename.yaml', [
    'v_1' => $var_1,
    'v_2' => $var_2,
    'v_3' => $var_3,
]);

В примерах выше, область применения Coresky Yaml, определенно коррелирует с компилятором представлений Jet. Представьте бухгалтерское приложение с огромным количеством форм. Теперь, рядом с папкой mvc, можно сделать папку forms и разместить в ней все формы приложения. Имена файлов содержащих yaml-формы, можно назвать в соответствии с именами контроллеров и разместить по несколько штук в одном файле разделив маркерами, в соответствии с именами действий, где используются эти формы. Представляете как это разгрузит код моделей, контроллеров и представлений? Как сказал автор статьи "Некоторые приемы YAML", да пребудет с нами KISS и DRY, а еще актуально: "разделяй и властвуй".

Формы на Yaml это не панацея, посмотрите, например этот файл. Довольно часто бывает нужно "прожонглировать" кусками кода и данных, чтобы сгенерировать финальный код. Раньше в подобных случаях, я использовал возможности Jet. Теперь это удобнее делать в Yaml. В приложении "Hole", которое вы можете установить с помощью Composer, есть несколько примеров форм на Yaml, в том числе, с передачей переменных в компилированный кэш.

Вы вероятно заметили "плюс" в Yaml нотации, в примерах выше, в местах где обычно бывает дефис. Это еще одно новшество в синтаксисе Coresky Yaml. Есть и другие нововведения, читайте подробнее в документации. Я старался показать хорошую сторону и скрытый потенциал Yaml, хотя, действительно в стандарте есть недостатки. Часто написать веб-приложение можно и без Yaml, но, например, в этом проекте без него было бы туго. Yaml в Coresky - это еще один мощный механизм для программирования и упрощения кода. Если у вас в проекте имеется более-менее значительный массив данных, который поместить в БД не рационально, у вас есть возможность использовать Yaml.

Другие интересные идеи в Coresky

Я напишу пару слов о каждой и помещу текст в спойлеры, так как это немного не по теме статьи. Если не интересно - вы можете пропустить эту часть.

Планы и продукты:

Hidden text

Нет велосипедам! Система продуктов в Coresky - это попытка сделать так, чтобы повторное использование функционального кода было максимально простым. Продукты бывают трёх типов: prod(функциональный код), dev(это по сути просто плагины для инструментов разработчика), view(дополнительные наборы шаблонов Jet и стилей CSS). Имя продукта основного приложения всегда main. Продукты похожи на модули Zend/Laminas, но в последнем нет никаких специальных средств для их интеграции в приложение, а также специальных системных средств для их поддержки. Продукты устанавливаются с помощью веб-интерфейса инструментов разработчика, в это время может произойти специальная инициализация продукта: создание таблиц в БД и т.д.

Планы - это надстройка над сущностями приложений. Стандартные планы, которые имеются в любом Sky-приложении: app, cache, mem, gate, jet. Управляет планами, по сути, движок абстрактного кэша.

Sky Gate - небесные врата

Hidden text

В Coresky нет привычной системы роутинга. SkyGate - это утилита с веб-интерфейсом, в которой настраиваются входные внешние данные для контроллеров. Первая часть адреса запроса определяет контроллер, а вторая действие в нем. Если нужна нестандартная адресация, необходимо использовать Coresky Rewrites.

Компилятор преставлений Jet

Hidden text

За основу была взята идея Laravel/Blade. В Jet много новшеств: препроцессор, бинарная идея блоков, включающая операторы @block, @use, #use, маркеры частей файла, три типа генерации визуализаций: top, sub, block. Имеется ввиду, что каждая визуализация запускает действие в контроллере, подготавливает переменные и генерирует визуализацию с помощью компилированного шаблона Jet.

Заключение

1. Если вы работаете со значительным объемом, особенно иерархических данных и не сильно воспринимаете Yaml: потрудитесь его изучить получше. Ему уже 23 года и он прекрасно себя чувствует, несмотря на плохие слухи. Если это так, значит он кому-то нужен, может нужен и вам? Когда вы, как Джек Салли скажете "Yaml, я тебя вижу..", вас от него уже будет не оторвать.

2. У стандартного Yaml есть скрытый потенциал, и я в этой статье старался показать как его раскрыть.

3. Не забывайте про подводные камни, если вы "не видите Yaml", будьте осторожны.