PLaSK library

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Public Attributes | List of all members
plask::XMLReader Class Reference

XML pull parser. More...

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

Collaboration diagram for plask::XMLReader:
[legend]

## 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