Module amxml::dom

XML DOM processor

Building DOM tree from XML document string

Building DOM tree can be done by calling 'new_document' function. The DOM tree can be turned into String.

use amxml::dom::*;
let xml_string = r#"<?xml version="1.0"?><article>foo</article>"#;
let doc = new_document(&xml_string).unwrap();
let result = doc.to_string();
assert_eq!(result, xml_string);

Retrieving the DOM node

Navigating DOM tree, or retrieving the DOM node, can be done by 'root_element', 'parent', 'first_child', 'nth_child', 'attribute_value' methods.

See the description and example of corresponding method.

Retrieving the DOM node by XPath

But more convenient way for retrieving the DOM node is, perhaps, using XPath, especially when the search criteria is not trivial.

First XPath example is somewhat straightforward. 'each_node' method visits the DOM nodes that match with the given XPath, and apply the function (closure) to these nodes.

use amxml::dom::*;
let xml = r#"<root><a img="a1"/><a img="a2"/></root>"#;
let doc = new_document(xml).unwrap();
let mut img = String::new();
doc.each_node("/root/a", |n| {
    img += n.attribute_value("img").unwrap().as_str();
});
assert_eq!(img, "a1a2");

Second XPath example is more complex. This finds the clerk OR engineer (NOT advisor) who has no subordinates. Note that clerks and enginners appear in document order in 'each_node' iteration.

use amxml::dom::*;
let xml = r#"
<?xml version='1.0' encoding='UTF-8'?>
<root>
    <clerk name="Ann">
        <advisor name="Betty"/>
        <clerk name="Charlie"/>
    </clerk>
    <engineer name="Dick">
        <engineer name="Emily"/>
    </engineer>
    <clerk name="Fred"/>
</root>
"#;
let doc = new_document(xml).unwrap();
let root = doc.root_element();
let xpath = "(//clerk | //engineer)[count(./*) = 0]";
let mut names = String::new();
root.each_node(xpath, |n| {
    names += n.attribute_value("name").unwrap().as_str();
    names += "; ";
});
assert_eq!(names, "Charlie; Emily; Fred; ");
 

Also see the description and example of 'each_node', 'get_first_node', 'get_nodeset' methods.

Manipurating the DOM node

Inserting / replacing / deleting the DOM node can be done by methods like 'append_child', 'insert_as_previous_sibling', 'insert_as_next_sibling', 'delete_child', 'replace_with', 'set_attribute', 'delete_attribute' methods.

See the description and example of corresponding method.

Note

This processor does not translate namespace prefixes to their corresponding URIs. If needed, you can get the URI via 'namespace_uri' method.

This processor does not care Directives <!DOCTYPE ...>, <!ELEMENT ...>, etc.

This processor accepts some illegal XML documents, like those that have more than one root elements. Sometimes it is convenient to accept such document temporally in the course of manipurating.

Structs

NodePtr

A node in the XML document tree.

Enums

NodeType

Type of node in the XML document tree.

Functions

new_document

Parses the XML string and creates the DOM tree and returns the topmost DocumentRoot node.