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.

Structure

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.

Component options

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.

Invalid characters in names

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).