L3DT documentation
Large 3D terrain generator

L3DT's XML formats

L3DT uses the eXtensible Markup Language to store settings in text files, such as the project file (.proj), climate file (.cli.xml), and the application settings file (.ini.xml).

Because I like writing code, I've made my own XML writer and parser. However, since I'm not a total masochist, I have not implemented the entire XML standard in L3DT's parser. Therefore, if you intent to write XML files for L3DT to read (for example, writing your own climate editor), you must conform to several requirements regarding the XML declaration, document type definition, element declarations, and case sensitivity. An example file is provided below.

Example file

Below is an example XML project file written by L3DT:

<?xml version="1.0" encoding="utf-8"?>
<varlist name="ProjectData">
  <varlist name="MapInfo">
    <varlist name="Terrain">
      <int name="nx">1024</int>
      <int name="ny">1024</int>
      <float name="HorizScale">10.000000</float>
    </varlist>
    <varlist name="Texture">
      <int name="nx">4096</int>
      <int name="ny">4096</int>
    </varlist>
    <bool name="WrapFlag">false</bool>
  </varlist>
  <varlist name="Files">
    <varlist name="Maps">
      <string name="DM">temp1_DM.dmf</string>
      <string name="HF">temp1_HF.hff</string>
      <string name="WM">temp1_WM.wmf</string>
      <string name="WS">temp1_WS.hff</string>
      <string name="AM">temp1_AM.amf</string>
      <string name="TN">temp1_TN.jpg</string>
      <string name="LM">LM\temp1_LM.mmf</string>
      <string name="TX">temp1_TX.jpg</string>
    </varlist>
    <varlist name="Climates">
      <string name="Temperate">C:\L3DT\L3DT data path\Resources\Climates\Temperate24.cli.xml</string>
      <string name="Temperate (deluxe)">C:\L3DT\L3DT data path\Resources\Climates\Temperate (deluxe).cli.xml</string>
    </varlist>
  </varlist>
</varlist>

XML declaration

L3DT does read the XML declaration, and actually cares about its content. Specifically:

  • There must be a version attribute, which must have the value “1.0”.
  • There must be an encoding attribute, which must have the value “utf-8” (not case-sensitive).

Additonal attributes may be specified, but will be ignored by L3DT.

Document type definition

The XML parser in L3DT does not support document type definitions, and any such declaration will cause an error when reading the file. DTD's are not required by L3DT because the parser implements a very strict sub-set of XML with specific requirements on element types.

Element declarations

Element declarations use the following prototype:

<TYPE name = "NAME">DATA</TYPE>

The restrictions on element types and element names are listed below.

Supported element types

L3DT's XML format supports a limited number of element types, which are divided into the categories of data elements (which don't contain 'child' elements) and tree elements (which may contain 'child' elements).

Data elements

tag type Example Comments
void <void name = “example”/> Voids contain no data, and are used as flags.
byte <byte>255</byte> 8-bit unsigned integer, values between 0 and 255.
short <short>32767</short> 16-bit integer, values between -32768 and 32767.
int <int>1</int> 32-bit integer, values between -2147483648 and 2147483647.
int64 <int64>1</int64> 64-bit integer.
float <float>0.01</float> Decimal and scientific notations are supported.
double <double>3E-120</double> Same as float, but with greater precision.
string <string>hello</string> Quotation marks are not required.
DirSelector <DirSelector>C:\temp\temp.tmp</DirSelector> Used in L3DT to store and select directory names. See paths.ini.xml example.

Tree elements

tag type Comments
varlist Contains any number of other elements.
buffer Used in L3DT to store binary data (as hexidecimal text).
FileConfig Used in L3DT to store file format settings. See formats.ini.xml example.
FileSelector Used in L3DT to store and select filenames. See paths.ini.xml example.
ComboSelector Used in L3DT to store and select options from a list. See formats.ini.xml example (specifically, RAW format).

Element names

Names of elements are specified using a 'name' attribute. For example:

<string name="this is the name">this is the data</string>

Forbidden characters

Names should be restricted to alphanumeric characters only (a-z, 0-9), although most symbols are supported. However, the following characters are explicitly forbidden in names:

  • . – full-stop.
  • ” – quotation mark.

Names must be unique within each level

Element names must be unique within each level of the document tree. For example, the following file is invalid:

<varlist name = "list1">
  <void name = "example">
  <void name = "example">
</varlist>

Whereas this is valid:

<varlist name = "list1">
  <void name = "example"/>
</varlist>
<varlist name = "list2">
  <void name = "example"/> <!-- no longer in the same level as the other 'example' -->
</varlist>

Empty elements

If an element contains no data, such as an empty string, L3DT's XML parser still requires both a start and an end tag for the element, and will not recognise a start tag that ends with a '/' (which normally signifies an empty element in HTML/XML).

This is OK:

<varlist name="empty list"></varlist>

This is not OK:

<varlist name="empty list"/>

Whoops: there is one exception: elements of type 'void' can be terminated by a '/', because they inherently contain no data.

Case sensitivity

Yup, that's right. L3DT's XML format is case senstive, which means that element tags must be in the same case as noted above. A 'varlist' is not the same as a 'VARLIST'.

Comments

Standard XML comments are supported, using the syntax shown below:

<!-- this is a comment -->
 
l3dt/formats/specs/xml.txt · Last modified: 2017/08/31 07:31 (external edit)
 
Except where otherwise noted, content on this wiki is licensed under the following license:CC Attribution-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki