X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.databoard%2Fsrc-isv%2Fspec%2FText%20Format.mediawiki;fp=bundles%2Forg.simantics.databoard%2Fsrc-isv%2Fspec%2FText%20Format.mediawiki;h=eb57f0e5a503ea3ee3ffde986757205646ff12f1;hb=969bd23cab98a79ca9101af33334000879fb60c5;hp=0000000000000000000000000000000000000000;hpb=866dba5cd5a3929bbeae85991796acb212338a08;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 new file mode 100644 index 000000000..eb57f0e5a --- /dev/null +++ b/bundles/org.simantics.databoard/src-isv/spec/Text Format.mediawiki @@ -0,0 +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. +|} \ No newline at end of file