]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.databoard/src-isv/spec/Text Format.mediawiki
(refs #7595) Started SCL/Reflection module
[simantics/platform.git] / bundles / org.simantics.databoard / src-isv / spec / Text Format.mediawiki
1 =Type Notation=
2 Types are written with ''type definitions'' <tt>''type <name> = <type>''</tt>. 
3 The builtin types are denoted by their names (<tt>Boolean</tt>, <tt>Byte</tt>, <tt>Integer</tt>, <tt>Long</tt>, <tt>Float</tt>, <tt>Double</tt>, <tt>String</tt>, <tt>Variant</tt>)
4     type Name = String
5     type Length = Integer
6
7 Complex type definitions and in particular recursive ones can be defined in pieces by giving names to types:
8     type NodeDescription = referable { name : String, children : NodeDescription[] }
9
10 All other type constructors have form <tt>C(T<sub>1</sub>, ..., T<sub>k</sub>)</tt>, where <tt>C</tt> is a type constructor
11 and parameters are datatypes. The following constructors are defined:
12     type Example = Optional( BaseType )
13
14 Parametrised type constructors can be defined as follows:
15     type Tree(A) = | Leaf A | Node referable { left : Tree(A), right : Tree(A) }
16     
17     type Sample(Value) = { time : Double, value : Value }
18
19 ==Meta-data==
20 Built-in types can be annotated. Annotations are written as <tt>T(key<sub>1</sub>=value<sub>1</sub>, ..., key<sub>k</sub>=value<sub>k</sub>)</tt>,
21 where <tt>key<sub>i</sub></tt> is an identifier and <tt>value<sub>i</sub></tt> a value of some built-in type (depending on the annotation).
22
23     type value = Integer(range=[1..10000])
24     type Probability = Double(range=[0..1.0])
25     type XML = String(mimeType="text/xml") 
26     type Html = String(pattern="^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?", length=[..4096])
27
28
29 The following annotations are defined:
30 * all numerical types
31 ** unit : String
32 ** range: Range
33 * String
34 ** pattern : String (regular expression pattern of allowed strings, case sensitive)
35 ** mimeType : String
36 ** length : Range
37
38     type Size = Integer(range=[1..10000], unit="m")
39     type Amplitude = Double(range=[-1.0..1.0])
40     type Frequency = Double(unit="1/s")
41     type Document = String(mimeType="text/xml")
42
43 ==Record==
44 A record type is constructed as <tt>{ f<sub>1</sub> : T<sub>1</sub>, ..., f<sub>k</sub> : T<sub>k</sub> }</tt>,
45 where <tt>f<sub>i</sub></tt> is a field name and <tt>T<sub>i</sub></tt> its datatype.  A field name cannot be empty and two field names cannot
46 be equal.
47 Field names are usually written in lowercase.
48     type Color = { red : Double, 
49                    green : Double,
50                    blue : Double }
51
52 ===Referable Record===
53 Referable record is a record prefixed with keyword <tt>referable</tt>.     
54     type Tree = referable { children : Tree[] }
55
56 ====Tuple Type====
57 A tuple type is a special case of record type where all components have empty names. The construction is in the following format (''T''<sub>1</sub>, ..., ''T''<sub>k</sub>).
58     type Vector = (Integer, Integer, Integer)
59
60 ==Union==
61 A union type is constructed as <tt>| n<sub>1</sub> T<sub>1</sub> | ... | n<sub>k</sub> T<sub>k</sub></tt>, where <tt>n<sub>i</sub></tt> is a tag name and <tt>T<sub>i</sub></tt> its datatype. 
62 The tag type is optional and is assumed to be <tt>{}</tt>, if left out. Tag names have to be non-empty and distinct.
63 Tag names are usually capitalized.    
64     type Color = | RGB (Float, Float, Float)
65                  | RGBA (Float, Float, Float, Float)
66     
67 Enumerations are also unions. The type names are left out. Name of the type is used as the tag name. 
68     type Method = | Disabled | Adaptive | Manual
69     
70     type CommandResponse = | Success
71                            | Error String
72
73 A tag may have the same name as a builtin datatype
74     type Example = | Double Double | Long Long
75
76 ==Array==
77 The textual notation for the array type construction is <tt>T[]</tt>, where <tt>T</tt> is the base type.
78     type VGA = Double[320][240]
79     type Names = String[]
80
81 Minimum and maximum length of the array can be specified as <tt>T[a..]</tt>, <tt>T[..b]</tt>, <tt>T[a..b]</tt> or <tt>T[a]</tt>,
82 where <tt>a</tt> and <tt>b</tt> are integers and <tt>a</tt> &le; <tt>b</tt>.
83 *Exact Value <tt>Double[ 0 ]</tt>
84 *Unlimited <tt>Double[]</tt>
85 *Limited <tt>Double[ ..100 ]</tt>, <tt>Double[ 10..100 ]</tt>, <tt>Double[ 10.. ]</tt>
86
87 ==Map==
88 Map type is defined as <tt>Map(K, V)</tt>, where <tt>K</tt> is key datatype, and <tt>V</tt> is value datatype.
89
90     type TimeSeries = Map( Long(unit="ms"), Double );
91     type PropertyMap = Map( String, String )
92
93 ==Variant==
94 If is defined as <tt>''type : value''</tt>. 
95  50 : Integer
96  {x=50, y=50, z=50} : { x:Double, y:Double, z:Double }
97  (50, 50, 50) : { x:Double, y:Double, z:Double }
98
99 ==Optional==
100 An optional type is constructed with a base type. Its values are the values of
101 the base type and a special value ''null''.
102
103     type Name = Optional( String )
104     exmpl1 : Name = "Hei"
105     exmpl2 : Name = null
106     
107 =Value Notation=
108 Value if (''.dbv'') is a text file that contains a single data value in text format. 
109 The type must be known to the reader. 
110
111 Value definition file is a text file (''.dbd'') that contains a list of value definitions.
112 There is a name, type, and value in a ''Value definition'' in the following format: <tt>''<name> : <type> = <value>''</tt>. 
113
114 It is assumed that the datatype of the value written in textual format is always known
115 in the context. Thus it is not necessary to be able to completely infer the type from
116 the value notation itself.
117
118   obj1 : Integer = 5
119   obj2 : { name : String } = { name = "ABC" }
120   obj3 : Node = { id = "123", parent = obj4 }
121
122 ''Strings'' are written by enclosing the string in double quotes. The special characters 
123 in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089]
124  "some string"
125  "string with special characters such as:\n - \\\n - \"\n" 
126
127 ''Long strings'' containing special characters and new lines are enclosed in triple double quotes:
128  """Long string
129  spanning multiple
130  lines"""
131 Characters cannot be escaped in this notation (?).
132
133 ''Integers'' are specified with a sequence of digits preceded by an optional '-'. ''Floating point numbers'' can contain also dot and exponent. The exact syntax follows the Java specification for ''int'' and ''double'' literals.
134  1
135  -345
136  3.1415
137  1e-10
138
139 ==Record==
140 The fields of a record value are enclosed in curly brackets {} and separated by comma. Each field consists of the field name, equality mark and the value.
141    pink : Color = { red = 1.0, green = 0.4, blue = 0.4 }
142
143 Long field names are escaped with single quotes. The special characters 
144 in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089]
145     type Example = { 'long field name' : Double }
146     value : Example = { 'long field name' = 5.0 }
147
148 ===Referable Record===
149 value in the following format: ''<name> : <type> = <value>''. 
150 Referable values are referred by name. 
151     root : Tree = { children = [ node1, node2 ] }
152     node1 : Tree = { children = [] }
153     node2 : Tree = { children = [] }
154
155 ===Tuple Type===
156     vec1 : Vector = (1, 2, 3)
157
158 When exactly one value is enclosed in parenthesis, the parenthesis are interpreted as grouping not as a tuple. Thus the following two lines are equal:
159  (34)
160  34
161
162 ==Union==
163 The value consists of the union tag name followed by a value:
164     result : CommandResponse = Error "The method call failed."
165     white : Color = RGBA (1,1,1,0)
166
167 Long union tags are escaped with single quotes. The special characters 
168 in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089]
169     type Example2 = | 'long union name' (1,1,1)
170
171 ==Array==
172 The values are enclosed in brackets [] and separated by comma.
173     image : Names = ["a", "b", "c"]
174
175 ==Map==
176 Map value is a collection of entries. They are enclosed in curly brackets {} and separated by comma (,). Each entry consists of the key name, equals (=) mark and the value.
177     properties : PropertyMap = map { Name = "Somename", Id = "6.0" }
178
179 Long field names are escaped with single quotes. The special characters 
180 in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089]
181     properties : PropertyMap = map { "string key name" = "5.0", "another key name" = "6.0" }
182
183 ==Variant==
184 Type can be omited for strings and booleans
185  "Hello World" : String
186  "Hello World"
187  true : Boolean
188  true 
189
190 Type can also be omited for numbers with the following rule. If there is a full stop (.) then the type is a Double, otherwise an Integer.
191  5.0 : Double
192  5.0
193  5 : Integer
194  5
195
196 ==Optional==
197 Record fields of optional type can be omited, if there is no value.
198     type Example = {
199              name : Optional (String)
200          }
201     exmpl : Example = {}
202     exmp2 : Example = { name = "abc" }
203
204
205 =File types=
206 {| border="1" cellpadding="3" cellspacing="0" align="center"
207 |'''Extension'''
208 |'''Description'''
209 |- 
210 |<tt>.dbt</tt> ||Databoard Type Definition File. Consists of type definitions in text format.
211 |- 
212 |<tt>.dbd</tt> ||Databoard Value Definition file. Consists of value definitions in text format.
213 |- 
214 |<tt>.dbv</tt> ||Databoard Value File. Contains a single value in text format without type information.
215 |}