XML pull parser. More...

#include <plask/utils/xml/reader.hpp>

Collaboration diagram for plask::XMLReader:

Classes
struct	CFileDataSource
	Allows to read XML from old C FILE. More...

class	CheckTagDuplication
	Util class that allow to check of duplication of tags. More...

struct	DataSource
	Base class to source of data. More...

struct	EnumAttributeReader
	Enum attribute reader class. More...

struct	StreamDataSource
	Allows to read XML from standard C++ input stream (std::istream). More...

Public Types
enum	NodeType { NODE_ELEMENT = 1 , NODE_ELEMENT_END = 2 , NODE_TEXT = 4 }
	Enumeration for all xml nodes which are parsed by XMLReader. More...

typedef std::function< std::string(const std::string &)>	Filter
	Filter can change attribute or content value before parse.

Public Member Functions
void	setFilters (Filter f)
	Set attribute and content filter to `f`.

void	throwException (const std::string &msg) const
	Throw exception which include information about current position in XML and typically describe logic error in XML file.

void	throwUnexpectedEndException () const
	Throw XMLUnexpectedEndException.

template<typename... Args>
void	throwUnexpectedElementException (Args &&... args) const
	Throw XMLUnexpectedElementException.

NodeType	ensureNodeTypeIs (int required_types, const char *new_tag_name=nullptr) const
	Throw XMLUnexpectedElementException if node type is not included in required_types or (only when new_tag_name is given) node type is NODE_ELEMENT and name is not equal to new_tag_name.

	XMLReader (std::unique_ptr< DataSource > &&source)
	Construct XML reader to read XML from given source.

	XMLReader (std::unique_ptr< std::istream > &&istream)
	Construct XML reader to read XML from given stream.

	XMLReader (const char *file_name)
	Construct XML reader to read XML from given file.

	XMLReader (FILE *file)
	Construct XML reader to read XML from given `file` FILE*.

	~XMLReader ()
	Delete source and XML parser.

void	swap (XMLReader &to_swap)
	Swap states of `this` and `to_swap`.

NodeType	getNodeType () const
	Get current type of node.

unsigned	getLineNr () const
	Get line number where current element starts.

unsigned	getColumnNr () const
	Get column number where current element starts.

bool	next ()
	Reads forward to the next xml node.

const std::vector< std::string > &	getPath () const
	Get vector of names of all opened tags from root to current one.

std::size_t	getLevel () const
	Get level of current node.

std::size_t	getAttributeCount () const
	Returns attribute count of the current XML node.

const std::map< std::string, std::string >	getAttributes () const
	Get all attributes, empty if current node is not NODE_ELEMENT.

void	ignoreAttribute (const std::string &name)
	Mark attribute with given name as read, so parser does not throw an exception if this attribute will be not read.

void	ignoreAllAttributes () const
	Allow to have unread attributes in current tag.

bool	hasAttribute (const std::string &name) const
	Check if current node has attribute with given `name`.

template<typename EnumT >
EnumAttributeReader< EnumT >	enumAttribute (const std::string attr_name, bool case_sensitive=false)
	Create EnumAttributeReader.

void	removeAlienNamespaceAttr ()
	Remove from attributes all attributes which are not in the default (empty) namespace.

std::string	getNodeName () const
	Returns the name of the current node (tag).

std::string	getTagName () const
	Returns the name of the current node (tag).

