Введение
--------

Это набор макросов для генерации radshell скриптов по упрощенному
конфигурационному файлу. radshell нужен для создания сервисов в
модели, т.к. создавать через GUI множество (особенно однотипных)
сервисов неудобно и неэффективно.

Версия глубокая альфа, сделан минимально необходимый функционал.

ВНИМАНИЕ!!!

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

Что сейчас сделано
------------------

По сервисам:

- Создание сервисов
- Заполнение атрибутов значениями (можно заполнять несколько правил)
- Создание зависимостей для сервисов
- Заполнение пользовательских атрибутов

По шаблонам:

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

Можно добавить в шаблон правило типа "Numerical Formula Rule".

Можно задать пользовательские атрибуты типа: "Ответственность",
"Регион" и их значения по умолчанию

В шаблон можно добавить простую зависимость типа "Good, Marginal, Bad
Aggregation Rule".

Можно (иногда только так) добавить правило Numerical Aggregation с
заданием значений статусов.

ПРИМЕЧАНИЕ: Функция в политике уже должна быть создана.


Структура папок:
----------------

radshell - рабочая папка для создания конфигурационных файлов. В ней
выполняются все действия пользователя.

m4 - каталог с макросами общими для всех остальных определений

service - макросы для создания сервисов и атрибутов к ним

template - макросы для создания шаблонов и правил.

define - макросы для инициализации полезных функций. Сейчас
реализована связка имени шаблона и его атрибутов.

Как использовать:
-----------------

1. Заходим в папку radshell
2. Создаем файл с описанием сервисной модели, например, model_1.mc
3. Генерируем скипт radshell командой:

m4 ../m4/radshell.m4 model_1.mc

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

Синтаксис (команды)
-------------------

Для комментирования строки используем команду m4 'dnl', если надо
закомментировать несколько строк - команда 'ifelse()'. См. пример в
отдельном файле.

ВНИМАНИЕ: Символ '#' комментирует строку для препроцессора
(т.е. строка не будет выполнена), но будет участвовать в выводе
окончательного radsh. Исключение первые строки (те что идут в поток
"-1").

Можно использовать стандартные макросы языка m4.

