libxml++: xmlpp::SaxParser Class Reference

libxml++ 5.0.2

Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
xmlpp::SaxParser Class Reference

SAX XML parser. More...

`#include <libxml++/parsers/saxparser.h>`

Inheritance diagram for xmlpp::SaxParser:
[legend]

## Classes
struct | Attribute
| Simple structure used in the start_element callback, in which the attributes are a list of name/value pairs. More...
struct | AttributeHasName
| This functor is a helper to find an attribute by name in an AttributeList using the standard algorithm std::find_if. More...

## Public Types
using | AttributeList = std::deque< Attribute >
Public Types inherited from xmlpp::Parser
using | size_type = unsigned int

## Public Member Functions
LIBXMLPP_API | SaxParser (bool use_get_entity=false)
LIBXMLPP_API | ~SaxParser () override
LIBXMLPP_API void | finish_chunk_parsing ()
| Finish a chunk-wise parse. More...
LIBXMLPP_API void | parse_chunk (const ustring & chunk)
| Parse a chunk of data. More...
LIBXMLPP_API void | parse_chunk_raw (const unsigned char * contents, size_type bytes_count)
| Parse a chunk of data. More...
LIBXMLPP_API void | parse_file (const std::string & filename) override
| Parse an XML document from a file. More...
LIBXMLPP_API void | parse_memory (const ustring & contents) override
| Parse an XML document from a string. More...
LIBXMLPP_API void | parse_memory_raw (const unsigned char * contents, size_type bytes_count) override
| Parse an XML document from raw memory. More...
LIBXMLPP_API void | parse_stream (std::istream & in) override
| Parse an XML document from a stream. More...
Public Member Functions inherited from xmlpp::Parser
LIBXMLPP_API | Parser ()
LIBXMLPP_API | ~Parser () override
LIBXMLPP_API bool | get_include_default_attributes () const noexcept
| See set_include_default_attributes(). More...
LIBXMLPP_API void | get_parser_options (int & set_options, int & clear_options) const noexcept
| See set_parser_options(). More...
LIBXMLPP_API bool | get_substitute_entities () const noexcept
| See set_substitute_entities(). More...
LIBXMLPP_API bool | get_throw_messages () const noexcept
| See set_throw_messages(). More...
LIBXMLPP_API bool | get_validate () const noexcept
| See set_validate(). More...
virtual LIBXMLPP_API void | parse_file (const std::string & filename)=0
| Parse an XML document from a file. More...
virtual LIBXMLPP_API void | parse_memory (const ustring & contents)=0
| Parse an XML document from a string. More...
virtual LIBXMLPP_API void | parse_memory_raw (const unsigned char * contents, size_type bytes_count)=0
| Parse an XML document from raw memory. More...
virtual LIBXMLPP_API void | parse_stream (std::istream & in)=0
| Parse an XML document from a stream. More...
LIBXMLPP_API void | set_include_default_attributes (bool val=true) noexcept
| Set whether default attribute values from the DTD shall be included in the node tree. More...
LIBXMLPP_API void | set_parser_options (int set_options=0, int clear_options=0) noexcept
| Set and/or clear parser option flags. More...
LIBXMLPP_API void | set_substitute_entities (bool val=true) noexcept
| Set whether the parser will automatically substitute entity references with the text of the entities' definitions. More...
LIBXMLPP_API void | set_throw_messages (bool val=true) noexcept
| Set whether the parser will collect and throw error and warning messages. More...
LIBXMLPP_API void | set_validate (bool val=true) noexcept
| By default, the parser will not validate the XML file. More...
Public Member Functions inherited from xmlpp::NonCopyable
| NonCopyable (const NonCopyable &)=delete
| NonCopyable (NonCopyable &&)=delete
NonCopyable & | operator= (const NonCopyable &)=delete
NonCopyable & | operator= (NonCopyable &&)=delete

