Xml Class Reference

Detailed Description

This class represents an XML element and can be used to manipulate a document DOM tree.

The class allows accessing the element's tag, attributes and child elements.

Consider the following XML fragment.

<html>
    <head>
        <meta charset="utf8"/>
        <meta name="author" content="John Doe"/>
    </head>
    <body>
        <h1>Hello</h1>
        <p class="main">world</p>
    </body>
</html>

Parsing/reading

This can be parsed from a string or read from a file:

Xml html = Xml::decode(xml);           // from a string
 
Xml html = Xml::read("document.xml");  // from a file

The content can be accessed easily using operator () for tags and [] for attributes. For example, the charset attribute in the <meta> element can be read with:

String charset = html("head")("meta")["charset"];  // -> "utf8"

• element("tag") returns the first child of element that has the given tag
• element("tag", 3) would return the 4th child with that tag
• element["attr"] returns the value of the attribute attr.

The text content of the <h1> element would be retrieved like this:

String text = html("body")("h1").text();  // -> "Hello"

That text content of an element can be written with .pu():

html("body").put("h1", "Bye");      // now it's <h1>Bye</h1>

We can iterate the children of the <body> element like this:

Xml body = html("body");
 
for(auto& e : body.children())
{
    e.setAttr("tag", e.tag());     // add an attribute with the tag name
}

Or only the children with a given tag:

for(auto& meta : html("head").children("meta"))
{
    if(meta.has("charset"))
        setCharset(meta["charset"]);
    else
        addMeta(meta["name"], meta["content"]);
}

Elements of the tree can be searched using selectors in the form of lambda predicates. For example, this will return all the embedded PNG images (<img> elements with an src attribute ending in ".png").

auto elems = html.find([](const Xml& e) {
    return e.tag() == "img" && e["src"].endsWith(".png");
});

Creating/writing

The same example XML document DOM can be built in code:

Xml html = Xml("html")
    << (Xml("head")
        << Xml("meta", Map<>("charset", "utf8"))
        << Xml("meta", Map<>("name", "author")("content", "John Doe"))
    )
    << (Xml("body")
        << Xml("h1", "Hello")
        << Xml("p", Map<>("class", "main"), "world")
    );

Or in newer compilers (with initializer lists):

Xml html("html", {
    Xml("head", {
        Xml("meta", {{"charset", "utf8"}}),
        Xml("meta", {{"name", "author"}, {"content", "John Doe"}})
    }),
    Xml("body", {
        Xml("h1", "Hello"),
        Xml("p", {{"class", "main"}}, "world")
    })
});

And the original XML formatted document can be written like this:

String xml = Xml::encode(html);    // to a string
Xml::write(html, "document.xml");  // to a file

#include <asl/Xml.h>

Inherits NodeBase.

Inherited by XmlText.

Public Member Functions
	Xml (const String &tag)
	Constructs an element with the given tag.
	Xml (const String &tag, const Map<> &attrs)
	Constructs an element with the given tag and attributes.
	Xml (const String &tag, const String &val)
	Constructs an element with the given tag and value (text subelement).
	Xml (const String &tag, const Map<> &attrs, const String &val)
	Constructs an element with the given tag, attributes and value (text subelement).
Xml	clone (bool detach=true) const
	Returns a separate copy of this element with its children, and no parent.
void	setTag (const String &tag)
	Changes the tag name of this element.
Xml	parent () const
	Returns the parent element of this element (a null Xml object if it this is the root)
const String &	tag () const
	Returns the tag of this element.
Map &	attribs ()
	Returns the element's attributes.
Xml	operator() (const String &tag, int i=0) const
	Returns the i-th child element with the given tag.
template<class F >
void	traverse (const F &f)
	Traverses all sub elements and executes the given function.
template<class F >
Array< Xml >	find (const F &pred) const
	Searches recursively and returns all sub elements that satisfy a condition given as a predicate.
template<class F >
Xml	findOne (const F &pred) const
	Searches recursively and returns the first sub element that satisfies a condition given as a predicate.
int	count (const String &tag) const
	Returns the number of children with the given tag.
void	remove (int i)
	Removes the i-th child element.
void	remove (const Xml &e)
	Removes the element e if it is a child of this element.
void	insert (int i, const Xml &e)
	Inserts an element at position i as a child.
const String &	operator[] (const String &a) const
	Returns the value of an attribute.
void	setAttr (const String &attr, const String &val)
	Sets the value of an attribute.
bool	has (const String &attr) const
	Returns true if the given attribute exists.
void	removeAttr (const String &attr)
	Removes the given attribute.
Xml &	put (const String &value)
	Sets the content of this element to the given text value.
Xml &	set (const String &value)
	Sets the content of this element to the given text value.
Xml &	put (const String &name, const String &val)
	Sets the content of a named subelement creating it if it does not exist.
Xml &	set (const String &name, const String &val)
	Sets the content of a named subelement creating it if it does not exist.
void	clear ()
	Removes all children.
Xml &	operator<< (const Xml &e)
	Appends an element as a child.
Xml &	operator<< (const String &text)
	Appends a text element as a child, or appends to the text if the last child is already a text element.
const Array< Xml > &	children () const
	Returns this element's children elements.
ChildrenEnumerator	children (const String &tag)
	Returns an enumerator of the children elements with the given tag.
int	numChildren () const
	Returns the number of child elements.
Xml &	child (int i)
	Returns the i-th child element.
bool	isText () const
	Returns true if this is a text element.
const String &	text () const
	Returns the text content of this element (the first child text element).
template<class T >
T	value (T deflt=T()) const
	Returns the trimmed content of this element converted to a given type; As in elem.value<int>()

Static Public Member Functions
static Xml	read (const String &file)
	Reads and decodes a file as XML and returns its root element.
static bool	write (const Xml &e, const String &file)
	Writes an XML document to a file.
static bool	write (const String &file, const Xml &e)
	Writes an XML document to a file.
static Xml	decode (const String &xml)
	Parses the given string as XML and returns the equivalent DOM tree.
static String	encode (const Xml &e, bool formatted=true)
	Encodes the given XML document as XML, with or without formatting.

Member Function Documentation

set() [1/2]

Xml & set	(	const String &	name,
		const String &	val
	)

Sets the content of a named subelement creating it if it does not exist.

Deprecated:

Use put(), set() will probably set an attribute in the future

set() [2/2]

Xml & set

(

const String &

value

)

Sets the content of this element to the given text value.

Deprecated:

Use put()

write()

static bool write ( const String &  file, const Xml &  e  )

static

Writes an XML document to a file.

Deprecated:

Use Xml::write(xml, file)

---

The documentation for this class was generated from the following file:

• Xml.h