|
0
|
1 This is the file format for mergetag text files.
|
|
|
2 Version: 0.1 unfinalised
|
|
|
3
|
|
|
4
|
|
|
5 The encoding should be unicode UTF-8, UTF-16 or UTF-32, and for anything other than UTF-8 must include a BOM.
|
|
|
6
|
|
|
7
|
|
|
8 Hierarchy:
|
|
|
9 + Sections (special section: see header)
|
|
|
10 ++ Data Tags
|
|
|
11
|
|
|
12
|
|
|
13 IDs:
|
|
|
14 IDs are used for several purposes; they are always stored as a uint number (0-4294967295). They may
|
|
|
15 be given in the file as a base-10 or hex number or, where a lookup table is provided to the reader,
|
|
|
16 as a double-quoted string (with no escape sequences).
|
|
|
17 Multiple section or data tags with the same ID are allowed; see the "Merging rules" section.
|
|
|
18
|
|
|
19
|
|
|
20 Outside of tags the only whitespace or valid tags is allowed. Whitespace is ignored.
|
|
|
21 The following tags are valid (see below for details):
|
|
|
22 tag purpose
|
|
|
23 {...} section identifiers
|
|
|
24 <...> data items
|
|
|
25 !{...} simple comment block
|
|
|
26 !<...> comment block parsed the same as <...>
|
|
|
27 Within tags, type specifications or data items whitespace is allowed between symbols.
|
|
|
28
|
|
|
29
|
|
|
30 Section identifier tags:
|
|
|
31 Format: {ID} or {ID|ID}
|
|
|
32 In the {ID|ID} case, the first ID is the section type, and the second ID the section name.
|
|
|
33 In the {ID} case, the section type ID has been ommitted and the default type is used (0).
|
|
|
34 A section identifier marks the beginning of a new section, extending until the next section
|
|
|
35 identifier or the end of the file. When a section is read, a new
|
|
|
36
|
|
|
37
|
|
|
38 Data item tags:
|
|
|
39 Format: <tp|ID=dt>
|
|
|
40 A data item with type tp, identifier ID and data dt. If the data does not fit the given type it is
|
|
|
41 an error and the tag is ignored. Once split into a type string, ID and data string, the contents
|
|
|
42 are passed to an addTag() function within the DataSection class which will parse tags of a
|
|
|
43 recognised format and either ignore or print a warning about other tags.
|
|
|
44
|
|
|
45
|
|
|
46 Data item tags: Type format:
|
|
|
47 Note:
|
|
|
48 The type is not initially parsed; it is read as a token terminated by any of these
|
|
|
49 characters: <>|=
|
|
|
50 Of course any character other than a | terminating the token is an error.
|
|
|
51 Format:
|
|
|
52 tp a basic type
|
|
|
53 tp[] a dynamic list of sub-type tp
|
|
|
54 Possible future additions:
|
|
|
55 tp() a dynamic merging list of sub-type tp (only valid as the primary type, ie
|
|
|
56 <subtype()|...>, not a sub-type of a tuple or another dynamic list)
|
|
|
57 {t1,t2,...,tn} a tuple with sub-types t1, t2, ..., tn
|
|
|
58
|
|
|
59 Basic types (only items with a + are currently supported):
|
|
|
60 abbrev./full name (each type has two names which can be used):
|
|
|
61
|
|
|
62 0 void --- less useful type
|
|
|
63 + 1 bool --- integer types
|
|
|
64 + s8 byte
|
|
|
65 + u8 ubyte
|
|
|
66 + s16 short
|
|
|
67 + u16 ushort
|
|
|
68 + s32 int
|
|
|
69 + u32 uint
|
|
|
70 + s64 long
|
|
|
71 + u64 ulong
|
|
|
72 s128 cent
|
|
|
73 u128 ucent
|
|
|
74
|
|
|
75 + binary --- alias for ubyte[]
|
|
|
76
|
|
|
77 + fp32 float --- floating point types
|
|
|
78 + fp64 double
|
|
|
79 + fp real
|
|
|
80 im32 ifloat
|
|
|
81 im64 idouble
|
|
|
82 im ireal
|
|
|
83 cpx32 cfloat
|
|
|
84 cpx64 cdouble
|
|
|
85 cpx creal
|
|
|
86
|
|
|
87 + UTF8 char --- character types (actually these CANNOT support UTF8 chars with length > 1)
|
|
|
88 UTF16 wchar
|
|
|
89 UTF32 dchar
|
|
|
90 + string --- alias for char[] --- (DOES support UTF8)
|
|
|
91 wstring --- alias for wchar[]
|
|
|
92 dstring --- alias for dchar[]
|
|
|
93
|
|
|
94
|
|
|
95 Data item tags: Data format:
|
|
|
96 Valid chars: [](){},+-.0-9eEixXa-fA-F '.' ".*"
|
|
|
97 Format:
|
|
|
98 [d1,d2,...,dn] data all of type t corresponding to t[]
|
|
|
99 (d1,d2,...,dn) data all of type t corresponding to t()
|
|
|
100 {d1,d2,...,dn} data corresponding to a type declaration of {t1,t2,...,tn}
|
|
|
101 d a single data element
|
|
|
102
|
|
|
103 Single data elements:
|
|
|
104 z an integer number (regexp: [+-]?[0-9]+)
|
|
|
105 z a floating point number (rough regexp: [+-]?[0-9]*[.]?[0-9]*(e[+-]?[0-9]+)?)
|
|
|
106 zi an imaginary floating point number (z is a floating point number)
|
|
|
107 y+zi, y-zi a complex number (4+0i may be written as 4, etc) (y, z are f.p.s)
|
|
|
108 0xz, -0xz a hexadecimal integer z (composed of chars 0-9,a-f,A-F)
|
|
|
109 'c' a char/wchar/dchar character, depending on the type specified (c may be any
|
|
|
110 single character except ' or an escape sequence)
|
|
|
111 "string" equivalent to ['s','t','r','i','n','g'] (for a string/wstring/dstring type)
|
|
|
112 may contain escape sequences
|
|
|
113 Escape sequences are a subset of those supported by D: \" \' \\ \a \b \f \n \r \t \v
|
|
|
114 XX...XX Binary (ubyte[]); each pair of chars is read as a hex ubyte
|
|
|
115 <void> void "data" has no symbols
|
|
|
116
|
|
|
117
|
|
|
118 Data format: Escape sequences:
|
|
|
119 To be created and written.
|
|
|
120
|
|
|
121
|
|
|
122 Comment tags (there are no line comments):
|
|
|
123 Simple comment blocks:
|
|
|
124 Format: !{...}
|
|
|
125 This is a simple comment block, and only curly braces ({,}) are treated specially. A {, whether or
|
|
|
126 not it is preceded by a !, starts an embedded comment block, and a } ends either an embedded block
|
|
|
127 or the actual comment block. Note: beware commenting out {...} tags with a string ID containing
|
|
|
128 curly braces which aren't in matching pairs.
|
|
|
129 Commented data tags:
|
|
|
130 Format: !<tp|ID=dt>
|
|
|
131 Basically a commented out data tag. Conformance to the above spec may not be checked as strictly as
|
|
|
132 normal, but the dt section is checked for strings so that a > within a string won't end the tag.
|
|
|
133
|
|
|
134
|
|
|
135 Merging rules:
|
|
|
136 if, when a data item is read, a data item with the same identifier
|
|
|
137 within the same section exists in the DataSet being read into:
|
|
|
138 + if the types are identical:
|
|
|
139 ++ if the primary type is a tp() mergeable dynamic list:
|
|
|
140 +++ the entries from the item being read are concatenated to those in the item
|
|
|
141 +++ in the DataSet
|
|
|
142 ++ else:
|
|
|
143 ++- the item already in the DataSet takes priority and is left untouched
|
|
|
144 + else:
|
|
|
145 +- a warning is issued, and the data item within the DataSet is left untouched
|
|
|
146 This allows merging some config settings in a user config file with the remaining settings in a
|
|
|
147 complete system config file and some support for modifications overriding or adding to some data.
|
|
|
148
|
|
|
149
|
|
|
150 Header:
|
|
|
151 The header is a standard section which is mandatory and must be the first section. Its section
|
|
|
152 identifier must start at the beginning of the file with no whitespace, declared with:
|
|
|
153 {MTXY} where XY is a two digit CAPITAL HEX version number representing the
|
|
|
154 mergetag format version, e.g. {MT01} .
|
|
|
155 If these are not the first 6 characters of the file the file will not be regarded as valid.
|
|
|
156 This formatting is very strict to allow reliable low-level parsing.
|
|
|
157
|
|
|
158
|
|
|
159 The data tags within the header have no special meaning; any may be used such as the following:
|
|
|
160 <string|"Author"="...">
|
|
|
161 <string|"Name"="...">
|
|
|
162 <string|"Description"="...">
|
|
|
163 <string|"Program"="..."> (which program created/uses this?)
|
|
|
164 <*|"Version"=...> (use any supported type)
|
|
|
165 <string|"Date"="YYYYMMDD"> (reverse date format; optionally "YYYYMMDDhhmmss")
|
|
|
166 <{u16,u8,u8}|"Date"={YYYY,MM,DD}> (actually this type probably won't be supported by
|
|
|
167 a standard section)
|
|
|
168 <string|"Copyright"=...>
|
|
|
169
|
|
|
170
|
|
|
171 Example:
|
|
|
172 {MT01}
|
|
|
173 {example section}
|
|
|
174 <u32|"num"=5>
|
|
|
175 <{u32,UTF8[]}()|"DATA"=(
|
|
|
176 {1,['a']},
|
|
|
177 {59,['w','o','r','d']},
|
|
|
178 {2,"strings can be written like this"} )>
|
|
|
179 <wchar[]|"name"="This string is stored in UTF16, regardless of the file's encoding.">
|
|
|
180 <{u32,UTF8[]}()|"DATA"=(
|
|
|
181 {3,"this is appended to the previous 'DATA' item"} )>
|
|
|
182 {"section: section identifiers and tuples are not confused since tuples only occur inside <...> items"}
|
|
|
183 <void|Empty tag= >
|
|
|
184 !{this is a comment {containing a comment}}
|
