Описание структуры типов Интегра-Планета-4D — различия между версиями

Текущая версия на 16:49, 19 октября 2017

Формат описания типов элементов системы

Типы элементов системы Интегра-Планета-4Д описываются на языке XML версии 1.0, с использованием utf-8 кодировки.

В xml документе присутствовуют следующие теги:

• enum - описание перечисляемого типа параметра.
• item - описание устройства(объекта).
• pin - описание разъема устройства(объекта).
• link - описание соединения между разъемами.
• event - описание события.

Корневой элемент файла описания может называться произвольно (например root).

Любой тег может содержать дополнительные атрибуты, доступные в режиме исполнения.   Дополнительный атрибут может иметь любое имя не совпадающее с именами служебных атрибутов, описанных ниже.

Имена дополнительных атрибутов так же не могут совпадать с именами тегов.

Описание Тегов

1. is

Теги enum, item, link, pin и event описывают конкретные элементы системы, и их тела могут содержать произвольное количество тегов is, указывающих базовый тип элемента.

Тег is может содержать следующие атрибуты:

type - тип базового устройства. Обязательный атрибут.

Наследуемый тип получает все значения, параметры и разъемы базового.

2. enum

Тег enum содержит следующие атрибуты:

type - тип перечисления. Обязательный атрибут.

assembly - имя сборки в которой определен данный тип (пространство имен должно быть строго acuario2.types). По умолчанию создает новый тип.

Тело тега enum содержит один или несколько тегов value, являющихся описанием конкретного значения перечисления.

Тело тега value содержит текстовое представление значения, с которым связан данный элемент перечисления.

Так же тег value может содержать дополнительные атрибуты:

color - цвет состояния (в html формате).

image - плоское изображение состояния.

model - 3D модель состояния.

sound - звуковое обозначение состояния.

hint - подсказка пользователю (может содержать URL HTML документа с подробным описанием действий оператора в случае наступления данного события).

Тег enum должен содержать один тег value не имеющий тела, который может содержать дополнительные атрибуты по умолчанию для всех значений, не описанных в перечислении.

3. param

Теги item, link, pin и event описывают конкретные элементы системы и их тела могут содержать произвольное количество тегов param, описывающих параметры данного элемента.

Тег param может содержать следующие атрибуты:

type - тип параметра. Обязательный атрибут.

ref - ссылка на другой элемент (uuid);

bool - булево значение (bool);

char - символ (char(1));

int - целое знаковое число (int8);

real - число с плавающей точкой (float8);

guid - глобальный уникальный идентификатор (uuid);

time - дата/время (timestamp);

span - интервал времени (interval);

bits - битовая строка (varbit);

text - строка (text);

ltree - ветка иерархического дерева (ltree);

list - список строк (text[]);

vector - список чисел с плавающей точкой (float8[]);

blob - бинарные данные (bytea);

hstore - словарь ключ/значение (hstore);

json - документ типа json (json);

xml - документ типа xml (xml);

point - точка в пространстве (point);

multipoint - множество точек (multipoint);

polygon - полигон (polygon);

multipolygon - множество полигонов (multipolygon);

args - если связано с перечисляемым типом при помощи атрибута enum, то список уникальных значений этого перечисления, иначе просто список строк (text[]);

name - имя параметра. Обязательный атрибут.

enum - тип перечисления связанного с данным параметром.

public - булево значение, помечающее параметр как доступный для внешних систем. См. тег item. По умолчанию считается равным false.

editor - тип редактора для параметра (например acuario2.client.EgsCodeEditor,acuario2.editor). По умолчанию выбирается автоматически в соответствии с типом параметра.

converter - тип конвертера для параметра (например acuario2.utils.UnixTimeConverter,acuario2.utils). По умолчанию выбирается автоматически в соответствии с типом параметра.

unit - единица измерения (например second).

typedef - имя параметра внутри данного типа содержащего описание json документа хранящегося в данном параметре. См. Dynamic TypeDef в конце документа.

Если тип параметра не указан то считается что это текстовый параметр.

Тело тега param может содержать текстовое представление значения поля по умолчанию.

Экземпляр элемента системы может содержать только одну копию одного и того же параметра.

Для совместимости с предыдущей версией параметр помеченный атрибутом many со значением true считается параметром типа list.

Имена параметров input и output являются частично зарезервированными и не должны использоваться при описании типов соединений.

