Skip to content

Latest commit

 

History

History
67 lines (62 loc) · 2.27 KB

multiple_files.adoc

File metadata and controls

67 lines (62 loc) · 2.27 KB

Multiple Files

For big protocols it is possible and even recommended to split schema definition into multiple files. The code generator must accept a list of schema files to process and must process them in the requested order. Note there are no include (or similar) statements in the CommsDSL specification. The code generator is expected to process the listed DSL files in the provided order and being able to reuse any definition that has already been encountered.

Every subsequently processed schema file must NOT change any properties of the <schema> node with the same name that was defined in the earlier processed schema file. However, it is allowed to omit any properties that have already been defined. For example:

First processed file:

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big" version="2">
    ...
</schema>

Second processed file:

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    ...
</schema>

It must be accepted by the code generator because it does NOT change previously defined endian, and version for the schema named MyProtocol. The second file doesn’t mention version at all.

However, the following third file must cause an error due to changing the endian value:

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="little">
    ...
</schema>

Also note, that all the properties have some default value and cannot be defined in the subsequently processed file while been omitted in the first one.

For example, the first file doesn’t specify version number (which defaults to 0)

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    ...
</schema>

The following second file must cause an error due to an attempt to override version property with different value.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" version="2">
    ...
</schema>

RECOMMENDATION: When the schema is split into multiple files, define all the relevant properties in the first file, then don’t set any other <schema> properties except the name in all the others.