Configuration 4 GNU (CFG)

The following XML excerpt is a setting that could be found in an INI file. It shows use of the property element and all three elements that a property can contain.

<property name="path">
  <whitespace>        </whitespace>
  <value>/home/jason</value>
  <comment type="append">My home directory</comment>
</property>

The property element identifies a Config4GNU property. The name of the property is identified using the name attribute. In the example above, the name of the property is "path."

The value element identifies the property's value. Since it can be anything, it is implemented as a simple text element rather than an attribute. If the value can contain linefeeds, the parser may implement the contents of the value element as an XML CDATA section.

The comment element identifies a user added comment on the property. The comment is there in case the Config4GNU front-end chooses to display the information to the user, but it mostly exists so that when the configuration file is rewritten, the comment will be preserved.

Parsers may specify attributes on the comment element to give itself additional information on how the comment should be rewritten to the file. In the example above, the comment element has an attribute "type" set to "append." This information tells the configuration file writer that the comment should be written on the same line as the property, "appended" onto the end of the line.

Multiple comments may appear in a property element. The comment element is not required to appear. If no comment element is specified, the file writer is to assume no comment was present in the file.

The whitespace element identifies any ignorable whitespace that existed in the file before this element. The whitespace information is not used by the front-end at all; it exists only so that the rewritten configuration will not contain artificial changes. If special characters occur in the whitespace, it may be necessary to create a CDATA section to contain the contents of the whitespace.

In the example above, the whitespace element tells the file writer to include eight spaces prior to the property statement in the configuration file.

Like the comment element, attributes can be used to provide additional information. Also like the comment element, more than one whitespace element can exist for a property.

If no whitespace element is present, or a whitespace element with a particular attribute is not present, the configuration file writer is to assume a "default" value for the whitespace. For example, if no whitespace element is present, the writer may choose to indent the property by eight spaces because all other properties in the section were indented by this amount.