README.md
1# XML Generator
2
3This set of tools is used to transform files written in the pseudo language
4(referred to as "Extended Domain Description") into XML parameter-framework
5Settings files. The extension of such files are usually `.edd` or `.pfw`.
6
7## EDD Syntax
8
9### Introduction
10
11The Extended Domain Description (EDD) has been designed to help describing
12multiple and complex PFW settings. It is a recursive structured language with
13tabulation indentation (inspired from python).
14
15It has several advantages :
16
17- Easy to write
18- Easy to read
19- Nearly twice as compact as it's equivalent in XML
20- Less merge conflicts and easy solving
21- Can be split in multiple files
22- Intuitive syntax and comprehension when you know the PFW concepts
23
24But has a couple of drawbacks:
25
26- it is not supported natively by the PFW. It needs to be compiled into XML.
27- it supports only tabulation indentation
28
29### Concepts
30
31The EDD adds a couple of concepts over the PFW ones in order to extend the
32concepts used in the Settings files.
33
34#### DomainGroup
35A domain group can contain other domain groups and domains. Those inner domains
36will be prefixed with the name of the domain group.
37
38*The tag for domain groups is `domainGroup`.*
39
40*Example*
41
42```
43domainGroup: Codec
44
45 domain: Flow
46 conf: Unmute
47 /Audio/codec/playback/master_mute = 0
48 conf: Mute
49 /Audio/codec/playback/master_mute = 1
50
51 domainGroup: Configure
52 RoutageState Includes Configure
53
54 domain: IHF
55 [...]
56```
57
58will create the domains :
59
60- Codec.Flow (containing the Unmute and Mute configurations)
61- Codec.Configure.IHF (The `RoutageState Includes Configure` rule will apply to
62 all configurations inside the `Codec.Configure.*` domains)
63
64#### ConfigurationGroup
65A configuration group can contain other configuration groups and
66configurations. Those inner configurations will be prefixed with the name of
67the configuration group.
68
69*The tag for configuration groups is `confGroup`.*
70
71*Example*
72
73```
74domain: ExternalDSP
75
76 conf: TTY
77 [...]
78
79 confGroup: CsvCall
80 Mode Is InCsvCall
81
82 confGroup: Output
83 conf: IHF
84 [...]
85 conf: Earpiece
86 [...]
87```
88
89will create the following configurations in the `ExternalDSP` domain:
90
91- TTY
92- CsvCall.Output.IHF
93- CsvCall.Outout.Earpiece
94
95As with domainGroup, the `Mode Is InCsvCall` rule applies to all
96`CsvCall.Output.*` configurations in the `ExternalDSP` domain.
97
98#### ConfigurationType
99A configuration type is the specialization concept. When defining a
100configuration type, any configuration in the containing domain (or domain
101group) with the same name will inherit the configuration type rule.
102
103*The tag for configuration types is `confType`.*
104
105*Example*
106
107```
108domain: ExternalDSP
109 confType: Bind
110 Mode Is InCsvCall
111
112 confGroup: Modem
113
114 conf: Bind
115 BandRinging is Modem
116 [...]
117 conf: Unbind
118 [...]
119```
120
121will create the following configurations in the `ExternalDSP` domain:
122
123- Modem.Bind (applicable if `Mode Is InCsvCall` and `BandRinging is Modem`)
124- Modem.Unbind (no rule, i.e. applicable by default)
125
126#### Component
127A component can be used to factorize parameter names in configurations.
128
129*The tag for components is `component`.*
130
131```
132domain: Foo
133 conf: Bar
134 component: /System/some_element
135 parameter1 = "egg"
136 parameter2 = "spam"
137 /System/another_element/parameter3 = 42
138```
139
140will create a domain Foo containing a configuration Bar (no rule, i.e.
141applicable by default) that will set these 3 parameters:
142
143- `/System/some_element/parameter1` to "egg"
144- `/System/some_element/parameter2` to "spam"
145- `/System/another_element/parameter3` to 42
146
147## Preprocessor
148
149The xmlGenerator uses m4 to preprocess the files before parsing them. You may
150use any macro implemented by m4, such as `define` and `include`. This is
151deprecated and we do not recommend using it.
152
153## Style
154
155Here are a few recommendations to follow when writing Settings using EDD:
156
157### Rules
158
159- if you need to modify a rule, do not hesitate to rework it globally.
160- keep rule depth under 3-4.
161- factorize the rules, taking 3 minute to write a Karnaugh map is worth it.
162- comment, comment, comment !
163
164### Enum Parameters
165
166When setting an enum parameter value, use its lexical space, not its numerical
167space. E.g. don't write
168
169 /Subsystem/frequency = 5
170
171Write instead:
172
173 /Subsystem/frequency = f48kHz
174
175### String Parameters
176
177In an EDD file, string parameters may not contain newlines. Apart from that,
178all characters are supported. Also, leading spaces are ignored. Do *not*
179surround a string parameter's value with quotes. Don't write:
180
181 /Subsystem/string_parameter = "some string value"
182
183Write instead:
184
185 /Subsystem/string_parameter = some string value
186
187## XML Generation
188
189Once a `.edd` file is ready to be tested, it is possible to generate the
190corresponding XML file.
191
192### domainGenerator.py
193
194This python tool is self-documented: you may run `domainGenerator.py -h` to get
195its full usage.
196
197It prints the resulting XML on the standard output. Its syntax is:
198
199 domainGenerator.py [-h] --toplevel-config TOPLEVEL_CONFIG_FILE
200 --criteria CRITERIA_FILE
201 [--initial-settings XML_SETTINGS_FILE]
202 [--add-domains XML_DOMAIN_FILE [XML_DOMAIN_FILE ...]]
203 [--add-edds EDD_FILE [EDD_FILE ...]]
204 [--schemas-dir SCHEMAS_DIR]
205 [--validate] [--verbose]
206
207*Explanation:*
208
209- The "top-level configuration file" is the same as the one provided by the
210 parameter-framework client to instantiate it. The plugins referenced in that
211 file are not used.
212- The "criteria file" lists all criteria and possible values used in the EDD
213 files.
214- The initial settings file is an XML file containing a single
215 `<ConfigurableDomains>` (plural) tag; it may not overlap with the other
216 sources below. It will be imported into the settings.
217- Domain files are XML files, each containing a single `<ConfigurableDomain>`
218 (singular) tag. They all will be imported in the order of the command line
219 into the settings.
220- EDD files are all the files in EDD syntax you want to add to your Settings.
221- The optional `--schemas-dir` argument lets you change the directory
222 containing the XML Schemas in the context of the XML generation only (see the
223 `--validate` option).
224- The optional `--validate` option check the validity of all XML files involved
225 in the process.
226
227*Regarding XML Domain files and EDD files:*
228
229In theory, the order doesn't matter but since files are parsed in the order of
230the command line, you'll get different (although equivalent) files if you
231change the order, which makes it more difficult to compare versions.
232
233
234*The "criteria file" must look something like this:*
235
236```
237ExclusiveCriterion Criterion1Name : Criterion1Value1 Criterion1Value2
238InclusiveCriterion Criterion2Name : Criterion2Value1 Criterion2Value2
239```
240
241I.e. One criterion by line, starting by its kind, then its name, followed by a
242semicolon and then all possible values separated by spaces.
243
244#### How it works
245TODO
246