Например: define(`varSrv',`Длинное_и_часто_повторяемое_имя_сервиса')
define(`__SERVER',`Здесь будет значение, которое потом исправим')

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

ЗАМЕЧАНИЕ: При использовании define в задании переменной (varSrv в
нашем примере) нельзя использовать символ "-", т.е. переменная типа
var-Srv работать не будет.

Можно также сократить запись, часто повторяющихся команд, например:
define(`__RESP',`USER_INST(RESPONSIBLE,Нижегородский ИВЦ)dnl')

Теперь при использовании записи "__RESP", будем устанавливать зону
ответственности для соответствующего сервиса.

Используются макросы:

TEMPL_SERV(Имя_шаблона_1[,Имя_шаблона_2,...,Имя_шаблона_n]) -
устанавливает имена шаблонов для создания сервиса и привязки его к
этим шаблонам. Используется только для СЕРВИСОВ, на атрибуты и шаблоны
не влияет. Имеет приоритет над макросом TEMPL_NAME при создании
сервисов. Т.е. все сервисы будут создаваться именно с этими
шаблонами. Для отмены используем макрос
undefine(`TMPL_SRV'). ВНИМАНИЕ!!! Не TEMPL_SERV

TEMPL_NAME(Имя шаблона) - устанавливает имя шаблона, который будет
использоваться в дальнейших операциях (например, значения для правил в
сервисах), в том числе и для создания сервисов. Имя может быть только
одно, для нескольких шаблонов используем команду TEMPL_SERV.

TEMPL_ATTR(Имя правила, Имя поля 1, Имя поля 2, ...) - задает имя
правила и имена полей, которые будут заполнятся при вызове команды
заполнения атрибутов в сервисе. Имя шаблона используется из
определения TEMPL_NAME.

_template_<Имя шаблона без префиксов> - устанавливает сразу две
команды: TEMPL_NAME и TEMPL_ATTR для соответствующего имени. Созданные
_template_ смотреть в файле define/def_templ.mc

TEMPLATE(Имя шаблона, Описание шаблона) - создаёт в выходном потоке
команды генерации шаблона-"пустышки".

ЗАМЕЧАНИЕ: переопределяет "Имя шаблона", т.е. TEMPL_NAME, поэтому
следим за очерёдностью определений.

NUM_FORMULA(Имя правила, Формула, Имя политики, Политика, Marginal
порог, Bad порог) - создаёт правило "Numerical Formula Rule".

USER_ATTR(Имя атрибута, Значение по-умолчанию) - в текущий шаблон
добавляется пара атрибут - значение по-умолчанию. Если надо несколько
атрибутов, повторить команду.

WORST_DEP(Имя шаблона, Имя правила, Bad, Marginal,
isChildInstancePropagation) - создает простое правило "Good, Marginal,
Bad Aggregation Rule". где:

    isChildInstancePropagation - true или false в зависимости от того как
    надо распространять статус.

    Bad, Marginal - какое состояние сервиса будет в зависимости от
    состояния потомка.

RULE_DESCR(Имя, Display, Description) - задаёт имя Numerical
Aggregation правила для создания. где:

	Имя - имя правила.

	Display - поле Display Name, то что будет отображаться при
	просмотре шаблона.

	Description - Краткое описание правила.

POLCNA_DEP(Имя шаблона, Имя функции) - создаёт само правило Numerical
Aggregation с вызовом функции из политики, где:

	Имя шаблона - имя дочернего шаблона, от которого будет
	зависеть исходный шаблон

	Имя функции - имя используемой функции. Функция в политике
	должна быть создана.

FUNCNA_DEP(Имя шаблона, {Min|Max|Sum}) - создаёт правило Numerical
Aggregation с использованием функции Minimum, Maximum или Sum, где:

	Имя шаблона - имя дочернего шаблона, от которого будет
	зависеть исходный шаблон

	Min|Max|Sum - фиксированные значения для вызова
	соответствующей агрегирующей функции. Проверка на корректность
	не производится.

SET_STATUS(Marginal, Bad) - устанавливает значения Статуса правила в
зависимости от возвращаемых значений функции, где:

	Marginal - значение для "жёлтого" статуса. (Должно быть
	числовое)

	Bad - значение для "красного" статуса. (Должно быть числовое)

ПРИМЕЧАНИЕ: Шаблон, в котором создаётся правило Numerical Aggregation
(RULE_DESCR, NUMAGG_DEP, SET_STATUS) задаётся макросами TEMPLATE или
TEMPL_NAME (Переменная TEMPL_NME).

SERVICE(Имя сервиса,Display Name,Description) - создает команды для
генерации сервиса с заданными полями. Если внутри полей (кроме имени
сервиса) надо использовать ", то задействуем \ (экранирование). Пример
смотрим в примере. :) Макрос устанавливает переменную SRV_NAME, ее
значение будет подставлено, если имя сервиса будет пропускаться в
макросах VALUES, VALUES_NEXT, USER_INST.

VALUES_NEXT(Имя сервиса,{1|2|3...},Значение атрибута 1,
		Значение атрибута 2, ...) - Заполняет атрибуты в
указанном сервисе указанными значениями. Имена полей берутся из
определения TEMPL_ATTR. Устарело, заменено макросом VALUES (см.),
в дальнейшем будет удалено. Оставлено для совместимости со старыми
описаниями.

VALUES([Имя сервиса,][{0|1|2|3|4...},] Значение атрибута 1,
		Значение атрибута 2, ...) - Заполняет атрибуты в
указанном сервисе указанными значениями. Имена полей берутся из
определения TEMPL_ATTR. Позволяет установить значения для одного и
того же правила в сервисе. Порядок правил со значениями задаётся
числами от 1 до максимального поддерживаемого radshell (0 -
специальное значение, описание см. ниже). Макросом корректность чисел
и их порядок не проверяется, так что следим самостоятельно. Имя
сервиса и номер 1 можно не писать. Будет использовано значение
SRV_NAME (устанавливается в макросе SERVICE()). Вместо пропущенного
номера будет задаваться "1".

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

См. пример в файле sampleService.mc

USER_INST([Имя сервиса,] Имя атрибута, Значение) - Заполняет
пользовательский атрибут в сервисе значением, желательно давать после
команды VALUES, т.к. она выполняет предварительную очистку всех
значений. Если надо заполнить несколько атрибутов, то команда даётся
несколько раз. Используется, например, для задания атрибута
RESPONSIBLE ("Ответственность"). Имя сервиса можно пропустить, будет
использовано имя из последнего макроса SERVICE. (Отвечает переменная
SRV_NAME)

ЗАМЕЧАНИЕ: Пропускать имена сервисов имеет смысл, когда сервис
описывается сразу весь, т.е. все макросы идут друг за другом:

SERVICE(...)
VALUES(...)
USER_INST(...)

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

define(`SRV_NAME',`<имя сервиса для настойки>')dnl

перед макросами, где допускается пропуск имен.

PARENT(Имя сервиса) - задает имя сервиса, который будет использоваться
как родитель в дальнейших командах CHILD.

CHILD(Имя сервиса 1, Имя сервиса 2, ...) - создаёт связки
родитель-потомок в выходном потоке.


Правила оформления
------------------

Задаем имена шаблонов и правил для заполнения атрибутов. Это все
направляем в поток divert(-1), там же можно задать необходимые
define()

В потоке divert(2) задаём описания шаблонов и правила. Можно
объединить с divert(3), т.е. не выделять его отдельно, если записи
идут подряд.

В потокe divert(5) делаем описание самих сервисов. Если используются
макросы для задания атрибутов (VALUES), то такие сервисы пишем сразу
же за макросами TEMPL_NAME и TEMPL_ATTR, так как изменённый TEMPL_NAME
все также будет использовать значения из TEMPL_ATTR. Можно
сформулировать общее правило: TEMPL_NAME должен идти в паре с
TEMPL_ATTR, за ним идут все сервисы, связанные с этим шаблоном. Так же
можно объединить с divert(6)

В потоке divert(7) задаем иерахию созданных сервисов.

Вообще есть такие потоки (divert):
0 - data fetcher
1 - политики для шаблонов
2 - описание шаблонов
3 - правила для шаблонов (rules)
4 - иерархия шаблонов
5 - описание сервисов
6 - атрибуты сервисов
7 - иерархия сервисов


ПРИМЕЧАНИЯ
----------

Примеры использования макросов приводятся в файле
sampleService.mc. Его можно использовать как шаблон для написания
своих конфигураций.