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"

asl::Xml::text

const String & text() const

Returns the text content of this element (the first child text element).

Definition: Xml.h:614

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

asl::Xml::write

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

Writes an XML document to a file.

asl::Xml::encode

static String encode(const Xml &e, bool formatted=true)

Encodes the given XML document as XML, with or without formatting.

#include <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. More...

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. More...

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. More...

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

Detailed Description

Public Member Functions

Static Public Member Functions

Member Function Documentation

◆ set() [1/2]

◆ set() [2/2]

◆ write()