## Protected Member Functions
LIBXMLPP_API void | initialize_context () override
virtual LIBXMLPP_API void | on_cdata_block (const ustring & text)
virtual LIBXMLPP_API void | on_characters (const ustring & characters)
virtual LIBXMLPP_API void | on_comment (const ustring & text)
virtual LIBXMLPP_API void | on_end_document ()
virtual LIBXMLPP_API void | on_end_element (const ustring & name)
virtual LIBXMLPP_API void | on_entity_declaration (const ustring & name, XmlEntityType type, const ustring & publicId, const ustring & systemId, const ustring & content)
| Override this to receive information about every entity declaration. More...
virtual LIBXMLPP_API void | on_error (const ustring & text)
virtual LIBXMLPP_API void | on_fatal_error (const ustring & text)
virtual LIBXMLPP_API _xmlEntity * | on_get_entity (const ustring & name)
| Override this method to resolve entities references in your derived parser, instead of using the default entity resolution, or to be informed when entity references are encountered. More...
virtual LIBXMLPP_API void | on_internal_subset (const ustring & name, const ustring & publicId, const ustring & systemId)
| Override this to receive information about the document's DTD and any entity declarations. More...
virtual LIBXMLPP_API void | on_start_document ()
virtual LIBXMLPP_API void | on_start_element (const ustring & name, const AttributeList & attributes)
virtual LIBXMLPP_API void | on_warning (const ustring & text)
LIBXMLPP_API void | release_underlying () override
Protected Member Functions inherited from xmlpp::Parser
virtual LIBXMLPP_API void | check_for_error_and_warning_messages ()
virtual LIBXMLPP_API void | check_for_exception ()
virtual LIBXMLPP_API void | handle_exception ()
| To be called in an exception handler. More...
virtual LIBXMLPP_API void | initialize_context ()
virtual LIBXMLPP_API void | on_parser_error (const ustring & message)
virtual LIBXMLPP_API void | on_parser_warning (const ustring & message)
virtual LIBXMLPP_API void | on_validity_error (const ustring & message)
virtual LIBXMLPP_API void | on_validity_warning (const ustring & message)
virtual LIBXMLPP_API void | release_underlying ()
Protected Member Functions inherited from xmlpp::NonCopyable
| NonCopyable () noexcept
virtual | ~NonCopyable ()

## Additional Inherited Members
Protected Types inherited from xmlpp::Parser
enum class | MsgType { ParserError , ParserWarning , ValidityError , ValidityWarning }
Static Protected Member Functions inherited from xmlpp::Parser
static LIBXMLPP_API void | callback_error_or_warning (MsgType msg_type, void * ctx, const char * msg, va_list var_args)
static LIBXMLPP_API void | callback_parser_error (void * ctx, const char * msg,...)
static LIBXMLPP_API void | callback_parser_warning (void * ctx, const char * msg,...)
static LIBXMLPP_API void | callback_validity_error (void * ctx, const char * msg,...)
static LIBXMLPP_API void | callback_validity_warning (void * ctx, const char * msg,...)
Protected Attributes inherited from xmlpp::Parser
_xmlParserCtxt * | context_
std::unique_ptr< exception > | exception_

## Detailed Description

SAX XML parser.

Derive your own class and override the on_*() methods. SAX = Simple API for XML

In a system that does not support std::exception_ptr: If an overridden on_*() method throws an exception which is not derived from xmlpp::exception, that exception is replaced by a xmlpp::exception before it is propagated out of the parse method, such as parse_file().

## Member Typedef Documentation

## ◆ AttributeList

using xmlpp::SaxParser::AttributeList = std::deque<Attribute>

## Constructor & Destructor Documentation

## ◆ SaxParser()

LIBXMLPP_API xmlpp::SaxParser::SaxParser | ( | bool | use_get_entity = `false` | ) |

Parameters

  use_get_entity | Set this to true if you will override on_get_entity(). In theory, if you do not override on_get_entity() the parser should behave exactly the same whether you use true or false here. But the default implementation of on_get_entity(), needed if you override on_get_entity() might not have the same behaviour as the underlying default behaviour of libxml, so the libxml implementation is the default here.

## ◆ ~SaxParser()

LIBXMLPP_API xmlpp::SaxParser::~SaxParser | ( |  | ) |
| override

## Member Function Documentation

## ◆ finish_chunk_parsing()

LIBXMLPP_API void xmlpp::SaxParser::finish_chunk_parsing | ( |  | ) |

Finish a chunk-wise parse.

Call this after the last call to parse_chunk() or parse_chunk_raw(). Don't use this function with the other parsing methods.

Exceptions

  xmlpp::internal_error |
  xmlpp::parse_error |
  xmlpp::validity_error |

## ◆ initialize_context()

LIBXMLPP_API void xmlpp::SaxParser::initialize_context | ( |  | ) |
| overrideprotectedvirtual

Reimplemented from xmlpp::Parser.

## ◆ on_cdata_block()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_cdata_block | ( | const ustring & | text | ) |
| protectedvirtual

## ◆ on_characters()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_characters | ( | const ustring & | characters | ) |
| protectedvirtual

## ◆ on_comment()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_comment | ( | const ustring & | text | ) |
| protectedvirtual

## ◆ on_end_document()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_end_document | ( |  | ) |
| protectedvirtual

## ◆ on_end_element()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_end_element | ( | const ustring & | name | ) |
| protectedvirtual

## ◆ on_entity_declaration()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_entity_declaration | ( | const ustring & | name,
|  | XmlEntityType | type,
|  | const ustring & | publicId,
|  | const ustring & | systemId,
|  | const ustring & | content
| ) |  |
| protectedvirtual

Override this to receive information about every entity declaration.

If you override this function, and you want normal entity substitution to work, then you must call the base class in your override.

This would be useful when overriding on_get_entity().

Exceptions

  xmlpp::internal_error |

## ◆ on_error()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_error | ( | const ustring & | text | ) |
| protectedvirtual

## ◆ on_fatal_error()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_fatal_error | ( | const ustring & | text | ) |
| protectedvirtual

