zem_user_manual

Инструкция по установке и эксплуатации

ООО «КОДЖЕЗ» (COGEZ LTD), 2025

Продукт: «Code Generation Zemlya» -
мультифункциональная универсальная система генерации кода/текста

3.4.x

1. Описание

Программа для ЭВМ «Code Generation Zemlya» - это мультифункциональная
универсальная программа, предназначенная для генерации кода/текста
различных систем. Генерация кода происходит на основе входных данных
и наборов шаблонов. Поддерживаемые форматы файлов данных: JSON, YAML,
TOML. Программа свободно конвертирует данные из любого формата в
любой из выше указанных. Позволяет проверять, очищать, обогащать,
трансформировать и объединять данные из этих файлов (подготовка
данных для кодогенерации). Синтаксис встроенного языка шаблонизации
прост, имеет богатый специализированный функционал. Программа
позволяет разделять сгенерированный код на отдельные файлы,
предназначенные для загрузки в распределённые системы (гетерогенная
генерация кода). Программа предназначена для оптимизации и ускорения
процессов разработки качественного кода для крупных и средних
компаний.

Программа реализована как утилита командной строки. Визуального
интерфейса не имеет. Предназначена для использования разработчиками
и инженерами в целях оптимизации процессов создания и управления
кодовой базой предприятия, а так же, на серверах предприятия,
в том числе в составе микросервисов.

Программа написана на языке Rust. Использованы исключительно
библиотеки с открытым исходным кодом с лицензиями MIT и Apache 2.0,
которые не накладывают никаких ограничений на использование, в том
числе в коммерческих целях. Весь исходный код 100% на языке Rust,
включая использованные библиотеки.

2. Требования

2.1. Системные

Предпочтительно использование приложения в операционных системах:

Linux 64 bit
Windows 64 bit
MacOS 64 bit

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

2.2. Аппаратные

Минимальные:

CPU: 2 core
RAM: 4 Gb

Рекомендуемые:

CPU: 4 core
RAM: 16 Gb

2.3. Функциональные

Компилятор Rust может собрать бинарный исполняемый файл под любую из
современных операционных систем и архитектур/разрядностей
процессоров. Приложение, откомпилированное под определённую
операционную систему, процессорную архитектуру и разрядность, будет
работать только на них.

Подробнее о вариантах компиляции можно узнать на на ресурсах:

Кросплатформенная компиляция

Поддерживаемые цели (target's)

3. Установка и настройка

Программа поставляется в виде набора бинарных исполняемых файлов на
каком-либо носителе (USB Flash, по электронной почте и др.).
Бинарные файлы лежат в поддиректориях, например:

x86_64-pc-windows-gnu-release - версия для 64 битной
OS Windows;
x86_64-unknown-linux-gnu-release - версия для 64 битной
OS Linux;
x86_64-unknown-linux-musl-release - версия для 64 битной
OS Linux без установленной библиотеки libc, подходит для
работы в контейнеризованной среде на «голом» Linux (требуется
только ядро);

Для установки необходимо скопировать бинарный файл в какую-либо
директорию. Если требуется дать права на запуск, в OS Linux нужно
воспользоваться командой chmod +x <путь_к_файлу>. Для OS Windows
давать права на запуск не требуется. Настройки приложение берёт из
переменных среды окружения. При запуске программа ищет файл .env
в текущей директории. Если такой файл есть, то переменные из этого
файла копируются в соответствующие переменный окружения процесса и
далее читаются программой для получения настроек. Файл .env
поставляется вместе с бинарными исполняемыми файлами и документацией.
В нём перечислены все переменные окружения и дано (в комментариях)
описание к каждой переменной с примерами.

Для DEVOPS инженеров есть ссылка по сборке image-файла docker,
где описано как собрать минимальный по размеру рабочий образ:

Самый маленький Docker образ Rust приложения

4. Начало работы с программой

При запуске программы без параметров в командной строке выдаётся
справка по основным командам и разделам. Всё стандартно, как у всех
утилит командной строки. Набираем в командной строке zem и
нажимаем Enter.

Чтобы запускать приложение из любой директории, набрав просто zem:

Для Linux - скопируйте бинарный файл в одну из директорий из
переменной окружения PATH. Например, в /usr/bin или в
~/.local/bin.

Для Windows - такая же логика, нужно посмотреть директории,
находящиеся в переменной окружения PATH и, либо добавить
директорию, где находится бинарный файл в эту переменную, либо
скопировать файл в одну из директорий перечисленных в переменной
PATH. Либо запускать бинарный файл, используя полный или
относительный путь, например
./distrib/x86_64-unknown-linux-gnu/zem.

При запуске программы видим примерно следующее (от версии к версии
список команд и разделов может меняться и расширяться):

Usage: zem <COMMAND>
Commands:
webserver Start webserver (aliases: "web", "w") data-process Data processing (aliases: "data-proc", "data", "d")
algorithm Calculation Algorithms (aliases: "alg", "a")
parse-templates Parse templates (aliases: "parse", "p")
generate Generate code (aliases: "gen", "g")
split-files Split files (aliases: "split", "s")
convert Convert data files (aliases: "conv", "c")
help Print this message or the help of the given
subcommand(s)
Options:
-h, --help Print help
-V, --version Print version

Команда - это самостоятельный модуль программы, который может
выполнять какие-либо действия.

Раздел - это список команд или других (вложенных) разделов.

Чтоб получить справку по команде/разделу, нужно запустить программу
с указанием команды/раздела без дополнительных опций или
воспользоваться командой zem help <имя_раздела_или_команды>.
Оба способа работают одинаково.

Если вы видите в скобках указание алиасов команды, например, для
раздела data-process указано (aliases: "data-proc", "data", "d"),
то вызвать этот раздел (это может быть и команда) можно как с полным
синтаксисом zem data-process, так и сокращённо zem data-proc или
zem data или zem d (это совершенно идентичные вызовы).

Давайте наберём zem d и увидим что содержится в этом разделе:

Usage: zem data-process <COMMAND>
Commands:
keys-operation Operations on keys (aliases: "keys-op", "keys", "k")
help Print this message or the help of the given
subcommand(s)

Мы видим ещё одну команду keys-operation со своими алиасами.
Давайте посмотрим, что эта команда из себя представляет. Набираем
zem data-process keys-operation или кратко zem d k
(используем короткие алиасы). Видим следующий вывод:

Operations on keys (aliases: "keys-op", "keys", "k")
Usage: zem data-process keys-operation [OPTIONS]
--input <[KEY=]INPUT_FILE>... --output <OUTPUT_FILE>
Options:
-i, --input <[KEY=]INPUT_FILE>...
(R) Input list of paths to files JSON or YAML formats (set
multiple paths to files separated by a space, KEYs are not
required)
-o, --output <OUTPUT_FILE>
(R) Output JSON file path, or can use "stdout" or "null"
literals
-p, --pretty
(F) Use human-readable (pretty) format for output JSON file
(by default: in one line)
-u, --upper
(F) Use convert keys to Uppercase (conflict with flag
"lower")
-l, --lower
(F) Use convert keys to Lowercase (conflict with flag
"upper")
-t, --trim
(F) Use Trimming keys (trimming keys from leading and
trailing white spaces)
-a, --as-array
(F) Use Array for output data (by default: use Mapping)
-s, --serial
(F) Use Serial execution (by default: use Parallel
execution)

Как это читать/понимать?

В квадратных скобках «[» и «]» указываются НЕ обязательные
параметры/аргументы.
В угловых скобках «<» и «>» указаны ОБЯЗАТЕЛЬНЫЕ
параметры/аргументы.
Символ многоточия «...» используется для обозначения множества
аргументов (список). Т.е. к примеру, в ключе --input (из
скриншота выше) можно задать целый список из входных файлов, а
необязательный «[KEY=]» означает, что ключ для каждого файла
может быть задан или НЕ задан. Разделяются элементы списка
пробелами. Если какой-то путь к файлу содержит пробелы, то нужно
указывать весь аргумент (вместе с ключом!!!) в кавычках (двойных
или одинарных). Если в пути к файлу есть символы двойной кавычки,
то обрамляем одинарными кавычками и наоборот.
Значком «(R)» отмечаются required (обязательные) аргументы.
Значком «(F)» отмечаются flag (флаги). Флаги не принимают
никаких значений, это просто признаки. Они могут быть указаны
как по отдельности zem d k --trim --pretty --upper ..., так и
через краткую форму zem d k -p -t -u ... или все вместе после
одного тире (-) zem d k -utp ....

Для закрепления давайте составим запуск субкоманды
keys-operations из раздела data-process. Полностью это будет
выглядеть примерно так:

zem data keys -pltsa \
-i path/to/file1.json key2=path/to/file2.yaml \
"key 3=path/with space/file 3.yaml" \
-o temp/output/all_in_one.json

Пройдёмся по концепциям работы программы:

Все сообщения и логи программа пишет в поток операционной системы
stderr.
Также программа возвращает так называемый код возврата (return
code). Если всё прошло успешно (без ошибок), то код возврата
будет ноль («0»), при ошибках - какую-то другую цифру. Всё в
соответствии со стандартами, как принято в большинстве
операционных систем.

Теперь средствами операционной системы перенаправим потоки вывода
в файлы. Это делается легко. Все потоки программы имеют свои номера:

stdin - входной поток программы, имеет номер 0 (ноль), он
нас особо не интересует.
stdout - выходной поток, имеет номер 1 (один).
stderr - поток ошибок, имеет номер 2 (два), в него
программа пишет все свои сообщения и логи работы, это важный
поток.

Давайте разберёмся как эти потоки можно перенаправить. Есть так
называемые директивы перенаправления потоков. Их всего две: «>»
и «>>». Первая перезаписывает файл (затирает), вторая дописывает
в конец. Теперь, зная это, мы можем отправить логи работы
программы в файл (возьмём прошлый пример):

zem data keys -pltsa \
-i path/to/file1.json key2=path/to/file2.yaml \
'key 3=path/with space/file 3.yaml' \
-o output/data/all_in_one.json \
1>output/rendered/output.txt 2>>logs/zem.log

Всё, результаты работы программы записываются в соответствующие
файлы.

А что, если нам нужно сначала обработать файлы, а потом
сгенерировать код по шаблонам? Причём не генерировать код, если
предыдущий шаг выполнился с ошибкой. Это делается так. Есть два
оператора, которые помогут: логическое «и» - «&&»
и логическое «или» - «||». Давайте разберём на примере:

zem conv y2j -p data/e3ddec83-91a8-43f3-8dfd-608f5df5e2bb.yaml \
out/converted/e3ddec83-91a8-43f3-8dfd-608f5df5e2bb.json && \
zem alg poar -p \
-i data/e3ddec83-91a8-43f3-8dfd-608f5df5e2bb.yaml data/ref.json \
-o out/data/e3ddec83-91a8-43f3-8dfd-608f5df5e2bb.json && \
zem parse templates/example/main.jinja && \
zem gen -i out/data/e3ddec83-91a8-43f3-8dfd-608f5df5e2bb.json \
-t templates/example/main.jinja \
-o out/rendered/e3ddec83-91a8-43f3-8dfd-608f5df5e2bb.txt && \
zem split \
-i out/rendered/e3ddec83-91a8-43f3-8dfd-608f5df5e2bb.txt \
-w out/rendered || \
echo Error: Process finished with exit code $?;

Мы разделяем запуски программы логическим «и» и логическим «или» и
с помощью «echo» печатаем код возврата (этот код возврата
последнего запуска находится в переменной окружения «$?»). Если
какой-либо из запусков программы "упадёт" с ошибкой (код возврата
не нулевой), то в консоли напечатается
«Error: Process finished with exit code <не_нулевой_код_возврата>».
Кроме того, к каждой отдельной команде можно добавить
перенаправление потоков вывода («>» или «>>») в файлы.
Подробнее смотрите в руководстве по командной строке операционной
системы.

Примечание: На Unix, Linux, Windows и MacOS всё это работает,
но, может и отличаться в некоторых деталях. Если не работает -
обратитесь к справочному руководству по вашей операционной
системе, интернету или за помощью к разработчику.

5. Функционал

webserver - (это команда) поднимает многопоточный webserver
на указанном хост:порт. Включает в себя RESTfull API функционал
и Swagger. В следующих версиях будет добавлено WebUI.
data-process (это раздел) - процессинг данных.
- keys-operation (это команда) - операции с ключами.
  - input - входные файлы в формате ключ=значение разделённые
    пробелами (ключи не обязательны). Параметр обязательный.
  - output - выходной файл. Параметр обязательный, но можно
    результаты отправить в выходной поток stdout или в null
    (не выводить ничего).
  - pretty - удобный формат для чтения разработчиком, но
    занимает больше места на диске. Без этого параметра выходной
    JSON будет в одну строку (компактный).
  - upper - преобразовать все ключи в верхний регистр
    (конфликтует с параметром lower).
  - lower - преобразует все ключи в нижний регистр
    (конфликтует с параметром upper).
  - trim - удалить в ключах лидирующие и концевые пробелы.
  - as-array - сохранить результаты как список, где каждый
    элемент будет содержать один входной файл. По умолчанию
    используется маппинг, и в него переносится информация из
    файлов (если в одном из входных файлов находится список, то
    нужно назначить ему ключ, иначе будет ошибка).
  - serial - выполнять последовательно. По умолчанию каждый
    входной файл читается отдельным потоком (асинхронно, так
    быстрее), поэтому информация в логах будет вперемешку из
    разных потоков. Если это не устраивает, то включите данный
    флаг, и потоки выстроятся в очередь (будет чуть медленнее,
    зато логи будет удобно читать).
algorithm (это раздел) - алгоритмы обработки данных.
- prj-obj-atr-ref (это команда) - специфический алгоритм
  предварительной обработки и расчётов по данным, рассматривайте
  как пример, не более. Для каждого клиента может быть сделан
  отдельный алгоритм сложных проверок и трансформаций данных.
  Параметры рассматривать не имеет смысла (это только пример для
  демонстрации).
parse-templates (это команда) - парсинг главного файла
шаблонов со всеми вложенными шаблонами. Главный файл шаблона
должен находиться на самом верхнем уровне, то есть, подчинённые
шаблоны должны находиться либо на том же уровне, либо глубже
(в подпапках). Проверяется только синтаксическая корректность
(переменные и их значения не проверяются, так как они будут
известны только во время генерации кода по шаблонам). Эта команда
принимает только один аргумент - путь к главному шаблону.
generate (это команда) - генерация кода.
- input - список входных файлов с данными. Если файлы содержат
  списки, то им нужно назначить ключи. Все входные файлы будут
  объеденены в один глобальный контекст, доступный в иерархии
  шаблонов. Есть одно правило - ключами «[KEY=]» может быть
  всё, кроме зарезервированных слов (True, true, False, false,
  None, none, Null, null <- это всё зарезервированные слова!).
  Также будут ошибки, если используются такие ключи в самом
  верхнем (коренном или другими словами: рутовом) уровне. То есть,
  если в каком-то файле могут быть (даже теоретически) ключи из
  списка зарезервированных слов, то сразу назначьте ключ
  «[KEY=]» этому файлу. На втором уровне вложенности уже
  можно использовать ключи из списка зарезервированных. Хорошая
  практика - сразу определиться с ключами для каждого из входных
  файлов, чтобы не было проблем впоследствии.
- template - главный шаблон (путь к главному шаблону).
- output - выходной файл с результатами генерации, который
  программа перезапишет, если данный файл существует.
split-files (это команда) - «нарезка» выходного файла
(результата генерации) на отдельные файлы по тегу.
- input - список входящих файлов для нарезки (ключи станут
  подпапками).
- tag - тэг для нарезки. Необязательный параметр, если этот
  тэг задан в переменной окружения ZEM_TAG_FOR_SPLIT.
- sep - сепаратор (разделитель строк), по умолчанию «\n»
  (Unix формат).
- work-dir - рабочая директория (куда будут записываться
  результаты), по умолчанию текущая директория (current
  directory, т.е. «./»). Путь может быть относительным (от
  текущей директории) или абсолютным.
- trim-end - очищать строки от концевых пробелов в выходных
  файлах.
- del-empty - удалять пустые строки.
convert (это раздел) - конвертации данных из формата в формат.
- json-to-json (это команда) - конвертирует из формата
  JSON в формат JSON. Сделано для удобства, например, если у вас
  есть json-файл, но без форматирования, а вы хотели бы посмотреть
  на него в удобном для чтения формате, то укажите флаг
  «--pretty»(-p) и удобно читайте. Или наоборот, хотите
  преобразовать из удобного для чтения формата в одну строку для
  экономии места и лучшего быстродействия (без флага «--pretty»).
- json-to-yaml - эта, и далее, различные вариации, это
  конвертации из одного формата в другой (там, где выходной файл
  в формате JSON - везде имеется флаг «--pretty»). Для форматов
  YAML и TOML флаг «--pretty» не нужен, так как они итак в
  удобном для чтения формате.
- xml-to-json (это команда) - конвертирует данные из
  формата XML в формат JSON. В демоверсии не доступна.

Программа защищена авторским правом действующего законодательства
Российской Федерации, и имеет Свидетельство о государственной
регистрации программы для ЭВМ № 2024681535. Исключительные права
пренадлежат ООО «КОДЖЕЗ». Нелегальное использование, копирование и
распространение преследуется законом.