version 3.0.0
Please note that this documentation covers version 3.0.0
. There are new features in version 3.2.0
that are not yet covered in this document.
1. What is XMLLIB?
XMLLIB is a library for parsing xml-les in Fortran. This means that it provides subroutines for extracting values from an xml file.
XMLLIB provides three dierent interfaces for parsing data, here referred to as the Konz
, Xpath
and xml2eg interfaces. The Konz
interface is sometimes also referred to as the Classic
interface. The xml2eg
interface is the most flexible of the three, the most robust and also the most simple to use. The Konz
and Xpath
interfaces are kept only for legacy usage. The details of the interfaces are described in section 3.
Note that XMLLIB cannot be used to parse any xml file. The xml restrictions of the different interfaces are described in section 2.
The XMLLIB source code is stored in the ITER git repository. To clone this repository:
> git clone ssh://git@git.iter.org/lib/xmllib.git
In this repository there are examples for each of the XMLLIB interfaces.
. |-- examples | |-- classic - classic interface (legacy code) | |-- cpp - C++ based sample | |-- xml2eg - samples for codes based on xml2eg library | `-- xpath - samples for codes based on XPath |-- src `-- tests
2. XML formats used in XMLLIB
There are a number of restrictions on the xml files that XMLLIB can parse. In particular, XMLLIB cannot parse:
- Any type of attributes. As an example, XMLLIB cannot parse
<species mass="2" charge="1"/>
. This information can instead be represented using following XML structure:
<species> <mass> 2 </mass> <charge> 1 </charge> </species>
- XMLLIB cannot parse arrays of elements. Example:
<family> <person><name> Bob </name></person> <person><name> Nick </name></person> </family>
cannot be parsed. Instead the two persons may be described as an array of names:
<family><names> Bob , Nick </names></family>
2.1. Restrictions in the xml format of the xml2eg interface
Using the xml2eg
interface the root element has to be /parameters
, i.e. only data under /parameters
can be accessed using the xml2eg
interface.
2.2. Restrictions in the format of the xml-schema for Konz and Xpath interfaces
The Xpath and Konz interfaces have restrictions on how the xml-schema file should be written. The main restriction is that any child-xml-element has to be specified using a reference, ref
,to a different element on the root level.
Example: Below the element parameter
has an explicitly declared child node
, thus it cannot be parsed with the Konz or Xpath interfaces.
<xs:element name="parameters"> <xs:complexType> <xs:all> <xs:element name="node" type="xs:float"/> </xs:all> </xs:complexType> </xs:element>
By moving the declaration outside the parameter element it can be parsed.
<xs:element name="parameters"> <xs:complexType> <xs:all> <xs:element ref="node" minOccurs="1"/> </xs:all> </xs:complexType> </xs:element> <xs:element name="node" type="xs:float"/>
One consequence of this limitation is that one cannot use the same name for two fields in different branches of the xml-tree unless both fields have identical format. As an example, there is no way to parse anything similar to the xml-tree below without renaming one of the elements called node
.
<xs:element name="parameters"> <xs:complexType> <xs:all> <xs:element name="integer"> <xs:all> <xs:element name="node" type="xs:integer"/> </xs:all> </xs:element> <xs:element name="float"> <xs:all> <xs:element name="node" type="xs:float"/> </xs:all> </xs:complexType> </xs:all> </xs:complexType> </xs:element>