Exceptions

  xmlpp::parse_error |

## ◆ on_get_entity()

virtual LIBXMLPP_API _xmlEntity * xmlpp::SaxParser::on_get_entity | ( | const ustring & | name | ) |
| protectedvirtual

Override this method to resolve entities references in your derived parser, instead of using the default entity resolution, or to be informed when entity references are encountered.

If you override this function then you must also specify true for use_get_entity constructor parameter. You will probably need to override on_entity_declaration() as well so that you can use that information when resolving the entity reference.

This is known to be difficult, because it requires both an understanding of the W3C specifications and knowledge of the libxml internals. Entity resolution is easier with the DomParser.

Call this method in this base class for default processing. For instance, if you just want to know about the existence of an entity reference, without affecting the normal substitution, just override and call the base class.

Unlike the DomParser, the SaxParser will also tell you about entity references for the 5 predefined entities.

Parameters

  name | The entity reference name.

Returns
  The resolved xmlEntity for the entity reference, or `nullptr` if not found. You must include libxml/parser.h in order to use this C struct. This instance will not be freed by the caller.

## ◆ on_internal_subset()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_internal_subset | ( | const ustring & | name,
|  | const ustring & | publicId,
|  | const ustring & | systemId
| ) |  |
| protectedvirtual

Override this to receive information about the document's DTD and any entity declarations.

## ◆ on_start_document()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_start_document | ( |  | ) |
| protectedvirtual

## ◆ on_start_element()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_start_element | ( | const ustring & | name,
|  | const AttributeList & | attributes
| ) |  |
| protectedvirtual

## ◆ on_warning()

virtual LIBXMLPP_API void xmlpp::SaxParser::on_warning | ( | const ustring & | text | ) |
| protectedvirtual

## ◆ parse_chunk()

LIBXMLPP_API void xmlpp::SaxParser::parse_chunk | ( | const ustring & | chunk | ) |

Parse a chunk of data.

This lets you pass a document in small chunks, e.g. from a network connection. The on_* virtual functions are called each time the chunks provide enough information to advance the parser.

The first call to parse_chunk() will setup the parser. When the last chunk has been parsed, call finish_chunk_parsing() to finish the parse.

Parameters

  chunk | The next piece of the XML document.

Exceptions

  xmlpp::internal_error |
  xmlpp::parse_error |
  xmlpp::validity_error |

## ◆ parse_chunk_raw()

LIBXMLPP_API void xmlpp::SaxParser::parse_chunk_raw | ( | const unsigned char * | contents,
|  | size_type | bytes_count
| ) |  |

Parse a chunk of data.

Since libxml++ 2.24:

This lets you pass a document in small chunks, e.g. from a network connection. The on_* virtual functions are called each time the chunks provide enough information to advance the parser.

The first call to parse_chunk_raw() will setup the parser. When the last chunk has been parsed, call finish_chunk_parsing() to finish the parse.

Parameters

  contents | The next piece of the XML document as an array of bytes.
  bytes_count | The number of bytes in the contents array.

Exceptions

  xmlpp::internal_error |
  xmlpp::parse_error |
  xmlpp::validity_error |

## ◆ parse_file()

LIBXMLPP_API void xmlpp::SaxParser::parse_file | ( | const std::string & | filename | ) |
| overridevirtual

Parse an XML document from a file.

Parameters

  filename | The path to the file.

Exceptions

  xmlpp::internal_error |
  xmlpp::parse_error |
  xmlpp::validity_error |

Implements xmlpp::Parser.

## ◆ parse_memory()

LIBXMLPP_API void xmlpp::SaxParser::parse_memory | ( | const ustring & | contents | ) |
| overridevirtual

Parse an XML document from a string.

Parameters

  contents | The XML document as a string.

Exceptions

  xmlpp::internal_error |
  xmlpp::parse_error |
  xmlpp::validity_error |

Implements xmlpp::Parser.

## ◆ parse_memory_raw()

LIBXMLPP_API void xmlpp::SaxParser::parse_memory_raw | ( | const unsigned char * | contents,
|  | size_type | bytes_count
| ) |  |
| overridevirtual

Parse an XML document from raw memory.

Parameters

  contents | The XML document as an array of bytes.
  bytes_count | The number of bytes in the contents array.

Exceptions

  xmlpp::internal_error |
  xmlpp::parse_error |
  xmlpp::validity_error |

Implements xmlpp::Parser.

## ◆ parse_stream()

LIBXMLPP_API void xmlpp::SaxParser::parse_stream | ( | std::istream & | in | ) |
| overridevirtual

Parse an XML document from a stream.

Parameters

  in | The stream.

Exceptions

  xmlpp::internal_error |
  xmlpp::parse_error |
  xmlpp::validity_error |

Implements xmlpp::Parser.

## ◆ release_underlying()

LIBXMLPP_API void xmlpp::SaxParser::release_underlying | ( |  | ) |
| overrideprotectedvirtual

Reimplemented from xmlpp::Parser.