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 |}