bundles/org.simantics.databoard/src-isv/spec/Text Format.mediawiki

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