regina::XMLElementReader Class Reference
File

Used to read the contents of a single XML element. More...

`#include <utilities/xmlelementreader.h>`

Inheritance diagram for regina::XMLElementReader:

## Public Member Functions

| XMLElementReader ()
| Creates a new element reader. More...
virtual | ~XMLElementReader ()
| Destroys this element reader. More...
virtual void | startElement (const std::string &tagName, const regina::xml::XMLPropertyDict &tagProps, XMLElementReader *parentReader)
| Signifies that parsing of this XML element is beginning. More...
virtual void | initialChars (const std::string &chars)
| Signifies that the initial text belonging to this XML element has been read. More...
virtual XMLElementReader * | startSubElement (const std::string &subTagName, const regina::xml::XMLPropertyDict &subTagProps)
| Signifies that a subelement of this XML element is about to be parsed. More...
virtual void | endSubElement (const std::string &subTagName, XMLElementReader *subReader)
| Signifies that parsing has finished for a subelement of this XML element. More...
virtual void | endElement ()
| Signifies that parsing of this XML element is finished. More...
virtual void | usingParser (regina::xml::XMLParser *parser)
| Called for the top-level element in an XML file when parsing begins. More...
virtual void | abort (XMLElementReader *subReader)
| Signifies that XML parsing has been aborted. More...

## Detailed Description

Used to read the contents of a single XML element.

Specifically, this class concerns itself with reading and storing the contents between a single opening tag and the corresponding closing tag. It is not concerned with reading subelements of the element in question, although the contents of subelements will be made available.

Generally a subclass of XMLElementReader will be used to receive and store information that you care about. However, if you simply wish to ignore the contents of a particular XML element (and all of its subelements), you can use class XMLElementReader itself for the element(s) you wish to ignore.

When the parser runs through a particular XML element, the routines of the corresponding XMLElementReader will be called as follows. First startElement() and initialChars() will be called. Then for each subelement encountered the following processing will take place: startSubElement() will be called to create a new child reader, the entire cycle of parsing routines will be called upon this child reader and then endSubElement() will be called upon the parent reader, after which the child reader will be destroyed. After all subelements have been processed, endElement() will be called.

If at any point parsing is aborted, routine abort() will be called upon all active readers and all active readers will be destroyed.

To parse an entire XML file using a variety of element readers (all of which may be of different subclasses of XMLElementReader), create a new regina::xml::XMLParser with an XMLCallback as its corresponding callback object.

When parsing begins on an entire XML file, an additional call is made: usingParser() will be called on the top-level element reader, so that it can gain direct access to the parser if required.

Python:
  Not present.

## Constructor & Destructor Documentation

## XMLElementReader()

regina::XMLElementReader::XMLElementReader | ( |  | ) |

inline

Creates a new element reader.

## ~XMLElementReader()

regina::XMLElementReader::~XMLElementReader | ( |  | ) |

inline virtual

Destroys this element reader.

The default implementation does nothing.

## Member Function Documentation

## abort()

void regina::XMLElementReader::abort | ( | XMLElementReader * | subReader | ) |

inline virtual

Signifies that XML parsing has been aborted.

This element reader will be destroyed shortly after this routine is called.

The default implementation does nothing.

Parameters

  subReader | the corresponding child reader if a subelement is currently being parsed, or 0 otherwise. If this parameter is non-zero, it is guaranteed that abort() has already been called upon the child reader and that the child reader has not yet been destroyed.

Reimplemented in regina::XMLPacketReader.

## endElement()

void regina::XMLElementReader::endElement | ( |  | ) |

inline virtual

Signifies that parsing of this XML element is finished.

It is guaranteed that endSubElement() has not yet been called upon the parent reader (if one exists).

The default implementation does nothing.

## endSubElement()

void regina::XMLElementReader::endSubElement | ( | const std::string & | subTagName,
|  | XMLElementReader * | subReader
| ) |  |

inline virtual

Signifies that parsing has finished for a subelement of this XML element.

The default implementation does nothing.

Parameters

  subTagName | the name of the subelement closing tag.
  subReader | the child reader that was used to parse the subelement (this is the reader that was returned by the corresponding startSubElement() call). It is guaranteed that endElement() has already been called upon this child reader and that the child reader has not yet been destroyed.

Reimplemented in regina::detail::XMLTriangulationReaderBase< dim >::GroupPresentationPropertyReader, regina::detail::XMLTriangulationReaderBase< dim >::AbelianGroupPropertyReader, regina::XMLPacketReader, and regina::XMLGroupPresentationReader.

## initialChars()

void regina::XMLElementReader::initialChars | ( | const std::string & | chars | ) |

inline virtual

Signifies that the initial text belonging to this XML element has been read.

The initial text is everything between the opening tag and the first subelement or closing tag.

The default implementation does nothing.

Parameters

  chars | the initial text for this element.

Reimplemented in regina::XMLCharsReader, regina::detail::XMLSimplexReader< dim >, regina::XMLNormalHypersurfaceReader, regina::XMLNormalSurfaceReader, regina::XMLAngleStructureReader, and regina::XMLAbelianGroupReader.

## startElement()

void regina::XMLElementReader::startElement | ( | const std::string & | tagName,
|  | const regina::xml::XMLPropertyDict & | tagProps,
|  | XMLElementReader * | parentReader
| ) |  |

inline virtual

Signifies that parsing of this XML element is beginning.

The default implementation does nothing.

Parameters

  tagName | the name of the opening tag for this element.
  tagProps | the properties associated with the opening tag.
  parentReader | the reader currently parsing the parent XML element, or 0 if this is the top-level element. If this paraneter is non-zero, it is guaranteed that startSubElement() has already been called upon the parent reader.

Reimplemented in regina::detail::XMLSimplicesReader< dim >, regina::detail::XMLSimplexReader< dim >, regina::XMLGroupPresentationReader, regina::XMLNormalHypersurfaceReader, regina::XMLNormalSurfaceReader, regina::XMLAngleStructureReader, and regina::XMLAbelianGroupReader.

## startSubElement()

XMLElementReader * regina::XMLElementReader::startSubElement | ( | const std::string & | subTagName,
|  | const regina::xml::XMLPropertyDict & | subTagProps
| ) |  |

inline virtual

Signifies that a subelement of this XML element is about to be parsed.

The default implementation returns a new XMLElementReader which can be used to ignore the subelement completely.

Parameters

  subTagName | the name of the subelement opening tag.
  subTagProps | the properties associated with the subelement opening tag.

Returns
  a newly created element reader that will be used to parse the subelement. This class should not take care of the new reader's destruction; that will be done by the parser.

Reimplemented in regina::detail::XMLTriangulationReaderBase< dim >::GroupPresentationPropertyReader, regina::detail::XMLTriangulationReaderBase< dim >::AbelianGroupPropertyReader, regina::XMLPacketReader, regina::detail::XMLSimplicesReader< dim >, regina::XMLGroupPresentationReader, regina::XMLNormalHypersurfaceReader, regina::XMLNormalSurfaceReader, and regina::XMLAngleStructureReader.

## usingParser()

void regina::XMLElementReader::usingParser | ( | regina::xml::XMLParser * | parser | ) |

inline virtual

Called for the top-level element in an XML file when parsing begins.

This allows direct access to the parser if needed (for instance, to change the character encoding).

The default implementation does nothing.

Parameters

  parser | the current XML parser.

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

- utilities/xmlelementreader.h

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).