SAX XML parser. More...

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

Inheritance diagram for xmlpp::SaxParser:

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
	SaxParser (bool use_get_entity=false)

	~SaxParser () override

void	finish_chunk_parsing ()
	Finish a chunk-wise parse. More...

void	parse_chunk (const ustring & chunk)
	Parse a chunk of data. More...

void	parse_chunk_raw (const unsigned char * contents, size_type bytes_count)
	Parse a chunk of data. More...

void	parse_file (const std::string & filename) override
	Parse an XML document from a file. More...

void	parse_memory (const ustring & contents) override
	Parse an XML document from a string. More...

void	parse_memory_raw (const unsigned char * contents, size_type bytes_count) override
	Parse an XML document from raw memory. More...

void	parse_stream (std::istream & in) override
	Parse an XML document from a stream. More...

Public Member Functions inherited from xmlpp::Parser
	Parser ()

	~Parser () override

bool	get_include_default_attributes () const noexcept
	See set_include_default_attributes(). More...

void	get_parser_options (int & set_options, int & clear_options) const noexcept
	See set_parser_options(). More...

bool	get_substitute_entities () const noexcept
	See set_substitute_entities(). More...

bool	get_throw_messages () const noexcept
	See set_throw_messages(). More...

bool	get_validate () const noexcept
	See set_validate(). More...

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

void	set_parser_options (int set_options=0, int clear_options=0) noexcept
	Set and/or clear parser option flags. More...

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

void	set_throw_messages (bool val=true) noexcept
	Set whether the parser will collect and throw error and warning messages. More...

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
void	initialize_context () override

virtual void	on_cdata_block (const ustring & text)

virtual void	on_characters (const ustring & characters)

virtual void	on_comment (const ustring & text)

virtual void	on_end_document ()

virtual void	on_end_element (const ustring & name)

virtual 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 void	on_error (const ustring & text)

virtual void	on_fatal_error (const ustring & text)

virtual _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 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 void	on_start_document ()

virtual void	on_start_element (const ustring & name, const AttributeList & attributes)

virtual void	on_warning (const ustring & text)

void	release_underlying () override

Protected Member Functions inherited from xmlpp::Parser
virtual void	check_for_error_and_warning_messages ()

virtual void	check_for_exception ()

virtual void	handle_exception ()
	To be called in an exception handler. More...

virtual void	on_parser_error (const ustring & message)

virtual void	on_parser_warning (const ustring & message)

virtual void	on_validity_error (const ustring & message)

virtual void	on_validity_warning (const ustring & message)

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 void	callback_error_or_warning (bool is_parser, bool is_error, void * ctx, const char * msg, va_list var_args)

static void	callback_error_or_warning (MsgType msg_type, void * ctx, const char * msg, va_list var_args)

static void	callback_parser_error (void * ctx, const char * msg,...)

static void	callback_parser_warning (void * ctx, const char * msg,...)

static void	callback_validity_error (void * ctx, const char * msg,...)

static void	callback_validity_warning (void * ctx, const char * msg,...)

static ParserCallbackCFuncType	get_callback_parser_error_cfunc ()

static ParserCallbackCFuncType	get_callback_parser_warning_cfunc ()

static ParserCallbackCFuncType	get_callback_validity_error_cfunc ()

static ParserCallbackCFuncType	get_callback_validity_warning_cfunc ()

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()

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()

xmlpp::SaxParser::~SaxParser ( )

override

Member Function Documentation

◆ finish_chunk_parsing()

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()

void xmlpp::SaxParser::initialize_context ( )

overrideprotectedvirtual

Reimplemented from xmlpp::Parser.

◆ on_cdata_block()

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

protectedvirtual

◆ on_characters()

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

protectedvirtual

◆ on_comment()

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

protectedvirtual

◆ on_end_document()

virtual void xmlpp::SaxParser::on_end_document ( )

protectedvirtual

◆ on_end_element()

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

protectedvirtual

◆ on_entity_declaration()

virtual 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 void xmlpp::SaxParser::on_error ( const ustring & text )

protectedvirtual

◆ on_fatal_error()

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

protectedvirtual

Exceptions

xmlpp::parse_error

◆ on_get_entity()

virtual _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 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 void xmlpp::SaxParser::on_start_document ( )

protectedvirtual

◆ on_start_element()

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

protectedvirtual

◆ on_warning()

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

protectedvirtual

◆ parse_chunk()

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()

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()

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()

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()

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()

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()

void xmlpp::SaxParser::release_underlying ( )

overrideprotectedvirtual

Reimplemented from xmlpp::Parser.

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ AttributeList

Constructor & Destructor Documentation

◆ SaxParser()

◆ ~SaxParser()

Member Function Documentation

◆ finish_chunk_parsing()

◆ initialize_context()

◆ on_cdata_block()

◆ on_characters()

◆ on_comment()

◆ on_end_document()

◆ on_end_element()

◆ on_entity_declaration()

◆ on_error()

◆ on_fatal_error()

◆ on_get_entity()

◆ on_internal_subset()

◆ on_start_document()

◆ on_start_element()

◆ on_warning()

◆ parse_chunk()

◆ parse_chunk_raw()

◆ parse_file()

◆ parse_memory()

◆ parse_memory_raw()

◆ parse_stream()

◆ release_underlying()