Файлы конфигурации.

Цель документа: описание формата конфигурационных файлов проекта Eskimo.
Тип документа: руководство администратора.
Составили: Савенко Д.В., Кузнецов А. А.
Дата: 06.07.2005
Версия: 1.0

1. Файлы конфигурации.

Сначала введем несколько определений:
Пробельный символ — пробел, табуляция, перевод строки а также любые их комбинации.
Идентификатор — это строка символов, не содержащая пробельных символов, а также специальных символов: <, > (угловые скобки), точка с запятой, /, “ (кавычки). 
Параметр — это либо идентификатор, либо любая текстовая строка, заключенная в кавычки (сами кавычки не включаются в значение параметра). Если необходимо использовать символ кавычек в самом значении, то он записывается по стандартным правилам: \”. Замечу, что эта форма записи поддерживается только внутри кавычек. 

Файл конфигурации представляет собой текстовый файл специального формата. Формат файла конфигурации содержит следующие элементы:

1. Комментарий. Комментарий начинается с символа # и продолжается до конца строки. Все его содержимое игнорируется парсером.

2. Обычное поле. Обычное поле состоит из названия и набора параметров, разделенных пробельными символами. Каждое поле обязательно должно заканчиваться точкой с запятой. Пример поля:

rocketTarget Washington Boston Detroit “Solt Lake City”;

rocketTarget — название поля, Washington, Boston, Detroit и Solt Lake City — параметры. Название должно быть идентификатором. Любые последовательности пробельных символов, не находящиеся в кавычках, интерпретируются как один пробел, поэтому строку выше можно было бы записать так:
rocketTarget	Washington
			Boston
			Detroit 
“Solt Lake City”;
Параметры полей имеют определенный тип, который задается либо сервером, либо плагином, который использует эти поля, и может быть выбран из следующего списка:
а) булевский тип, имеет два значения: On и Off, причем регистр букв не имеет значения.
б) целочисленный тип — целое число в диапазоне –2 147 483 648 .. 2 147 483 647. В зависимости от конкретного случая диапазон может быть сужен. 
в) дробный тип — 64-битное число с плавающей точкой. В зависимости от конкретного случая диапазон может быть сужен. 
г) строковой тип — любая строка, не содержащая символа перевода строки. Если она не содержит специальных символов (см. определение параметра), то она может не быть заключена в кавычки. Иначе необходимо заключить ее в кавычки.
д) тип с выбором — строка, которая выбирается из определенного списка допустимых строк. 
е) списковый тип — список строковых значений (смотри пример с rocketTarget, там как раз использован этот тип).

3. Контейнерное поле. Данное поле имеет следующий формат:

<fieldTag fieldName>
# другие поля, в том числе и контейнерные. 
</fieldTag> 

Внутри контейнерного поля может содержаться любое количество любых полей, в том числе и контейнерных. По существу контейнерное поле описывает новый узел иерархии конфигурации, родителем которого будет являться контейнерное поле более высокого уровня, либо контейнерное поле специального типа — ROOT, которое всегда имеется по умолчанию, не требует явного описания и содержит в себе все другие поля. 
Теперь более подробное описание:
fieldTag — это тег поля. Доступны следующие теги (регистр символов имеет значение!):
а) subsystem — определяет конфигурацию определенной подситемы сервера (например, подсистема BootManager и т.д.). 
б) launchscheme — описание определенной схемы запуска.
в) group — описание группы сервисов.
г) instance — описание сервиса (экземпляра определенного плагина).

fieldName — название, подчиняется правилам параметра. Например, <subsystem BootManager> описывает подсистему загрузки, <instance “Mega Cool Plugin”> описывает экземпляр плагина с названием Mega Cool Plugin. 

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

4. Команда @include.
Для удобства расположения информации введена возможность включать в конфигурационный файл другие конфигурационные файлы. Это реализуется командой include со следующим синтаксисом:
@include <file_name>;
На место этой команды на этапе разбора конфигурационного файла вставляется содержимое конфигурационного файла с именем file_name. Происходит просто текстовая вставка файла как он есть, поэтому, вообще говоря, вставляемый файл может не быть в полном смысле слова корректным конфигурационным файлом. Однако не рекомендуется это практиковать. Команда @include была введена исключительно для того, чтобы длинные конфигурации плагинов и подсистем можно было логически выделить в отдельные файлы. 

2. Файлы описания полей.

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

Определения пробельного символа, идентификатора и параметра идентичны приведенным в предыдущем разделе. Комментарии имеют такой же формат, как и в предыдущем разделе. Контейнерных тегов не предусматривается, имеется лишь список полей следующего вида:
type fieldName [defaultValue];
Обратите внимание на обязательную точку с запятой в конце. Этот тип описания поля используется для описания полей типов boolean, integer, double, string и list. Здесь:
type — тип поля (boolean, integer, double, list или string);
fieldName — имя поля;
defaultValue — необязательный параметр, который задает значение по умолчанию, если в конфигурационном файле это поле будет отсутствовать. Пример поля:
string MostInebriousNation “Russians”;

Для поля с типом list значением по умолчанию может быть набор параметров. Например, так:
list TwoMostInebriousNation Russians Frenches;

Обратите внимание, что значение по умолчанию есть параметр, поэтому кавычки в некоторых случаях могут быть опущены (см. определение параметра). 

Для типа с выбором параметров синтаксис несколько другой:

select fieldname [%]value1 [%]value2 . . . [%]valueN;

value1 … valueN — список возможных значений. Перед одним из этих значений может стоят знак %, что означает, что это значений будет использоваться по умолчанию. Пример:

select diplomacyType speech army %nuclear;