Configuration Definition Language (CDL) specification
Table of Contents
1.1. Purpose
The Configuration Definition Language (CDL) is an application-level language,
that allows programmers to define the structure of configuration files, its format,
interdependents and limitations among parameters in human-readable view.
The main purposes are:
1. Easy-to-use API for programmers;
2. Human-readable format of files for users;
3. Easy language for definitions of configuration rules, and simple check
possibility of them.
The specification of the language are very young, and all the time have evolution.
This specification defines the 1.0 verion of the CDL, and some future language
directions.
1.2. Requirements
The keywords in upper case:
- "MUST" mandatore implementation in the configuration or parser;
- "MUST NOT" prohibit such implementation;
- "MAY" desired implementation;
- "OPTIONAL" optional, not important implementation.
Language uses the tag model, such as XML or HTML languages.
Configuration can consists of many files, but logically consists of two parts:
- Definition part, which describes structure and parameters of configuration file.
With help of this, programmer can define users tags, parameters of such tags and
constraints and limitations between these parameters.
- Configuration part, which stores the configuration information of program
correspondingly to definition part.
All user informations in language stored in the pairs of parameter -- values list
view. Tags uses to group iformation. Before use counfiguration, it must be
described by the language -- specific keywords. This description needed to define
the interdependents and limitations between the configuration data. Under such
approach programmer not need to verify parameters of configuration at the runtime,-
all work will be make by the parser of the CDL, and if errors will be have a place
in the configuration, user take information about them from the parser.
2.1. Symbols, terms, definitions.
The language are case -- sensitive. To define language keywords can be used lower
and upper case latin symbols [A-Z, a-z], arabic ciphers [0-9], underscore and
the minus sign.
Some other auxiliary signs uses for language purposes:
comma - separate the values in the list;
quote or double quote - define the string;
semicolon - mark the end of the expression;
space, tab, CR, LF - the design symbols;
square brackets - to define the index;
(,),&,|,! - in logic expressions.
= - for assignments.
Inside the strings back slash character used to define special symbols:
\n - CR LF sequence;
\r - LF;
\t - the tab symbol;
\\ - the backslash character itself;
\0xNUM - hexadecimal representation of the symbol;
If string value do not use special or auxiliary symbols, than they may be
represent without quotes,- parser MUST be recognize them as string value.
For the purposes of this specification the following definitions apply:
'identifier' - the sequense of latin symbols, arabic ciphers, or underscore
symbol, started from latin symbols or underscore;
'parameter' - the indentifier, which can be corresponded with one or more values;
'tag' - identifier inside left and right brockets;
'expression' - the aggregate of parameter and them values.
2.2. Syntax
2.2.1. Parameters
The values of parameters is defined by this method:
parameter = value1, value2, ..., value_n;
Each parameter can have the list of values, accessed by its indexes (as C linear
array).
2.2.2 Tags
There are two types of the tags: paired and non-paired. The paired tag have the
begin tag, (<tag1> for example) and the end tag. The name of the end tag equals the
name of begin tag, but begins from the '/' sign (</tag1> for example). The text
between begin and end tags called the contents of the tag and consists of the
parameters and other tags. The one-paired tags consists only from begin tag, and
not have their contents. The begin tags (as paired so non-paired) can have tag specification,
which not have the pay load and uses to define some specific tag features.
The tag specification is the list of parameters and their values, divided by the
comma signs. Each parameter in the tag specification can have ONLY ONE value in
contrast of the parameters iside the tag contents.
2.3. Data types
CDL has seven predefined data types, corresponded to C/C++ data types, plus time
and timestamp types:
integer - signed integer values in range -2,147,483,648 <= X <= 2,147,483,647;
boolean - can have one of the values (0, 1 or true, false, of yes, no);
float - floating point values in range 2.23 10^-308 < |X| < 1.79 10^308;
time - the time in format HH:MM:SS;
datetime - date and time in format: HH:MM:SS DD:MM:YYYY;
string - consistency of symbols, enclosed in single or double quotes. If in
context of the string special symbols not uses, than quotes can be
ignored.
binary - binary data, represented as consistency of the hexadecimal --
represented symbols.
2.4. Logical expressions
In definition part some parameters used to define configuration content checking. For this purpose
logical expressions can be used. Operands of these expressions is tag parameters, the values are
existance (logical 1) or absence (logical 0) of them. Expression operators are used:
& - logical AND;
| - logical OR;
! - logical negation (NOT);
() - to group operands.
For example:
<!tag>
...
name = some_tag;
must_be = param_1 | (param_2 & param3);
...
<!param>
name = param_1;
...
</!param>
<!param>
name = param_2;
...
</!param>
<!param>
name = param_3;
...
</!param>
</!tag>
Keyword "must_be" determine, what param_1 or param_2 + param_3 MUST be defined in confiuration part
by user.
2.5. Keywords
if, then, else
exist - to check
define, undef - to define/undefine variables;
coming soon....
The definitions used to define user (information) tags, their parameters and
limitations between them. For language purposes the tag names begining from '!'
symbol are reserved. Tags may be enclosed one in another, due to we can have
configuration tree.
3.1. Common tags
<!include> tag uses to include another files, their specification parameters are:
file - the path to the included file.
<!locale> tag uses to define the default locale of the configuration file, their
specification parameters are:
cp - code page of the configuration file;
lng - language of the configuration file.
<!cdl> tag uses to define language specific data.
ver - the version of the CDL.
<!--></!--> tag uses to add the comments into the configuration.
3.2. User tag and parameter definition
For user tag definition uses special reserved paired tag <!tag>. It have some
predefined parameters with predefined data types. Except this, the user <!tag>
not have differences from user tags. Their parameters are:
name - the name of the tag (string data type);
must_be - the list of parameters of the tag, which must be defined
inside the tag, logical operators are allowed between them (string
data type);
unique - the list of parameters, values of which must have unique
values inside the parent tag (string data type);
The definition of parameters makes inside the tag definition, in the <!tag>
content. For user parameters definition uses special reserved paired tag <!param>.
Just as <!tag> it have some predefined parameters also:
name - the name of the parameter (string data type);
type - type of the parameter (string data type);
default - default value, if this parameter was not defined inside the
tag in the configuration (string data type);
enum - the list of possible values (string data type);
min_size and max_size - to declare allowed range of values (double data type).
For example, to define configuration computer 'hardware list', which have five
devices: CPU, RAM, Video card, COM1 and COM2 ports, with such restrictions:
- CPU: must have CPU_Name(string), Frequency(integer) parameters, and CPU_Name
can have only some of predefined names;
- RAM: must have the Value(int) of memory and can have the Frequency(int) of it;
- Video card: must have IRQ(int) and MEM(string) and can have dimension params
x_size(int), y_size(int);
- COM ports: must have IRQ(int) and MEM(string).
so we can define file "hardware_list.def":
<!cdl ver = 1.0>
<!locale cp = ISO-8859-5, lang = ru>
<!tag>
name = "CPU";
must_be = manufacturer, frequency;
<!param>
name = manufacturer;
type = string;
enum = AMD, Intel, Motorola;
default = AMD;
</!param>
<!param>
name = frequency;
type = integer;
</!param>
</!tag>
<!tag>
name = RAM;
must_be = value;
<!param>
name = value;
type = integer;
</!param>
<!param>
name = freq;
type = integer;
</!param>
</!tag>
<!tag>
name = VIDEO;
must_be = irq, mem;
<!param>
name = irq;
type = integer;
min_size = 10;
max_size = 255;
default = 10;
</!param>
<!param>
name = mem;
type = string;
</!param>
<!param>
name = x_size;
type = integer;
min_size = 800;
max_size = 2200;
</!param>
<!param>
name = y_size;
type = integer;
min_size = 600;
max_size = 1280;
</!param>
</!tag>
<!tag>
name = COM;
must_be = irq, mem;
unique = irq, mem;
<!param>
name = irq;
type = integer;
min_size = 3;
max_size = 255;
</!param>
<!param>
name = mem;
type = string;
</!param>
</!tag>
and after that we can use such configuration file "hardware_list.cfg":
<!include file = hardware_list.def>
<CPU>
manufacturer = Intel;
frequency = 2800;
</CPU>
<RAM>
value = 1024;
</RAM>
<VIDEO>
irq = 11;
mem = "E8000000-EFFFFFFF";
x_size = 1024;
y_size = 768;
</VIDEO>
<!-- COM0>
<COM>
irq = 3;
mem = "0378-037f";
</COM>
<!-- COM1>
<COM>
irq = 4;
mem = "03f8-03ff";
</COM>
3.3. User tag specification parameters
The main idea of difference between tag specification parameters and tag content parameters conatins
in theirs purposes:
- tag contents uses to store configuration informatin, which not relate to the tag
itself,- it relate only to useful (configuration) information;
- tag specification, on the contrary, relate only to the tag itself.
Specification parameters uses for tags, which can't have useful information (Common tags in chapter
5.1 are one of such using), or in future, for specification tag visualization and access control (see Ch. 8).
This section describes common interface of parsing programs, uses CDL.
4.1. Accessing the data.
For access to data of the configuration file, user should give to parser the
"path" to needed parameter such as UNIX path notation: the slash is the root of
the configuration, tags is the "directories" and parameter name is the "file name".
If we have in one tag level any subtags with the equal names, than we can access
to such tags by their indexes. The parameters with equal names inside one tag are
denied (we can use one parameter with many values for that purposes).
For example, to acces such configuration:
<tag2> //tag one
param_1 = val_1, val_2, ...,val_n;
</tag2>
...
<tag2> //tag N
param_1 = val_1, val_2, ...,val_n;
</tag2>
we can use:
to val_1 of the param_1, tag2:
/tag2[N]/param_1[0] or
/tag2[N]/param_1
to val_n of the param_1, tag2 N:
/tag2[N]/param_1[n]
4.2. Inernationalization.
Coming soon...
CDL_SUCCESS success
CDL_TAG_VALUE_ERROR could not recognize parameter value
CDL_MEM_ALLOC_ERROR memory allocating error
CDL_STRING_NOT_FOUND could not find desired string
CDL_INCORRECT_TAG_CLOSURE incorrect tag closure
CDL_INCORRECT_TAG_NAME incorrect tag name
CDL_EMBEDDED_TAG_ERROR embedded tag error
CDL_TAG_NOT_FOUND the tag not found
CDL_INCORRECT_SYMBOL incorrect symbol
CDL_PARAMETER_VALUE_IS_NULL parameter not assigned a value
CDL_BRACKET_INCORRECT_CLOSED bracket in logical sequence was incorrect closed
CDL_LEFT_OPERAND_MISSING operand's stack is empty while close right bracket
CDL_INCORRECT_OPERAND_ORDER incorrect order of operands, possible logic
operand between there missing
CDL_FILE_IO_ERROR file i/o error
CDL_DTD_LOGIC_ERROR dtd structure logic error
CDL_STRING_ASSIGNMENT_ERROR string parameter values parsing error
CDL_INCORRECT_PARAM_CLOSURE incorrect DTD tag <!param> closure
CDL_DTD_DUPLICATE_PARAM the parameter is duplicated
CDL_UNKNOWN_PARAM_TYPE unknown parameter type
CDL_UNKNOWN_PARAM_NAME unkown DTD parameter name
CDL_TAG_NAME_NOT_DEFINED tag name not defined
CDL_PARAM_NAME_NOT_DEFINED parameter name not defined
CDL_PARAM_TYPE_NOT_DEFINED parameter type not defined
CDL_DUMP_ASSIGNMENT_ERROR binary parameter assignment incorrectly
CDL_DUMP_SYMBOLS_NOT_EVEN binary dump symbols not even
CDL_INCORRECT_DUMP_SYMBOL the dump symbol is not in 0-9 and Aa-Ff range
(not hex symbol)
CDL_STR_TO_TIME_ERROR incorrect time definition
CDL_STR_TO_DATETIME_ERROR incorrect datetime definition
CDL_ENUM_ASSIGNMENT_ERROR enum assignment error
CDL_TAG_NOT_DEFINED the tag is not defined
CDL_PARAMETER_WITHOUT_TAG the parameter defined ouside of the tag
CDL_PARAMETER_NOT_DEFINED parameter not defined for this tag
CDL_DTD_PARAMS_NOT_FOUND
CDL_INCORRECT_INCLUDE_DEF
CDL_INCORRECT_FILE_PATH
CDL_UNKNOWN_SYSTEM_TAG
CDL_STR_TO_INT_ERROR
CDL_STR_TO_FLOAT_ERROR
CDL_LIST_ASSIGNMENT_ERROR
CDL_POINTER_IS_NULL
CDL_UNKNOWN_ERROR
CDL_VALUE_NOT_UNIQUE
CDL_VALUE_NOT_ENUM
CDL_INVALID_PARAM_PATH
CDL_INVALID_TAG_PATH
CDL_DEFAULT_ASSIGNMENT_ERROR
CDL_VALUE_NOT_IN_RANGE
CDL_INTERNAL_PARSER_ERROR
|
