The xml::document class encapsulates the notion of an XML document.

When parsing XML documents with the xml::tree_parser, you will be working with xml::document objects so that you can access the resulting node tree.

Using the xml::document class is not limited to working with the xml::tree_parser class. You can also use it when you want to generate an XML document. In this case, you will build the node tree by hand, and then use one of the xml::document member functions to convert or save the node tree as XML data.

Document Settings

Although the xml::document class is mainly a container for the node tree, it does contain some settings that apply to the entire XML document. The xml::document class provides member functions for getting and setting of these values. The following list illustrates which document settings are available:

The version from the <?xml?> processing instruction: xml::document::get_version(), xml::document::set_version().
The document encoding from the <?xml?> processing instruction: xml::document::get_encoding(), xml::document::set_encoding().
Whether or not the document is marked standalone in the <?xml?> processing instruction: xml::document::get_is_standalone(), xml::document::set_is_standalone().

You should consult the xmlwrapp API reference for more information about these member functions.

Internal and External Subsets

The XML document may contain either an internal or external subset, both or no subsets at all. The xml::document provides member functions to test for the existence of subsets. The are the xml::document::has_internal_subset() and xml::document::has_external_subset() functions.

An internal subset is present when document type definitions are placed inside the XML document itself. This can be useful if you did not want to use an external DTD or if you wanted to override something from the external DTD.

If the XML document references an external DTD file or URL, it is said to have an external subset. This is the most common type of subset.

Validating the Document

Validating with DOCTYPE

If the XML document contains either an internal or external subset, you can use the xml::document::validate() member function to validate the XML document against the subsets. This function will return true if the document is valid.

When the document is not valid, or it does not contain an internal or external subset, the xml::document::validate() function will return false.

Validating with Any DTD

If the XML document does not contain an internal or external subset, or when you want to validate the document against a specific external subset, you can use an overloaded version of the xml::document::validate() member function. The overloaded version takes the name of a file or a URL to an external subset to validate the document against.

Like the other xml::document::validate() function, this one will return true if the document is valid according to the given external subset. In this case, the external subset will be attached to the document for further use. For example, to provide default attribute values.

If the external entity cannot be parsed, or the document is not valid, the xml::document::validate() will return false.

Processing XInclusions

If you would like xmlwrapp to search the node tree and process any XInclusions (<xi:include> elements), you can use the xml::document::process_xinclude() member function. It will return an int telling you how many substitutions were preformed.

Accessing Document Children

Although an XML document may only contain one element type node (the root node), it may contain more than one child. For example, there may be XML comments above the root node's opening tag, or below the root node's closing tag. In this case, those comments would be children of the xml::document object.

You can access these children using xml::node::iterator objects. The xml::document class provides xml::document::begin() and xml::document::end() member functions for getting iterators to the children. For more information about node iterators, see Accessing a Node's Children.

Accessing the Root Node

The most frequently used child node of the XML document is the root node. As mentioned above, the root node is the only child node of the document that is an element.

In order to save you time and effort finding the root node, the xml::document class provides the xml::document::get_root_node() member function. This function will return a reference to the root node for the document.

Setting the Root Node

If you wanted to set the root node of the document to some other element node, you can use the xml::document::set_root_node() member function. This will create a copy of the given node and use it and the root node for the document. If the document already had a root node, it will be removed and deleted.

Converting and Saving the Document as XML

The xml::document provides a few different member functions for converting the node tree into XML. The following list will summarize these functions:

xml::document::save_to_string() converts the node tree to XML and places the results in a given std::string object.
xml::document::save_to_file() converts the node tree to XML and saves the results into the given file.
xml::document::operator<<() convert the node tree to XML and inserts the results into the given std::ostream object.