-
Notifications
You must be signed in to change notification settings - Fork 0
Configuration XML
Alongside normal command-line options, it is possible to pass options via XML in an equivalent way. The options are loaded from the file sfi-config.xml
or via the --options
parameter.
Any sequence of command-line options can be converted to this format by using the options
mode, with the exception of the input/output files and the mode itself, which cannot be expressed using this format.
The root of the document is the <options>
element, located in the https://sfi.is4.site/config
namespace:
<options xmlns="https://sfi.is4.site/config" /> <!-- also the output of `sfi options -` -->
Any elements that are children of the root element have the same effect as specifying the corresponding command-line options:
<options xmlns="https://sfi.is4.site/config">
<root>urn:uuid:</root> <!-- same as --root "urn:uuid:" -->
</options>
Options with a particular value may also be specified as an attribute:
<options
root="urn:uuid:"
xmlns="https://sfi.is4.site/config">
<!-- also same as --root "urn:uuid:" -->
</options>
However options which may be repeated (such as --include
or --exclude
) should not be written as attributes because it may change their order and result in different interpretation.
Options without a value must be specified as an empty element, and never as an attribute:
<options xmlns="https://sfi.is4.site/config">
<buffered /> <!-- same as --buffered -->
</options>
The value of an option is passed without any transformation to the corresponding option handler, additional "
characters or escaping are not needed. If the option's value consists entirely of spaces, either an attribute has to be used instead of an element, or the xml:space="preserve"
attribute has to be added to the element.
Individual components' properties, such as analyzer:stream-factory:triple-size-estimate
, contain the :
character which cannot be stored as an XML local name directly. Instead, it is possible to nest the option in multiple elements:
<options xmlns="https://sfi.is4.site/config">
<analyzer>
<stream-factory>
<triple-size-estimate>32</triple-size-estimate> <!-- same as --analyzer:stream-factory:triple-size-estimate 32 -->
</stream-factory>
</analyzer>
</options>
This way, multiple options for the same component can be grouped without repeating the component's name. It is also possible to store them as attributes instead of elements, like above.
When an XML name is encountered (the name of an element or attribute), it is first decoded using XmlConvert.DecodeName
, to allow the presence of arbitrary characters, encoded as _x####_
. This means that even the :
character can be encoded, as _x003A_
, and so the snippet above can be equivalently written as:
<options
analyzer_x003A_stream-factory_x003A_triple-size-estimate="32"
xmlns="https://sfi.is4.site/config" />
Doing this however decreases readability and is not needed when it can be written using the nested syntax. It is however necessary if the component name contains wildcards (?
and *
) or if the element would start on xml
(reserved, case-insensitive).