Ранее я уже выкладывал пост об этой утилите, сейчас решил описать её более развернуто и дать больше примеров и описания, так как функционал подрос за год.
Предыстория
Я в своей работе часто использовал стандартную линуксовую утилиту envsubst, с помощью неё удобно шаблонизировать конфигурационные файлы в разных скриптах. Но её функционала мне не хватало, она только умеет подставлять переменные среды в текст шаблона, например менять $VAR_NAME на её значение.
echo "Hello, $USER!" | envsubstЗатем я нашел отличную реализацию шаблонизатора Mustache написанном на чистом bash - mo. И долго использовал его вместо envsubst. Синтаксис Mustache давал намного больше возможностей по шаблонизации чем простой envsubst.
echo "Hello, {{ USER }}!" | moНо всё-таки Mustache довольно примитивен, а синтаксис немного инопланетен, и не включает в себя некоторые продвинутые возможности типа макросов, преобразований текста.
Поэтому мои поиски решения не прекращались. Я смотрел в сторону полноценных шаблонизаторов такие как Jinja, ERB, Freemarker и пр., и на утилиты на их основе, но мне не нравилось что они за собой тянут какой-то язык и его жирный рантайм. Да, я видел что есть утилиты-шаблонизаторы на Go, например Gomplate, которые собраны в статику, но когда я гляжу на размер этих бинарников мне становится грустно (~100Мб). Возможно есть достойные шаблонизаторы и на Rust, но я уже не стал искать, решение было принято )
Появление muenvsubst
В общем я решил что надо исправлять ситуацию, так родился мой проект muenvsubst. У меня большой опыт кодинга на C++. Я в своё время игрался со сборкой статики, с пакетным менеджером conan для C++. Нашел в Conan Center шаблонизатор mustache, который минималистичный и ни от чего не зависит. Первый релиз утилиты был как раз с этим шаблонизатором, отсюда и возникла приставка "mu" перед envsubst. С этим шаблонизатором мой статический бинарник собранный под Alpine получился 1,3Мб, это уже вдохновляло!
Некоторое время я вёл борьбу с размером бинарника, я переделал сборку с Alpine на uClibc, размер бинарника стал 900Кб, также я добавил upx и получил 260Кб, это уже было прямо очень хорошо! Теперь шаблонизатор можно добавлять прямо в Git в нужный проект, где нужна шаблонизация.
Всё интересное по сборке находится в Dockerfile. Я специально сделал сборочный образ с uClibc на основе проекта Buildroot, так как эта стандартная библиотека даёт самый минимальный по размеру рантайм из известных мне. Обычный gnu libc - конечно громадный монстр по сравнению с этой библиотекой.
Как я писал раньше - mustache довольно примитивен, я нашел ещё один более мощный шаблонизатор Inja, он также присутствует на Conan Center. Есть ещё jinja2cpp но там до чёрта зависимостей, мне такое не подходит. Так появилась версия 1.1.0, которая поддерживала два движка шаблонизации mstch и inja, размер бинарника подрос на 100Кб.
Что имеем на данный момент
В итоге я выкинул поддержку mstch из бинарника, так как Inja полностью покрывает его функционал.
Утилита может работать как оригинальный envsubst - принимать на вход (stdin) шаблон и выдавать на выход (stdout) шаблонизированный текст. В качестве значений для шаблонизации используются переменные среды как в оригинальном envsubst. Также можно указать файл шаблона и выходной файл.
echo "Hello, {{ USER }}!" | muenvsubst
muenvsubst -i template.txt -o result.txtСтандартный функционал Inja:
подстановка переменных
Hello, {{ USER }}!поддержка двух вариантов синтаксиса выражений
// стандартный для Jinja2
{% if USER == "John" %} {{ USER }} {% endif %}
// альтернативный
## if USER == "John"
{{ USER }}
## endifпеременные
## set userName = "mr. " + USER
Hello, {{ userName }}!условный оператор
// альтернативный
## if USER == "John"
Hello, John!
## else
You're not John
## endifцикл
## set i = 1
## for elem in split(PATH, ":")
Path elem {{ i }}: {{ elem }}
## set i = i + 1
## endforфункции
upper(s: string): string // в верхний регистр
lower(s: string): string // в нижний регистр
capitalize(s: string): string // Первую букву в верхний регистр
replace(s: string, from: string: to: string): string // замена в строке с from на to
range(num: int): array<int> // генерация числовой последовательности начиная с 0
length(val: string | array): int // длина строки или массива
first(arr: array<T>): T // первое значение
last(arr: array<T>): T // последнее значение
sort(arr: array): array // сортировка
join(arr: array, delimiter: string): string // объединить элементы в строку с разделителем
round(v: float): int // округлить до целого
odd(v: int): bool // число нечётное?
even(v: int): bool // число чётное?
divisibleBy(v: int, divider: int): bool // число делится на divider?
max(arr: array<T>): T // максимальное значение
min(arr: array<T>): T // минимальное значение
int(s: string): int // строку в целое число
float(s: string): float // строку в float
default(var: variable, val: T): T // если переменная не задана, подставить значение по умолчанию
exists(varName: string): bool // проверка на наличие переменной
existsIn(obj: object, varName: string): bool // проверка на наличие в объекте
isString(v: T): bool // значение строка?
isArray(v: T): bool // значение массив?includes
Hello, {{ userName }}## set userName="John"
## include "greeter.j2"Помимо стандартного для Inja я добавил следующий функционал:
Несколько полезных функций
error(message: string) // принудительная генерация ошибки
fromBase64(base64: string): string // декодирование base64
toBase64(text: string): string // кодирование base64
fromJson(json: string): json // декодирование Json
toJson(value: any, indent: int?): string // кодирование в Json
sh(stdin: string?, command: string): string // выполнение sh команды, можно подать текст на вход и получить текст на выходе
split(text: string, delimiter: string): string // разделить строку по подстроке
toBool(value: any): boolean // сконвертировать что угодно в bool
trim(text: string): string // обрезать пробелы и переносы по краям
center(text: string, width: int = 80): string // отцентрировать текст по заданной ширине
indent(text: string, width: int | string, first: boolean = false, blank: boolean = false): string // добавить слева отступыОтдельно хочу отметить функцию sh, она существенно расширяет возможности шаблонизации, так как можно наваять любые скрипты на bash если шаблонизатор в чём-то не справляется своими силами:
{{ sh("hostname") }}
{{ sh("uuidgen") | replace("-", "") }}
{{ "Hello John!" | sh("sed 's/John/Mary/'") }}Поддержку макросов по аналогии с Jinja2 (MR в Inja - https://github.com/pantor/inja/pull/334)
{% macro greeter(name, greeting="Hello") %}{{ greeting }}, {{ name }}!{% endmacro -%}
{{ greeter(USER) }}{{ greeter("World", "Hi") }}
{{ greeter("World", "Hi") }}Поддержку фильтров по аналогии с Jinja2 (MR в Inja - https://github.com/pantor/inja/pull/336). Фильтры позволяют обработать шаблонизированный текст заданной функцией, полезно, например, для добавления отступов, функции replace, uppercase и т.д, на что хватит фантазии:
## filter indent("// ", true)
line1
line2
## endfilterПоддержку pipe синтаксиса вызова функций. Правило очень простое - первый параметр в функцию подставляется из результата вычисления выражение до "|". Этот функционал и MR уже принят в Inja и доступен начиная с версии 3.5:
"A,B,C" | split(",") | join(";")Заключение
Теперь это мощный шаблонизатор и приставка "mu - μ" уже означает микро размер а не mustache.
Мы на работе во всю шаблонизируем наши скрипты и конфиги этой утилиткой. Очень надеюсь что кому-то ещё она тоже пригодится.
В планах еще есть пара фич на будущее:
подстановка переменных из шаблона в скрипты вызываемые из функции sh как переменные среды
использование помимо переменных среды на входе, файлы с JSON или YAML в качестве данных
возможно сборка под Mac и Windows. Но кому это нужно?