std::string	getTextContent () const
	Check if current node is NODE_TEXT (throw exception if it's not) and get node data (text content).

template<typename T >
T	getTextContent () const
	Check if current node is NODE_TEXT (throw exception if it's not) and get node data (text content).

template<typename T >
T	getAttribute (const std::string &name, const T &default_value) const
	Get value of attribute with given `name`, or `default_value` if attribute with given `name` is not defined in current node.

plask::optional< std::string >	getAttribute (const std::string &name) const
	Get value of attribute with given `name`.

template<typename T >
plask::optional< T >	getAttribute (const std::string &name) const
	Get value of attribute with given `name`.

std::string	requireAttribute (const std::string &attr_name) const
	Require the attribute with given `name`.

template<typename T >
T	requireAttribute (const std::string &name) const
	Require the attribute with given `name`.

void	requireNext ()
	Go to next element.

NodeType	requireNext (int required_types, const char *new_tag_name=nullptr)
	Go to next element.

void	requireTag ()
	Call requireNext() and next check if current element is tag opening.

void	requireTag (const std::string &name)
	Call requireNext() and next check if current element is tag opening.

bool	requireTagOrEnd ()
	Call requireNext() and next check if current element is tag opening or closing of tag.

bool	requireTagOrEnd (const std::string &name)
	Call requireNext() and next check if current element is tag opening (in such case it also check if it has name equal to given `name`) or closing of tag.

void	requireTagEnd ()
	Call requireNext() and next check if current element is tag closing.

std::string	requireText ()
	Call requireNext() and next check if current element is text.

std::string	requireTextInCurrentTag ()
	Read text inside current tag.

template<typename T >
T	requireText ()
	Call requireNext() and next check if current element is text.

template<typename T >
T	requireTextInCurrentTag ()
	Call requireNext() and next check if current element is text.

bool	gotoNextOnLevel (std::size_t required_level, NodeType required_type=NODE_ELEMENT)
	Skip everything up to element with required type on required level.

bool	gotoNextTagOnCurrentLevel ()
	Skip everything up to next tag element on current level.

void	gotoEndOfCurrentTag ()
	Skip everything up to end of the current tag.

Public Attributes
StringInterpreter	stringInterpreter
	Parsers used to interpret string values.

Filter	attributeFilter
	Filter that can change attribute value before parse.

Filter	contentFilter
	Filter that can change content value before parse.

Detailed Description

XML pull parser.

It makes some checks while reading and throw exceptions when XML document not is valid:

it check open/close tags,
it checks if all attributes was read.

Definition at line 118 of file reader.hpp.

Member Typedef Documentation

◆ Filter

typedef std::function<std::string(const std::string&)> plask::XMLReader::Filter

Filter can change attribute or content value before parse.

Definition at line 311 of file reader.hpp.

Member Enumeration Documentation

◆ NodeType

enum plask::XMLReader::NodeType

Enumeration for all xml nodes which are parsed by XMLReader.

Enumerator
NODE_ELEMENT	A xml element, like <foo>
NODE_ELEMENT_END	End of an xml element, like </foo>
NODE_TEXT	Text within a xml element: <foo> this is the text. </foo>

Definition at line 122 of file reader.hpp.

Constructor & Destructor Documentation

◆ XMLReader() [1/4]

plask::XMLReader::XMLReader ( std::unique_ptr< DataSource > && source )

Construct XML reader to read XML from given source.

Parameters

source source of XML data, will be delete by this after use by this

Definition at line 125 of file reader.cpp.

◆ XMLReader() [2/4]

plask::XMLReader::XMLReader ( std::unique_ptr< std::istream > && istream )

Construct XML reader to read XML from given stream.

Parameters

istream stream to read, will be closed and delete by this

Definition at line 131 of file reader.cpp.

◆ XMLReader() [3/4]

plask::XMLReader::XMLReader ( const char * file_name )

Construct XML reader to read XML from given file.

Parameters

file_name name of file to read

Definition at line 137 of file reader.cpp.

◆ XMLReader() [4/4]

plask::XMLReader::XMLReader ( FILE * file )

Construct XML reader to read XML from given file FILE*.

Parameters

file	input file

Definition at line 143 of file reader.cpp.

◆ ~XMLReader()

plask::XMLReader::~XMLReader ( )

Delete source and XML parser.

Definition at line 169 of file reader.cpp.

Member Function Documentation

◆ ensureNodeTypeIs()

XMLReader::NodeType plask::XMLReader::ensureNodeTypeIs	(	int	required_types,
		const char *	new_tag_name = `nullptr`
	)		const

Throw XMLUnexpectedElementException if node type is not included in required_types or (only when new_tag_name is given) node type is NODE_ELEMENT and name is not equal to new_tag_name.

Parameters

required_types	bit sum of NodeType-s
new_tag_name	(optional) name of required tag (ignored if NODE_ELEMENT is not included in required_types)

Returns: type of current node

Definition at line 91 of file reader.cpp.

◆ enumAttribute()

template<typename EnumT >

EnumAttributeReader< EnumT > plask::XMLReader::enumAttribute	(	const std::string	attr_name,
		bool	case_sensitive = `false`
	)

inline

Create EnumAttributeReader.

Parameters

attr_name	name of the attribute
case_sensitive	true if the attribute value should be case sensitive

Definition at line 649 of file reader.hpp.

◆ getAttribute() [1/3]

plask::optional< std::string > plask::XMLReader::getAttribute ( const std::string & name ) const

Get value of attribute with given name.

Parameters

name	name of attribute to get

Returns: plask::optional which represent value of attribute with given name or has no value if there is no attribute with given name

Definition at line 276 of file reader.cpp.

◆ getAttribute() [2/3]

template<typename T >

plask::optional< T > plask::XMLReader::getAttribute ( const std::string & name ) const

inline

Get value of attribute with given name.

Throws exception if value of attribute given name can't be casted to required type T.

Parameters

name	name of attribute to get

Returns: plask::optional which represent value of attribute with given name or has no value if there is no attribute with given name

Template Parameters

T	required type of value, boost::lexical_cast<T> or registered parser will be used to obtain value of this type from string

Definition at line 721 of file reader.hpp.

◆ getAttribute() [3/3]

template<typename T >

T plask::XMLReader::getAttribute	(	const std::string &	name,
		const T &	default_value
	)		const

inline

Get value of attribute with given name, or default_value if attribute with given name is not defined in current node.

Parameters

name	name of attribute
default_value	default value which will be return when attribute with given `name` is not defined

Returns: attribute with given name, or default_value if attribute with given name is not defined in current node

Template Parameters

T	required type of value, boost::lexical_cast<T> or registered parser will be used to obtain value of this type from string

Definition at line 697 of file reader.hpp.

◆ getAttributeCount()

std::size_t plask::XMLReader::getAttributeCount ( ) const

inline

Returns attribute count of the current XML node.

This is usually non 0 if the current node is NODE_ELEMENT, and the element has attributes.

Returns: amount of attributes of this xml node.

Definition at line 617 of file reader.hpp.

◆ getAttributes()

const std::map< std::string, std::string > plask::XMLReader::getAttributes ( ) const

Get all attributes, empty if current node is not NODE_ELEMENT.

Returns: all attributes, reference is valid up to read() call

Definition at line 214 of file reader.cpp.

◆ getColumnNr()

unsigned plask::XMLReader::getColumnNr ( ) const

inline

Get column number where current element starts.

Returns: column number of current element start

Definition at line 581 of file reader.hpp.

◆ getLevel()

std::size_t plask::XMLReader::getLevel ( ) const

inline

Get level of current node.

Root has level 1, children of root have level 2, and so on.

Returns: level of current node which is equal to length of path returned by getPath()

Definition at line 609 of file reader.hpp.

◆ getLineNr()

unsigned plask::XMLReader::getLineNr ( ) const

inline

Get line number where current element starts.

Returns: line number of current element start

Definition at line 575 of file reader.hpp.

◆ getNodeName()

std::string plask::XMLReader::getNodeName ( ) const

Returns the name of the current node (tag).

Throw exception if it is not defined.

Returns: name of the current node

Definition at line 247 of file reader.cpp.

◆ getNodeType()

NodeType plask::XMLReader::getNodeType ( ) const

inline

Get current type of node.

Returns: current type of node

Definition at line 569 of file reader.hpp.

◆ getPath()

const std::vector< std::string > & plask::XMLReader::getPath ( ) const

inline

Get vector of names of all opened tags from root to current one.

Includes tag which is just closed when the current node is NODE_ELEMENT_END.

Returns: vector of names of all opened tags, first is root, last is current tag

Definition at line 603 of file reader.hpp.

◆ getTagName()

std::string plask::XMLReader::getTagName ( ) const

inline

Returns the name of the current node (tag).

Throw exception if it is not defined.

Returns: name of the current node

Definition at line 672 of file reader.hpp.

◆ getTextContent() [1/2]

std::string plask::XMLReader::getTextContent ( ) const

Check if current node is NODE_TEXT (throw exception if it's not) and get node data (text content).

Returns: data of the current node

Definition at line 257 of file reader.cpp.

◆ getTextContent() [2/2]

template<typename T >

T plask::XMLReader::getTextContent ( ) const

inline

Check if current node is NODE_TEXT (throw exception if it's not) and get node data (text content).

Returns: data of the current node casted (by lexical_cast) to given type T

Definition at line 685 of file reader.hpp.

◆ gotoEndOfCurrentTag()

void plask::XMLReader::gotoEndOfCurrentTag ( )

Skip everything up to end of the current tag.

Definition at line 354 of file reader.cpp.

◆ gotoNextOnLevel()

bool plask::XMLReader::gotoNextOnLevel	(	std::size_t	required_level,
		NodeType	required_type = `NODE_ELEMENT`
	)

Skip everything up to element with required type on required level.

Parameters

required_level	level on which required element should be
required_type	type of required element

Returns: true if reader is on required element or false if XML data end

Definition at line 340 of file reader.cpp.

◆ gotoNextTagOnCurrentLevel()

bool plask::XMLReader::gotoNextTagOnCurrentLevel ( )

Skip everything up to next tag element on current level.

Returns: true if reader is on required element or false if XML data end

Definition at line 350 of file reader.cpp.

◆ hasAttribute()

bool plask::XMLReader::hasAttribute ( const std::string & name ) const

inline

Check if current node has attribute with given name.

Parameters

name	attribute name

Returns: true only if current node has attribute with given name

Definition at line 641 of file reader.hpp.

◆ ignoreAllAttributes()

void plask::XMLReader::ignoreAllAttributes ( ) const

inline

Allow to have unread attributes in current tag.

Definition at line 634 of file reader.hpp.

◆ ignoreAttribute()

void plask::XMLReader::ignoreAttribute ( const std::string & name )

inline

Mark attribute with given name as read, so parser does not throw an exception if this attribute will be not read.

Parameters

name	name of attribute to ignore

Definition at line 629 of file reader.hpp.

◆ next()

bool plask::XMLReader::next ( )

Reads forward to the next xml node.

Returns: false only if there is no further node.

Definition at line 184 of file reader.cpp.

◆ removeAlienNamespaceAttr()

void plask::XMLReader::removeAlienNamespaceAttr ( )

Remove from attributes all attributes which are not in the default (empty) namespace.

Definition at line 235 of file reader.cpp.

◆ requireAttribute() [1/2]

std::string plask::XMLReader::requireAttribute ( const std::string & attr_name ) const

Require the attribute with given name.

Throws exception if there is no attribute with given name.

Returns: its value

Definition at line 294 of file reader.cpp.

◆ requireAttribute() [2/2]

template<typename T >

T plask::XMLReader::requireAttribute ( const std::string & name ) const

inline

Require the attribute with given name.

Throws exception if there is no attribute with given name.

Returns: its value

Template Parameters

T	required type of value, boost::lexical_cast<T> will be used to obtain value of this type from string

Definition at line 743 of file reader.hpp.

◆ requireNext() [1/2]

void plask::XMLReader::requireNext ( )

Go to next element.

Exceptions

XMLUnexpectedEndException if there is no next element

Definition at line 300 of file reader.cpp.

◆ requireNext() [2/2]

XMLReader::NodeType plask::XMLReader::requireNext	(	int	required_types,
		const char *	new_tag_name = `nullptr`
	)

Go to next element.

Parameters

required_types	bit sum of NodeType-s
new_tag_name	(optional) name of required tag (ignored if NODE_ELEMENT is not included in required_types)

Returns: type of new current node

Exceptions

XMLUnexpectedElementException	if node type is not included in `required_types` or (only when new_tag_name is given) node type is `NODE_ELEMENT` and name is not equal to `new_tag_name`.
XMLUnexpectedEndException	if there is no next element

Definition at line 304 of file reader.cpp.

◆ requireTag() [1/2]

void plask::XMLReader::requireTag ( )

Call requireNext() and next check if current element is tag opening.

Throw exception if it's not.

Definition at line 309 of file reader.cpp.

◆ requireTag() [2/2]

void plask::XMLReader::requireTag ( const std::string & name )

Call requireNext() and next check if current element is tag opening.

Throw exception if it's not or if it name is not name.

Definition at line 313 of file reader.cpp.

◆ requireTagEnd()

void plask::XMLReader::requireTagEnd ( )

Call requireNext() and next check if current element is tag closing.

Throw exception if it's not.

Definition at line 325 of file reader.cpp.

◆ requireTagOrEnd() [1/2]

bool plask::XMLReader::requireTagOrEnd ( )

Call requireNext() and next check if current element is tag opening or closing of tag.

Throw exception if it's not.

Returns: true if the next tag was opened

Definition at line 317 of file reader.cpp.

◆ requireTagOrEnd() [2/2]

bool plask::XMLReader::requireTagOrEnd ( const std::string & name )

Call requireNext() and next check if current element is tag opening (in such case it also check if it has name equal to given name) or closing of tag.

Throw exception if it's not.

Parameters

name	required name of opening tag

Returns: true if the next tag was opened

Definition at line 321 of file reader.cpp.

◆ requireText() [1/2]

std::string plask::XMLReader::requireText ( )

Call requireNext() and next check if current element is text.

Throw exception if it's not.

Returns: read text

Definition at line 329 of file reader.cpp.

◆ requireText() [2/2]

template<typename T >

T plask::XMLReader::requireText ( )

inline

Call requireNext() and next check if current element is text.

Throw exception if it's not.

Returns: read text casted (by lexical_cast) to givent type T

Definition at line 812 of file reader.hpp.

◆ requireTextInCurrentTag() [1/2]

std::string plask::XMLReader::requireTextInCurrentTag ( )

Read text inside current tag.

Move parser to end of current tag.

Returns: read text

Definition at line 334 of file reader.cpp.

◆ requireTextInCurrentTag() [2/2]

template<typename T >

T plask::XMLReader::requireTextInCurrentTag ( )

inline

Call requireNext() and next check if current element is text.

Throw exception if it's not. Next require end of tag.

Returns: read text casted (by lexical_cast) to givent type T

Definition at line 821 of file reader.hpp.

◆ setFilters()

void plask::XMLReader::setFilters ( Filter f )

inline

Set attribute and content filter to f.

Parameters

f	new filter common for attribute and content

Definition at line 409 of file reader.hpp.

◆ swap()

void plask::XMLReader::swap ( XMLReader & to_swap )

Swap states of this and to_swap.

Parameters

to_swap object to swap with this

Definition at line 173 of file reader.cpp.

◆ throwException()

void plask::XMLReader::throwException ( const std::string & msg ) const

inline

Throw exception which include information about current position in XML and typically describe logic error in XML file.

Parameters

msg	custom part of exception message

Definition at line 479 of file reader.hpp.

◆ throwUnexpectedElementException()

template<typename... Args>

void plask::XMLReader::throwUnexpectedElementException ( Args &&... args ) const

inline

Throw XMLUnexpectedElementException.

Parameters

args... XMLUnexpectedElementException constructor arguments to use, excluding the first one

Definition at line 491 of file reader.hpp.

◆ throwUnexpectedEndException()

void plask::XMLReader::throwUnexpectedEndException ( ) const

inline

Throw XMLUnexpectedEndException.

Definition at line 484 of file reader.hpp.

Member Data Documentation

◆ attributeFilter

Filter plask::XMLReader::attributeFilter

Filter that can change attribute value before parse.

Definition at line 400 of file reader.hpp.

◆ contentFilter

Filter plask::XMLReader::contentFilter

Filter that can change content value before parse.

Definition at line 403 of file reader.hpp.

◆ stringInterpreter

StringInterpreter plask::XMLReader::stringInterpreter

Parsers used to interpret string values.

Definition at line 397 of file reader.hpp.

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

plask/utils/xml/reader.hpp
plask/utils/xml/reader.cpp

Classes

Public Types

Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ Filter

Member Enumeration Documentation

◆ NodeType

Constructor & Destructor Documentation

◆ XMLReader() [1/4]

◆ XMLReader() [2/4]

◆ XMLReader() [3/4]

◆ XMLReader() [4/4]

◆ ~XMLReader()

Member Function Documentation

◆ ensureNodeTypeIs()

◆ enumAttribute()

◆ getAttribute() [1/3]

◆ getAttribute() [2/3]

◆ getAttribute() [3/3]

◆ getAttributeCount()

◆ getAttributes()

◆ getColumnNr()

◆ getLevel()

◆ getLineNr()

◆ getNodeName()

◆ getNodeType()

◆ getPath()

◆ getTagName()

◆ getTextContent() [1/2]

◆ getTextContent() [2/2]

◆ gotoEndOfCurrentTag()

◆ gotoNextOnLevel()

◆ gotoNextTagOnCurrentLevel()

◆ hasAttribute()

◆ ignoreAllAttributes()

◆ ignoreAttribute()

◆ next()

◆ removeAlienNamespaceAttr()

◆ requireAttribute() [1/2]

◆ requireAttribute() [2/2]

◆ requireNext() [1/2]

◆ requireNext() [2/2]

◆ requireTag() [1/2]

◆ requireTag() [2/2]

◆ requireTagEnd()

◆ requireTagOrEnd() [1/2]

◆ requireTagOrEnd() [2/2]

◆ requireText() [1/2]

◆ requireText() [2/2]

◆ requireTextInCurrentTag() [1/2]

◆ requireTextInCurrentTag() [2/2]

◆ setFilters()

◆ swap()

◆ throwException()

◆ throwUnexpectedElementException()

◆ throwUnexpectedEndException()

Member Data Documentation

◆ attributeFilter

◆ contentFilter

◆ stringInterpreter