CLEAR

Clear Language for Entity Adequate Representation

Short guide

Version 7.0 Date: 2008-01-31

1. Overview

This language is designed for platform independent entity representation for memory structures, storage and network interactions as well. It is next step in data representation languages evolution after markup languages, so it is based on both, XML experience and binary data encoding. But it is devoid of indeterminacy on the one hand and is human understandable on the other hand. Clear language structures are simple and obvious so do not expect something supernatural here. It is simple and clear...

2. Requirements

• Compact and efficient
• Expressive and human-readable
• High-performance parsing
• Single-meaning syntax and modeling rules
• Native hierarchical, table, network and relational structures support
• Object-oriented and data types support
• Maps directly to programming-language structures
• Maps directly to network protocol packets
• Maps directly to database engine structures
• Self decrypted and extensible syntax
• UTF-8 support
• Security and data safety
• Transport independent
• BLOB support in BASE64
  

3. Fields

Fields are for holding named values as a entity properties. CLEAR gives possibility to defile field types using regular expressions. All characters except 0x00..0x1F, 0x25 ("%") and 0x5D ("]") are allowed in values without escaping. Escaped characters should be encoded as %NN where NN is hexadecimal character code (for example %10 or %25). Symbol 0x22 (double quotation) should be escaped only if it is the first letter in value.

Fields are of the following two formats. First is simple:

Syntax: FieldName[value]

Second format allows to use 0x5D ("]") without escaping and used for regular expressions and other values which oftenly uses square brackets: Name["value-with-]-symbol"]. But combination of 0x22 (double quotation) and 0x5D ("]") should be escaped as in example: Name["value-with-%22]-symbols"]

4. Links

Format of links is similar to fields first format except of using 0x3E (">") instead of
0x5D ("]").

Syntax: LinkName<URL>
Example: MySite<http://meta-systems.com.ua/>

5. Sets

Format of sets is similar to fields first format except of using 0x3E ("}") instead of
0x5D ("]").

Syntax: SetName{item-1,...,item-N}
Example: Colors{green,navy,yellow}

6. Entities and hierarchy

CLEAR allows organizing fields, sets and links into entities or objects. Entities are separated with line breaks (0x0D 0x0A). Objects can be organized hierarchically as trees in markup languages. Numbers in the beginning of any row are hierarchy level, for example:

1: Node1:Class1 Field1[value1] Field2[Value2] Link1<link1>
2:   SubNode1 Field3[value3] Set1{} Set2{item4,item5} Field4[value4]
2:   SubNode2 Field5[value5] Field6[value6]
3:     SubSubNode1 Set3{item6,item7} Field7[value7] Link2<link2>
2:   SubNode3 Field9[value9]
3:     SubSubNode2:Class2,Class3 Field10[value10] Link3<link3>

Thanks to level numbering we can skip branches and quickly parse to the necessary entity. It is also releases us of "end" keywords needed in other languages to close tree levels. In CLEAR, for example, level 3 object ends when next level 3 or level 2 object starts (generally when sibling or higher level object starts or EOF reached).

7. Entities Classes and Properties naming

Entity name and class definitions are precedes fields, links and sets declarations. CLEAR allows multiple for inheritance and allows entity without ancestor class at all. Classes can be defined in *.model files as type declarations. Classes separates by ":" from entity name and separates by "," from each other. For example:

1: Node1:Class1 Field1[value1] Field2[value2]
2:   SubNode1:Class2,Class3 Field3[value3]
2:   SubNode2 F[val1] F[val2] [val3] [val4] <url1>

We need to give user possibility to encode any symbol of 0x00-0xFF in entity names and class names, so 0x00-0x1F should be escaped as - %1F, also we need to escape following: colon (":") as %3A, dash ("-") as %2D, equality ("=") as %3D, plus ("+") as %2B, star ("*") as %2A, comma (",") as %2C and space as %20. So we escape only 39 chars of 256 set.

Previous example shows us fields and links without name. CLEAR allows having multiple properties (fields, links and sets) with one name or properties without name. Parser organizes those properties into arrays so we can access values by property name or array index.

8. Folders

Folders are entities used for grouping other entities. Folders have colon (":") but have no class specified. For example:

1: Folder:
2:   SubNode1 Field1[value1] Field2[value2]
2:   SubNode2 Field3[value3] Field4[value4]


9. Members

Members are complex properties of parent entities. Members have "#" as a first letter in their names. For example:

1: Node1:Class1
2:   #SubNode1 Field3[value3] Field4[value4]
2:   #SubNode2 Field5[value5] Field6[value6]


10. CLEAR model files (*.model)

Data definition files contain types and classes definitions. Model files are of common CLEAR format. See examples and explanations further at this guide.

11. CLEAR files (*.clear)

CLEAR have default extension for data files. Root entity contains links to data definition (*.model) files. For example:

1: Node1:CLEAR <http://xross.net.ua/clear.model> <models/example.model>
2:   SubNode01 Field2[value2]

12. Comments

Lines which not started with "N: " (where N is decimal number) are commented. For example:

// comments here
1: Node1:Class1 Field1[value1]
-- comments here


13. Types

In the following example you can see type definitions as regular expression and as enumerated dictionary. Type definitions marked with "Type" class and all should be at the second level of model file (directly under root node).

1: ExampleModel
2:   float:Type  ["^-?\d*\.?\d*$"]
2:   string:Type [".*"]
2:   Align:Type  {Top,Right,Bottom,Left}
2:   Class1 Aligns{Top,Left:Align} Align[Align]
2:   Class2 Field1[0:float] Field2[float]
3:     #Member Set1{0,12.5,15.1:float} Set2{string}


14. Classes

In previous example there are Class1 and Class2 declared.