X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.databoard%2Fsrc-isv%2Fspec%2FText%20Format.mediawiki;h=0ced0641569486b39ee440e1d3cc33567881181d;hb=6bf51de1941aa1dc5ee0a3aa8c50d53168b0c068;hp=eb57f0e5a503ea3ee3ffde986757205646ff12f1;hpb=969bd23cab98a79ca9101af33334000879fb60c5;p=simantics%2Fplatform.git diff --git a/bundles/org.simantics.databoard/src-isv/spec/Text Format.mediawiki b/bundles/org.simantics.databoard/src-isv/spec/Text Format.mediawiki index eb57f0e5a..0ced06415 100644 --- a/bundles/org.simantics.databoard/src-isv/spec/Text Format.mediawiki +++ b/bundles/org.simantics.databoard/src-isv/spec/Text Format.mediawiki @@ -1,215 +1,215 @@ -=Type Notation= -Types are written with ''type definitions'' ''type = ''. -The builtin types are denoted by their names (Boolean, Byte, Integer, Long, Float, Double, String, Variant) - type Name = String - type Length = Integer - -Complex type definitions and in particular recursive ones can be defined in pieces by giving names to types: - type NodeDescription = referable { name : String, children : NodeDescription[] } - -All other type constructors have form C(T1, ..., Tk), where C is a type constructor -and parameters are datatypes. The following constructors are defined: - type Example = Optional( BaseType ) - -Parametrised type constructors can be defined as follows: - type Tree(A) = | Leaf A | Node referable { left : Tree(A), right : Tree(A) } - - type Sample(Value) = { time : Double, value : Value } - -==Meta-data== -Built-in types can be annotated. Annotations are written as T(key1=value1, ..., keyk=valuek), -where keyi is an identifier and valuei a value of some built-in type (depending on the annotation). - - type value = Integer(range=[1..10000]) - type Probability = Double(range=[0..1.0]) - type XML = String(mimeType="text/xml") - type Html = String(pattern="^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?", length=[..4096]) - - -The following annotations are defined: -* all numerical types -** unit : String -** range: Range -* String -** pattern : String (regular expression pattern of allowed strings, case sensitive) -** mimeType : String -** length : Range - - type Size = Integer(range=[1..10000], unit="m") - type Amplitude = Double(range=[-1.0..1.0]) - type Frequency = Double(unit="1/s") - type Document = String(mimeType="text/xml") - -==Record== -A record type is constructed as { f1 : T1, ..., fk : Tk }, -where fi is a field name and Ti its datatype. A field name cannot be empty and two field names cannot -be equal. -Field names are usually written in lowercase. - type Color = { red : Double, - green : Double, - blue : Double } - -===Referable Record=== -Referable record is a record prefixed with keyword referable. - type Tree = referable { children : Tree[] } - -====Tuple Type==== -A tuple type is a special case of record type where all components have empty names. The construction is in the following format (''T''1, ..., ''T''k). - type Vector = (Integer, Integer, Integer) - -==Union== -A union type is constructed as | n1 T1 | ... | nk Tk, where ni is a tag name and Ti its datatype. -The tag type is optional and is assumed to be {}, if left out. Tag names have to be non-empty and distinct. -Tag names are usually capitalized. - type Color = | RGB (Float, Float, Float) - | RGBA (Float, Float, Float, Float) - -Enumerations are also unions. The type names are left out. Name of the type is used as the tag name. - type Method = | Disabled | Adaptive | Manual - - type CommandResponse = | Success - | Error String - -A tag may have the same name as a builtin datatype - type Example = | Double Double | Long Long - -==Array== -The textual notation for the array type construction is T[], where T is the base type. - type VGA = Double[320][240] - type Names = String[] - -Minimum and maximum length of the array can be specified as T[a..], T[..b], T[a..b] or T[a], -where a and b are integers and a ≤ b. -*Exact Value Double[ 0 ] -*Unlimited Double[] -*Limited Double[ ..100 ], Double[ 10..100 ], Double[ 10.. ] - -==Map== -Map type is defined as Map(K, V), where K is key datatype, and V is value datatype. - - type TimeSeries = Map( Long(unit="ms"), Double ); - type PropertyMap = Map( String, String ) - -==Variant== -If is defined as ''type : value''. - 50 : Integer - {x=50, y=50, z=50} : { x:Double, y:Double, z:Double } - (50, 50, 50) : { x:Double, y:Double, z:Double } - -==Optional== -An optional type is constructed with a base type. Its values are the values of -the base type and a special value ''null''. - - type Name = Optional( String ) - exmpl1 : Name = "Hei" - exmpl2 : Name = null - -=Value Notation= -Value if (''.dbv'') is a text file that contains a single data value in text format. -The type must be known to the reader. - -Value definition file is a text file (''.dbd'') that contains a list of value definitions. -There is a name, type, and value in a ''Value definition'' in the following format: '' : = ''. - -It is assumed that the datatype of the value written in textual format is always known -in the context. Thus it is not necessary to be able to completely infer the type from -the value notation itself. - - obj1 : Integer = 5 - obj2 : { name : String } = { name = "ABC" } - obj3 : Node = { id = "123", parent = obj4 } - -''Strings'' are written by enclosing the string in double quotes. The special characters -in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089] - "some string" - "string with special characters such as:\n - \\\n - \"\n" - -''Long strings'' containing special characters and new lines are enclosed in triple double quotes: - """Long string - spanning multiple - lines""" -Characters cannot be escaped in this notation (?). - -''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. - 1 - -345 - 3.1415 - 1e-10 - -==Record== -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. - pink : Color = { red = 1.0, green = 0.4, blue = 0.4 } - -Long field names are escaped with single quotes. The special characters -in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089] - type Example = { 'long field name' : Double } - value : Example = { 'long field name' = 5.0 } - -===Referable Record=== -value in the following format: '' : = ''. -Referable values are referred by name. - root : Tree = { children = [ node1, node2 ] } - node1 : Tree = { children = [] } - node2 : Tree = { children = [] } - -===Tuple Type=== - vec1 : Vector = (1, 2, 3) - -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: - (34) - 34 - -==Union== -The value consists of the union tag name followed by a value: - result : CommandResponse = Error "The method call failed." - white : Color = RGBA (1,1,1,0) - -Long union tags are escaped with single quotes. The special characters -in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089] - type Example2 = | 'long union name' (1,1,1) - -==Array== -The values are enclosed in brackets [] and separated by comma. - image : Names = ["a", "b", "c"] - -==Map== -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. - properties : PropertyMap = map { Name = "Somename", Id = "6.0" } - -Long field names are escaped with single quotes. The special characters -in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089] - properties : PropertyMap = map { "string key name" = "5.0", "another key name" = "6.0" } - -==Variant== -Type can be omited for strings and booleans - "Hello World" : String - "Hello World" - true : Boolean - true - -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. - 5.0 : Double - 5.0 - 5 : Integer - 5 - -==Optional== -Record fields of optional type can be omited, if there is no value. - type Example = { - name : Optional (String) - } - exmpl : Example = {} - exmp2 : Example = { name = "abc" } - - -=File types= -{| border="1" cellpadding="3" cellspacing="0" align="center" -|'''Extension''' -|'''Description''' -|- -|.dbt ||Databoard Type Definition File. Consists of type definitions in text format. -|- -|.dbd ||Databoard Value Definition file. Consists of value definitions in text format. -|- -|.dbv ||Databoard Value File. Contains a single value in text format without type information. +=Type Notation= +Types are written with ''type definitions'' ''type = ''. +The builtin types are denoted by their names (Boolean, Byte, Integer, Long, Float, Double, String, Variant) + type Name = String + type Length = Integer + +Complex type definitions and in particular recursive ones can be defined in pieces by giving names to types: + type NodeDescription = referable { name : String, children : NodeDescription[] } + +All other type constructors have form C(T1, ..., Tk), where C is a type constructor +and parameters are datatypes. The following constructors are defined: + type Example = Optional( BaseType ) + +Parametrised type constructors can be defined as follows: + type Tree(A) = | Leaf A | Node referable { left : Tree(A), right : Tree(A) } + + type Sample(Value) = { time : Double, value : Value } + +==Meta-data== +Built-in types can be annotated. Annotations are written as T(key1=value1, ..., keyk=valuek), +where keyi is an identifier and valuei a value of some built-in type (depending on the annotation). + + type value = Integer(range=[1..10000]) + type Probability = Double(range=[0..1.0]) + type XML = String(mimeType="text/xml") + type Html = String(pattern="^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?", length=[..4096]) + + +The following annotations are defined: +* all numerical types +** unit : String +** range: Range +* String +** pattern : String (regular expression pattern of allowed strings, case sensitive) +** mimeType : String +** length : Range + + type Size = Integer(range=[1..10000], unit="m") + type Amplitude = Double(range=[-1.0..1.0]) + type Frequency = Double(unit="1/s") + type Document = String(mimeType="text/xml") + +==Record== +A record type is constructed as { f1 : T1, ..., fk : Tk }, +where fi is a field name and Ti its datatype. A field name cannot be empty and two field names cannot +be equal. +Field names are usually written in lowercase. + type Color = { red : Double, + green : Double, + blue : Double } + +===Referable Record=== +Referable record is a record prefixed with keyword referable. + type Tree = referable { children : Tree[] } + +====Tuple Type==== +A tuple type is a special case of record type where all components have empty names. The construction is in the following format (''T''1, ..., ''T''k). + type Vector = (Integer, Integer, Integer) + +==Union== +A union type is constructed as | n1 T1 | ... | nk Tk, where ni is a tag name and Ti its datatype. +The tag type is optional and is assumed to be {}, if left out. Tag names have to be non-empty and distinct. +Tag names are usually capitalized. + type Color = | RGB (Float, Float, Float) + | RGBA (Float, Float, Float, Float) + +Enumerations are also unions. The type names are left out. Name of the type is used as the tag name. + type Method = | Disabled | Adaptive | Manual + + type CommandResponse = | Success + | Error String + +A tag may have the same name as a builtin datatype + type Example = | Double Double | Long Long + +==Array== +The textual notation for the array type construction is T[], where T is the base type. + type VGA = Double[320][240] + type Names = String[] + +Minimum and maximum length of the array can be specified as T[a..], T[..b], T[a..b] or T[a], +where a and b are integers and a ≤ b. +*Exact Value Double[ 0 ] +*Unlimited Double[] +*Limited Double[ ..100 ], Double[ 10..100 ], Double[ 10.. ] + +==Map== +Map type is defined as Map(K, V), where K is key datatype, and V is value datatype. + + type TimeSeries = Map( Long(unit="ms"), Double ); + type PropertyMap = Map( String, String ) + +==Variant== +If is defined as ''type : value''. + 50 : Integer + {x=50, y=50, z=50} : { x:Double, y:Double, z:Double } + (50, 50, 50) : { x:Double, y:Double, z:Double } + +==Optional== +An optional type is constructed with a base type. Its values are the values of +the base type and a special value ''null''. + + type Name = Optional( String ) + exmpl1 : Name = "Hei" + exmpl2 : Name = null + +=Value Notation= +Value if (''.dbv'') is a text file that contains a single data value in text format. +The type must be known to the reader. + +Value definition file is a text file (''.dbd'') that contains a list of value definitions. +There is a name, type, and value in a ''Value definition'' in the following format: '' : = ''. + +It is assumed that the datatype of the value written in textual format is always known +in the context. Thus it is not necessary to be able to completely infer the type from +the value notation itself. + + obj1 : Integer = 5 + obj2 : { name : String } = { name = "ABC" } + obj3 : Node = { id = "123", parent = obj4 } + +''Strings'' are written by enclosing the string in double quotes. The special characters +in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089] + "some string" + "string with special characters such as:\n - \\\n - \"\n" + +''Long strings'' containing special characters and new lines are enclosed in triple double quotes: + """Long string + spanning multiple + lines""" +Characters cannot be escaped in this notation (?). + +''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. + 1 + -345 + 3.1415 + 1e-10 + +==Record== +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. + pink : Color = { red = 1.0, green = 0.4, blue = 0.4 } + +Long field names are escaped with single quotes. The special characters +in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089] + type Example = { 'long field name' : Double } + value : Example = { 'long field name' = 5.0 } + +===Referable Record=== +value in the following format: '' : = ''. +Referable values are referred by name. + root : Tree = { children = [ node1, node2 ] } + node1 : Tree = { children = [] } + node2 : Tree = { children = [] } + +===Tuple Type=== + vec1 : Vector = (1, 2, 3) + +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: + (34) + 34 + +==Union== +The value consists of the union tag name followed by a value: + result : CommandResponse = Error "The method call failed." + white : Color = RGBA (1,1,1,0) + +Long union tags are escaped with single quotes. The special characters +in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089] + type Example2 = | 'long union name' (1,1,1) + +==Array== +The values are enclosed in brackets [] and separated by comma. + image : Names = ["a", "b", "c"] + +==Map== +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. + properties : PropertyMap = map { Name = "Somename", Id = "6.0" } + +Long field names are escaped with single quotes. The special characters +in the strings are escaped following Java-specification. [http://java.sun.com/docs/books/jls/second_edition/html/lexical.doc.html#101089] + properties : PropertyMap = map { "string key name" = "5.0", "another key name" = "6.0" } + +==Variant== +Type can be omited for strings and booleans + "Hello World" : String + "Hello World" + true : Boolean + true + +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. + 5.0 : Double + 5.0 + 5 : Integer + 5 + +==Optional== +Record fields of optional type can be omited, if there is no value. + type Example = { + name : Optional (String) + } + exmpl : Example = {} + exmp2 : Example = { name = "abc" } + + +=File types= +{| border="1" cellpadding="3" cellspacing="0" align="center" +|'''Extension''' +|'''Description''' +|- +|.dbt ||Databoard Type Definition File. Consists of type definitions in text format. +|- +|.dbd ||Databoard Value Definition file. Consists of value definitions in text format. +|- +|.dbv ||Databoard Value File. Contains a single value in text format without type information. |} \ No newline at end of file