ClanLib provides a number of classes that can read data from text files. This data can be anything from settings for a game, such as which resolution to use, whether an application is full screen, etc., to game data, such as a list of guns available in the game and their related properties. Regardless of the data stored, it's possible to organize and structure our data into files so each can be read and interpreted by our application. ClanLib expects such data files to be structured according to the XML format, for which it provides several classes to read from and write data to XML.
XML is an acronym for Extensible Markup Language, and it's an approachable, general-purpose file structure. To create a simple XML file you open a text editor (e.g., Notepad or something similar), enter the required content into the file, and save it with an .xml extension.
The following XML file contains information about students at a school, including name, age, and class. This example record contains information about two students named Bob and James. However, XML can store any kind of data; this is just a simple example.
<STUDENTS> <STUDENT> <NAME>Bob</NAME> <AGE>15</AGE> <CLASS>5D</CLASS> </STUDENT> <STUDENT> <NAME>James</NAME> <AGE>15</AGE> <CLASS>7E</CLASS> </STUDENTS> </STUDENTS>
Like many things in the world of computing, XML works on the idea of a tree structure, also known as a hierarchical structure. Each item in an XML file (e.g., STUDENT, NAME, AGE, CLASS) is called a node. Every node has an opening and closing tag to mark the beginning and ending of the node, respectively, and anything contained in between is said to be contained inside the node. For example, the node STUDENT occurs twice in the sample file-once for each student. Each STUDENT node has an opening tag (<STUDENT>) and a closing tag (</STUDENT>). Notice that the closing tag is similar to the opening one, except its name is prefixed by a / character. Each STUDENT node contains details about a particular student. Thus, each STUDENT node is said to contain the nodes inside it: NAME, AGE, and CLASS.
So, the first STUDENT contains:
<NAME>Bob</NAME> <AGE>15</AGE> <CLASS>5D</CLASS>
And the second STUDENT contains:
<NAME>James</NAME> <AGE>15</AGE> <CLASS>7E</CLASS>
Nodes that contain other nodes are said to be parent nodes and the contained nodes are said to be the child nodes of the parent. STUDENTS is a parent node of each STUDENT node, and each STUDENT node is consequently a child of STUDENTS. In turn, each NAME, AGE, and CLASS node is a child of STUDENT, and therefore STUDENT is in turn their parent.
In XML, a node is called an element if it has attributes. Attributes are extra information given to a node. The following sample is the same XML file as above, but written using elements instead of nodes.
<STUDENTS> <STUDENT name="Bob" Age="15" /> <STUDENT name="James" Age="15" /> </STUDENTS>
More information about XML can be found at http://www.w3schools.com/xml/.
ClanLib offers a number of classes to create and process an XML structure and to then save it to a file. The stages involved in this process follow.
Whether loading or saving XML data to a file or constructing an XML hierarchy in memory to be processed, it'll be useful to create a CL_DomDocument object. CL_DomDocument is a manager class for creating and maintaining XML structures being saved or loaded from files. The following code creates this object:
All XML documents requires a single root node/element that is the ultimate parent of all other nodes and elements. The root element, and all elements, is created using the create_element method of CL_DomDocument, and this method returns a newly created CL_DomElement object. This element is not automatically attached to any hierarchy. It is not considered as being part of the document until it is attached. This will occur later. For now, it is an independent element hovering about in memory. Consider the following code:
CL_DomElement Element = Document.create_element("root");
All other elements of any level of the XML hierarchy can be created in the same way you create a root element. To set the attributes of an element, the set_attribute method can be called. This method accepts two std::string arguments: one for the name of the attribute to be created and one for the value of the attribute.
The elements in an XML document, as we saw, have a relationship to one another in terms of being parents or children of the others. To build this relationship, nodes must be attached to other nodes as children, and ultimately, the root node must be attached to the document as a child. A node can be attached to another as a child using the append_child method of any node. Consider the following:
Element1.append_child(Element2); //... And so on Document.append_child(Element1);
To save an XML hierarchy, the save method of CL_DomDocument is called:
Document.save(new CL_OutputSource_File("sample.xml"), true, true);
Loading data from XML documents uses the same classes as saving and is, more or less, the reverse of that process.
Loading is the process of reading data from an XML file and loading the contents into a structure in memory using the XML classes already described. This is achieved using the load method of CL_DomDocument.
Document.load(new CL_InputSource_File("Sample.xml"), true, true);
The root node or element of a document is the highest parent, and is also known as the ultimate ancestor.
CL_DomElement Element = Document.get_document_element();