====== L3DT's XML formats ======

L3DT uses the [[wp>EXtensible_Markup_Language|eXtensible Markup Language]] to store settings in text files, such as the 
[[l3dt:formats:specs:proj|project file]] (.proj), 
[[l3dt:formats:specs:cli.xml|climate file]] (.cli.xml), and the
[[l3dt:formats:specs:ini.xml|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 [[l3dt:formats:specs:proj|project file]] written by L3DT:

<code xml>
<?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>
</code>

===== 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 [[wp>Document_Type_Definition|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 [[#supported element types|element types]].

===== Element declarations =====

Element declarations use the following prototype:

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

The restrictions on [[#supported element types|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 {{l3dt:formats:specs: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 {{l3dt:formats:specs:formats.ini.xml}} example. |
|  FileSelector  | Used in L3DT to store and select filenames. See {{l3dt:formats:specs:paths.ini.xml}} example. |
|  ComboSelector  | Used in L3DT to store and select options from a list. See {{l3dt:formats:specs:formats.ini.xml}} example (specifically, RAW format). |

==== Element names ====

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

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

=== 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:

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

Whereas this is valid:

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

==== 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:
<code xml>
<varlist name="empty list"></varlist>
</code>

This is //not// OK:

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

//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:

<code xml>
<!-- this is a comment -->
</code>