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