Имена параметров state и stateargs, так же являются частично зарезервированными, но они должны быть описаны для каждого типа устройства.

Состояние элемента определяется тремя параметрами:

state - визуальное состояние элемента. Всегда имеет тип ltree. Должно быть связано с перечисляемым типом при помощи атрибута enum.

stateargs - дополнительные состояния элемента. Всегда имеет тип args. Должно быть связано с перечисляемым типом при помощи атрибута enum.

4. pin

Тег pin может содержать следующие атрибуты:

type - тип разъема. Обязательный атрибут.

abstract - булево значение, помечающее тип как абстрактный. Т.е. запрещающий создание экземпляров такого типа. По умолчанию считается равным false.

many - булево значение указывающее что из данного разъема может выходить несколько соединений. По умолчанию считается равным false.

must - булево значение указывающее что данный разъем обязательно должен быть соединен. По умолчанию считается равным false.

base - базовый тип элемента. По умолчанию Pin.

5. link

Тег link может содержать следующие атрибуты:

type - тип соединения. Обязательный атрибут.

abstract - булево значение, помечающее тип как абстрактный. Т.е. запрещающий создание экземпляров такого типа. По умолчанию считается равным false.

in - тип входного разъема. Обязательный атрибут.

out - тип выходного разъема. Обязательный атрибут.

base - базовый тип элемента. По умолчанию Link.

6. item

Тег item может содержать следующие атрибуты:

type - тип устройства. Обязательный атрибут.

abstract - булево значение, помечающее тип как абстрактный. Т.е. запрещающий создание экземпляров такого типа. По умолчанию считается равным false.

public - булево значение, помечающее тип как доступный для внешних систем. Т.е. указывает, что компилятор должен создать специальные типы в пространстве имен @public для использования их в качестве параметров soap веб-сервиса. По умолчанию считается равным false.

base - базовый тип элемента. По умолчанию Item.

Тело тега item может содержать произвольное количество следующих тегов:

pin - указывает тип разъема.

Тег pin может содержать следующие атрибуты:

type - тип разъема. Обязательный атрибут.

name - уникальное для устройства имя разъема. Используется для связывания с графическим отображением устройства. . Если для разъема не указано имя, то его имя совпадает с его типом.

many - булево значение указывающее, что из данного разъема может выходить несколько соединений. По умолчанию берется значение атрибута из базового класса.

must - булево значение указывающее, что данный разъем обязательно должен быть соединен. По умолчанию берется значение атрибута из базового класса.

repeat - строковое значение, задающее диапазон номеров, имена дубликатов, разъемы вида 1..8. Вместо такого разъема создаются его копии с добавлением к имени индекса из дипазона.

Внутренний для устройства разъем не может содержать дополнительных параметров.

7. event

Тег event может содержать следующие атрибуты:

type - тип события. Обязательный атрибут.

abstract - булево значение, помечающее тип как абстрактный. Т.е. запрещающий создание экземпляров такого типа. По умолчанию считается равным false.

base - базовый тип элемента. По умолчанию Event.

Замечания

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

Dynamic TypeDef

Динамическое описание типа позволяет во время исполнения программы строить визуальные формы, для редактирование некоторого набора параметров содержащихся в плоском json документе, который в свою очередь полностью содержится в одном обычном параметре.

Т.е. для Dynamic TypeDef необходимо два параметра внутри одного типа.

Например:

<item type="TestItem">
   <param name="settings" type="json" typedef="typedef" />
   <param name="typedef" type="xml"/>
</item>

Тип TestItem содержит параметр settings типа json описание к которому содержится в параметре typedef типа xml.

Dynamic TypeDef представляет собой подмножество основного языка TypeDef, в котором произвольный корневой элемент может содержать один или несколько тегов param со всеми описанными выше атрибутами, и таким образом описывает параметры плоского json документа.

Например если параметр typedef содержит:

<root>
   <param name="enabled" type="bool" />
   <param name="list" type="list" />
   <param name="timeout" type="int" unit="second">500</param>
</root>

Тогда параметр settings будет содержать json документ вида:

{
   enabled: false,
   list: null,
   timeout: 500
}

Отметим что данную технологию не следует использовать для расширения типа объектов динамическими параметрами, т.к. само описание динамического типа хранится так же в параметре конкретного (а не любого) экземпляра типа. Поэтому Dynamic TypeDef следует использовать только для расширения конкретного экземпляра типа, как например внутри триггеров EGS.