Proxy class to conveniently convert XML structure to user data. More...

#include <bind.h>

Public Member Functions
	XmlIn (const XmlDoc &doc)
	Construct an input proxy for an XML document. More...

	XmlIn (const XmlElement *element)
	Construct an input proxy for a single XML element, may be nullptr. More...

	XmlIn (const XmlElement &element)
	Construct an input proxy for a single XML element. More...

template<class String >
XmlIn	operator[] (const String &name) const
	Retrieve a handle to an XML child element for reading. More...

void	next ()
	Refer to next sibling element with the same name. More...

template<class T >
bool	operator() (T &value) const
	Read user data from the underlying XML element. More...

template<class String , class T >
bool	attribute (const String &name, T &value) const
	Read user data from an XML attribute. More...

const XmlElement *	get () const
	Return a pointer to the underlying Xml element, may be nullptr.

	operator bool () const
	Test whether the underlying XML element exists. More...

bool	errorsOccured () const
	Notifies errors while mapping the XML to user data. More...

template<class String >
std::vector< String >	getErrorsAs () const
	Get a list of XML element and attribute names which failed to convert to user data. More...

Detailed Description

Proxy class to conveniently convert XML structure to user data.

Constructor & Destructor Documentation

zen::XmlIn::XmlIn ( const XmlDoc & doc )

Construct an input proxy for an XML document.

zen::XmlDoc doc;
  ... //load document
zen::XmlIn in(doc);
in["elem1"](value1); //
in["elem2"](value2); //read data from XML elements into variables "value1", "value2", "value3"
in["elem3"](value3); //

zen::XmlIn::XmlIn ( const XmlElement * element )

Construct an input proxy for a single XML element, may be nullptr.

See also: XmlIn(const XmlDoc& doc)

zen::XmlIn::XmlIn ( const XmlElement & element )

Construct an input proxy for a single XML element.

See also: XmlIn(const XmlDoc& doc)

Member Function Documentation

template<class String , class T >

bool zen::XmlIn::attribute	(	const String &	name,
		T &	value
	)		const

Read user data from an XML attribute.

This conversion requires a specialization of zen::readText() for type T.

zen::XmlDoc doc;
  ... //load document
zen::XmlIn in(doc);
in["elem"].attribute("attr1", value1); //
in["elem"].attribute("attr2", value2); //read data from XML attributes into variables "value1", "value2", "value3"
in["elem"].attribute("attr3", value3); //

Template Parameters

String	Arbitrary string-like type: e.g. std::string, wchar_t*, char[], wchar_t, wxString, MyStringClass, ...
T	String-convertible user data type: e.g. any string-like type, all built-in arithmetic numbers

Returns: "true" if the attribute was found and the conversion to the output value was successful.

See also: XmlElement::getAttribute()

bool zen::XmlIn::errorsOccured ( ) const

Notifies errors while mapping the XML to user data.

Error logging is shared by each hiearchy of XmlIn proxy instances that are created from each other. Consequently it doesn't matter which instance you query for errors:

XmlIn in(doc);
XmlIn inItem = in["item1"];
int value = 0;
inItem(value); //let's assume this conversion failed
assert(in.errorsOccured() == inItem.errorsOccured());
assert(in.getErrorsAs<std::string>() == inItem.getErrorsAs<std::string>());

Note that error logging is NOT global, but owned by all instances of a hierarchy of XmlIn proxies. Therefore it's safe to use unrelated XmlIn proxies in multiple threads.

However be aware that the chain of connected proxy instances will be broken once you call XmlIn::get() to retrieve the underlying pointer. Errors that occur when working with this pointer are not logged by the original set of related instances.

template<class String >

std::vector<String> zen::XmlIn::getErrorsAs ( ) const

Get a list of XML element and attribute names which failed to convert to user data.

Template Parameters

String Arbitrary string class: e.g. std::string, std::wstring, wxString, MyStringClass, ...

Returns: A list of XML element and attribute names, empty list if no errors occured.

void zen::XmlIn::next ( )

Refer to next sibling element with the same name.

Example: Loop over all XML child elements named "Item"

<?xml version="1.0" encoding="UTF-8"?>
<Root>
    <Item>1</Item>
    <Item>3</Item>
    <Item>5</Item>
</Root>

zen::XmlIn in(doc);
...
for (zen::XmlIn child = in["Item"]; child; child.next())
{
    ...
}

zen::XmlIn::operator bool ( ) const

explicit

Test whether the underlying XML element exists.

XmlIn in(doc);
XmlIn child = in["elem1"];
if (child)
  ...

Use member pointer as implicit conversion to bool (C++ Templates - Vandevoorde/Josuttis; chapter 20)

template<class T >

bool zen::XmlIn::operator() ( T & value ) const

Read user data from the underlying XML element.

This conversion requires a specialization of zen::readText() or zen::readStruc() for type T.

Template Parameters

T	User type that receives the data

Returns: "true" if data was read successfully

template<class String >

XmlIn zen::XmlIn::operator[] ( const String & name ) const

Retrieve a handle to an XML child element for reading.

It is not an error if the child element does not exist, but only later if a conversion to user data is attempted.

Template Parameters

String Arbitrary string-like type: e.g. std::string, wchar_t*, char[], wchar_t, wxString, MyStringClass, ...

Parameters

name	The name of the child element

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation