Спецификация текстового словаря

Оглавление

1 Заголовок
2 Теги
3 Ограничения словаря

Словарь состоит из следующих компонент:

заголовок - содержит идентификаторы словаря;
тэги - элементы в USDS-документе;
ограничения - дополнительные правила построения документов USDS.

При сохранении словаря в текстовый файл рекомендуется использовать расширение udic и кодировку UTF-8. Один текстовый файл может содержать словарей с разными идентификаторами и версиями. В бинарный документ USDS добавляется только один словарь - с помощью которой было создано тело документа.

Пример файла с несколькими словарями:

hell_world.udic

USDS DICTIONARY ID=888 v.1.0
{
    1: STRUCT I
    {
        1: UNSIGNED VARINT n;
        2: DOUBLE s;
        3: STRING<UTF-8> g;
        4: LONG t;
        5: BOOLEAN b;
    } RESTRICT {notRoot;}

    2: STRUCT S
    {
        1: UNSIGNED VARINT n;
        2: INT m;
        3: LONG s;
        4: LONG e;
        5: ARRAY<I> v;
    }
} 

USDS DICTIONARY ID=888 v.1.1
{
    1: STRUCT I
    {
        1: UNSIGNED VARINT n;
        2: DOUBLE s;
        3: STRING<UTF-8> g;
        4: LONG t;
        5: BOOLEAN b;
        6: BOOLEAN с;
    } RESTRICT {notRoot;}

    2: STRUCT S
    {
        1: UNSIGNED VARINT n;
        2: INT m;
        3: LONG s;
        4: LONG e;
        5: ARRAY<I> v;
    }
}

Заголовок

Заголовок имеет следующий формат:

На рисунке обозначено:

идентификатор словаря (Dictionary identifier) - целочисленный идентификатор словаря, значение от 0 до 2147483647. Идентификаторы от 1 до 65535 зарезервированы для стандартных публичных словарей (HTML, SQL, JavaScript и т.д.);
основная версия (Major version) - целое число от 0 до 255;
промежуточная версия (Minor version) - целое число от 0 до 255.

Идентификатор словаря и версии используются для контроля целостности документов USDS и уменьшения их размера. Например, при установке сетевого соединения вы передаете клиенту словарь и его идентификатор, а в дальнейшем - только идентификатор словаря и тело документа. Также возможна ситуация, когда клиенту и серверу идентификатор Словаря задается на этапе компиляции (или несколько его версий), тогда по сети всегда передаются только идентификатор и тело документа.

Если вы всегда включаете словарь в тело документа (например, конфигурационные файлы приложения), то идентификатор словаря может быть установлен как 0 (ID=0). Рекомендуется соблюдать версионность словарей даже в этом случае.

идентификатор тега (Tag identifier) - целое число, значения от 1 до 2147483647, сквозная нумерация, должно быть уникально в рамках одной версии словаря;
тип данных для тега (Tag type): один из типов данных USDS (см. раздел ниже ) или имя другого тега (будет использован тип данных этого тега);
имя тега (Tag name) - текстовое имя тега: от 1 символа, только латинские символы, цифры и знак подчеркивания '_'. Первый символ имени не может быть цифрой. Уникально в рамках словаря;
ограничения (RESTRICT) - дополнительные правила использования тега. Для всех тегов доступны следующие ограничения:

notRoot - служит для обозначения тегов, которые не могут быть корневыми элементами в Теле документа USDS. Например для HTML корневым является тег <html>. В словаре может быть объявлено несколько корневых тегов.

Типы данных

Полный список типов данных приведен ниже:

Не удалось найти URL спецификации гаджета

Простые типы

Теги с простыми типами данных (с 1 по 25 в таблице типов выше) объявляются следующим образом:

Для целых типов со знаком используется форма записи "Дополнительный код", или "Two's complement". Вещественные числа соответствуют стандарту IEEE 754, который поддерживается большинством аппаратных конфигураций.

Типы данных bigendian будут корректно обработаны на платформах Little-Endian и наоборот. Рекомендуется использовать bigendian только при передаче данных между двумя платформами Big-Endian.

Целые упакованные числа: типы данных varint и unsigned varint соответствуют спецификации Little Endian Base 128. Префикс bigendian для данного типа недопустим, но на платформах Big-Endian данные будут корректно обработаны. Использование varint может уменьшить размер документа USDS. При чтении тела документа USDS парсер вернет ошибку, если упакованное число превысит размер переменной, в которую десериализуются данные (зависит от языка программирования).

Для всех типов данных, кроме BOOLEAN доступны следующие ограничения:

values - допустимые значения: диапазоны или список конкретных значений;
precision - точность. Задается как для вещественных, так и для целых чисел.

Структуры

Структуры в USDS используются для сериализации классов и структур, в словаре они объявляются следующим образом:

На рисунке обозначено:

идентификатор поля (Field identifier) - целое число, значения от 1 до 2147483647, сквозная нумерация в рамках тега, уникально в рамках одного тега;
тип данных поля (Field type): один из типов данных USDS кроме "STRUCT", или имя другого тега (в том числе с типом "STRUCT"), или имя этого же тега (в этом случае он должен быть optional);
имя поля (Field name): от 1 символа, только латинские символы, цифры и знак подчеркивания '_'. Первый символ не может быть цифрой. Уникально в рамках структуры;
для полей доступны следующие ограничения:

все ограничения, которые есть у типа данных поля;
default - значение по умолчанию: если значение поля соответствует дефолтному, то оно не включается в документ USDS, уменьшая тем самым его размер. Значения по умолчанию доступны только для простых типов (1-25) и типа STRING;
optional - опциональные поля: если поле включено в документ USDS, то парсер вернет значение поля. Если не включено - парсер вернет признак "NULL". Опциональное поле не может иметь значения по умолчанию.

Массивы

Теги с типом данных Массив описываются следующим образом:

На рисунке обозначено:

Element's type - тип данных для элементов массива, допустимы следующие типы:

один из простых типов данных USDS (1-25);
STRING;
имя другого тега с любым типом данных;
список из нескольких тегов с любым типом данных: в этом случае в массив могут быть включены любые из перечисленных тегов (полиморфный массив);

для массивов доступны следующие ограничения:

все ограничения, которые есть у типа данных элемента массива;
fixSize: фиксированное количество элементов в массиве. Максимальный размер массива зависит от используемого языка программирования и разрядности ОС;
minSize - минимальный размер массива, значения от 0. Не может быть указано совместно с fixSize;
maxSize - максимальный размер массива, значения от 1. Не может быть указано совместно с fixSize;
minOccure - только для полиморфных массивов: минимальное количество объектов указанного типа в массиве;
maxOccure - только для полиморфных массивов: максимальное количество объектов указанного типа в массиве.

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

Строки

Теги с типом "Строка" описываются следующим образом:

На рисунке обозначено:

Text encode - кодировка текста. Полный список поддерживаемых кодировок приведен в таблице ниже. В словаре может быть объявлено несколько тегов с разными кодировками;
для строк доступны следующие ограничения:

fixSize: фиксированное количество символов в строке (включая особенности каждой из кодировок). Значения от 1;
minSize: минимальное количество символов в строке, значения от 0. Нельзя задавать совместно с fixSize;
maxSize: максимальное количество символов в строке, значения от 1. Нельзя задавать совместно с fixSize;
values: регулярное выражение, которому должна соответствовать строка.

Не удалось найти URL спецификации гаджета

Списки

Теги с типом данных "Список" оптимизированы на работу с массивами данных, размер которых заранее не известен.

Element's type - тип данных для элементов списка, допустимы следующие типы:

один из простых типов данных USDS (1-25);
STRING;
имя другого тега с любым типом данных;
список из нескольких тегов с любым типом данных: в этом случае в список могут быть включены любые из перечисленных тегов (полиморфный список);

для списков доступны следующие ограничения:

все ограничения, которые есть у типа данных элемента списка;
minSize - минимальный размер списка, значения от 0;
maxSize - максимальный размер списка, значения от 1;
minOccure - только для полиморфных списков: минимальное количество объектов указанного типа в списке;
maxOccure - только для полиморфных списков: максимальное количество объектов указанного типа в списке.

Ассоциативные массивы (Map)

Теги содержат список пар "ключ - значение" (map) и описываются следующим образом:

На рисунке обозначено:

тип данных для ключей (Key type):

один из простых типов данных USDS (1-25);
STRING;
имя другого тега с любым типом данных;
список из нескольких тегов с любым типом данных: в этом случае ключами могут быть любые из перечисленных тегов (полиморфный ассоциированный массив);

тип данных для значений (Value type):

один из простых типов данных USDS (1-25);
STRING;
имя другого тега с любым типом данных;
список из нескольких тегов с любым типом данных: в этом случае значениями могут быть любые из перечисленных тегов (полиморфный ассоциированный массив);

доступны следующие ограничения:

все ограничения, которые есть у типов данных ключей и значений;
minSize - минимальный размер массива, значения от 0;
maxSize - максимальный размер массива, значения от 1;
minOccure - только для полиморфных массивов: минимальное количество объектов указанного типа в массиве;
maxOccure - только для полиморфных массивов: максимальное количество объектов указанного типа в массиве.

Полиморфные теги

Полиморфные теги используются для поддержки полиморфизма в документах USDS. Например, тег <BODY> может включать в себя произвольное количество тегов <H1> и <H2> в любом порядке. Чтобы реализовать данную конструкцию в USDS необходимо в словаре объявить следующие теги:

1: STRUCT H1 { ... }
2: STRUCT H2 { ... }
3: POLYMORPH<H1, H2> BodySubTags;
4: STRUCT Body
{
    1: LIST<BodySubTags> subTags;
}

Элементами полиморфа могут быть только другие теги, но они в свою очередь могут быть любого типа.

На рисунке обозначено:

Tag names - список тегов, входящих в полиморф, любого типа включая другие полиморфы.
ограничения:

доступно только общее для всех тегов ограничение - notRoot.

Ограничения словаря

Для словаря доступны следующие ограничения:

minOccure - минимальное количество объектов указанного типа в USDS документе, значения от 0;
maxOccure - максимальное количество объектов указанного типа в USDS документе, значения от 1.

2015.08.10 Андрей Абрамов
Обновлено 2015.10.30

Comments

Не удалось найти URL спецификации гаджета

Languages

Последние действия на сайте