libxml++  4.9.1
About: libxml++ is a C++ wrapper for the libxml XML parser library.
  Fossies Dox: libxml++-4.9.1.tar.xz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

xmlpp::SaxParser Class Reference

SAX XML parser. More...

#include <saxparser.h>

Inheritance diagram for xmlpp::SaxParser:
[legend]
Collaboration 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

 SaxParser (bool use_get_entity=false)
 
 ~SaxParser () override
 
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...
 
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 finish_chunk_parsing ()
 Finish a chunk-wise parse. More...
 
- Public Member Functions inherited from xmlpp::Parser
 Parser ()
 
 ~Parser () override
 
void set_validate (bool val=true) noexcept
 By default, the parser will not validate the XML file. More...
 
bool get_validate () const noexcept
 See set_validate(). 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...
 
bool get_substitute_entities () const noexcept
 See set_substitute_entities(). More...
 
void set_throw_messages (bool val=true) noexcept
 Set whether the parser will collect and throw error and warning messages. More...
 
bool get_throw_messages () const noexcept
 See set_throw_messages(). 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...
 
bool get_include_default_attributes () const noexcept
 See set_include_default_attributes(). More...
 
void set_parser_options (int set_options=0, int clear_options=0) noexcept
 Set and/or clear parser option flags. More...
 
void get_parser_options (int &set_options, int &clear_options) const noexcept
 See set_parser_options(). More...
 

Protected Member Functions

virtual void on_start_document ()
 
virtual void on_end_document ()
 
virtual void on_start_element (const ustring &name, const AttributeList &attributes)
 
virtual void on_end_element (const ustring &name)
 
virtual void on_characters (const ustring &characters)
 
virtual void on_comment (const ustring &text)
 
virtual void on_warning (const ustring &text)
 
virtual void on_error (const ustring &text)
 
virtual void on_fatal_error (const ustring &text)
 
virtual void on_cdata_block (const ustring &text)
 
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 _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_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...
 
void release_underlying () override
 
void initialize_context () override
 
- Protected Member Functions inherited from xmlpp::Parser
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)
 
virtual void handle_exception ()
 To be called in an exception handler. More...
 
virtual void check_for_exception ()
 
virtual void check_for_error_and_warning_messages ()
 
- Protected Member Functions inherited from xmlpp::NonCopyable
 NonCopyable () noexcept
 
virtual ~NonCopyable ()
 
 NonCopyable (const NonCopyable &)=delete
 
NonCopyableoperator= (const NonCopyable &)=delete
 
 NonCopyable (NonCopyable &&)=delete
 
NonCopyableoperator= (NonCopyable &&)=delete
 

Private Member Functions

void parse ()
 

Private Attributes

std::unique_ptr< _xmlSAXHandler > sax_handler_
 
std::unique_ptr< Documententity_resolver_doc_
 

Friends

struct SaxParserCallback
 

Additional Inherited Members

- Protected Types inherited from xmlpp::Parser
enum  MsgType { MsgType::ParserError, MsgType::ParserWarning, MsgType::ValidityError, MsgType::ValidityWarning }
 
- Static Protected Member Functions inherited from xmlpp::Parser
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 void callback_error_or_warning (MsgType msg_type, void *ctx, const char *msg, va_list var_args)
 
- Protected Attributes inherited from xmlpp::Parser
_xmlParserCtxt * context_
 
std::unique_ptr< exceptionexception_
 

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

Definition at line 34 of file saxparser.h.

Member Typedef Documentation

◆ AttributeList

Definition at line 52 of file saxparser.h.

Constructor & Destructor Documentation

◆ SaxParser()

xmlpp::SaxParser::SaxParser ( bool  use_get_entity = false)
Parameters
use_get_entitySet 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.

Definition at line 41 of file saxparser.cc.

References xmlpp::SaxParserCallback::cdata_block(), xmlpp::SaxParserCallback::characters(), xmlpp::SaxParserCallback::comment(), xmlpp::SaxParserCallback::end_document(), xmlpp::SaxParserCallback::end_element(), xmlpp::SaxParserCallback::entity_decl(), xmlpp::SaxParserCallback::error(), xmlpp::SaxParserCallback::fatal_error(), xmlpp::SaxParserCallback::get_entity(), xmlpp::SaxParserCallback::internal_subset(), sax_handler_, xmlpp::Parser::set_throw_messages(), xmlpp::SaxParserCallback::start_document(), xmlpp::SaxParserCallback::start_element(), and xmlpp::SaxParserCallback::warning().

◆ ~SaxParser()

xmlpp::SaxParser::~SaxParser ( )
override

Definition at line 84 of file saxparser.cc.

References release_underlying().

Member Function Documentation

◆ finish_chunk_parsing()

void xmlpp::SaxParser::finish_chunk_parsing ( )

◆ initialize_context()

void xmlpp::SaxParser::initialize_context ( )
overrideprotectedvirtual

Reimplemented from xmlpp::Parser.

Definition at line 370 of file saxparser.cc.

References entity_resolver_doc_, and xmlpp::Parser::initialize_context().

Referenced by finish_chunk_parsing(), parse(), parse_chunk_raw(), and parse_stream().

◆ on_cdata_block()

void xmlpp::SaxParser::on_cdata_block ( const ustring text)
protectedvirtual

Definition at line 137 of file saxparser.cc.

Referenced by xmlpp::SaxParserCallback::cdata_block().

◆ on_characters()

void xmlpp::SaxParser::on_characters ( const ustring characters)
protectedvirtual

Definition at line 115 of file saxparser.cc.

Referenced by xmlpp::SaxParserCallback::characters().

◆ on_comment()

void xmlpp::SaxParser::on_comment ( const ustring text)
protectedvirtual

Definition at line 119 of file saxparser.cc.

Referenced by xmlpp::SaxParserCallback::comment().

◆ on_end_document()

void xmlpp::SaxParser::on_end_document ( )
protectedvirtual

Definition at line 103 of file saxparser.cc.

Referenced by xmlpp::SaxParserCallback::end_document().

◆ on_end_element()

void xmlpp::SaxParser::on_end_element ( const ustring name)
protectedvirtual

Definition at line 111 of file saxparser.cc.

Referenced by xmlpp::SaxParserCallback::end_element().

◆ on_entity_declaration()

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

Definition at line 94 of file saxparser.cc.

References entity_resolver_doc_.

Referenced by xmlpp::SaxParserCallback::entity_decl().

◆ on_error()

void xmlpp::SaxParser::on_error ( const ustring text)
protectedvirtual

Definition at line 127 of file saxparser.cc.

◆ on_fatal_error()

void xmlpp::SaxParser::on_fatal_error ( const ustring text)
protectedvirtual
Exceptions
xmlpp::parse_error

Definition at line 132 of file saxparser.cc.

◆ on_get_entity()

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

Definition at line 89 of file saxparser.cc.

References entity_resolver_doc_.

Referenced by xmlpp::SaxParserCallback::get_entity().

◆ on_internal_subset()

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.

Definition at line 141 of file saxparser.cc.

References entity_resolver_doc_.

◆ on_start_document()

void xmlpp::SaxParser::on_start_document ( )
protectedvirtual

Definition at line 99 of file saxparser.cc.

Referenced by xmlpp::SaxParserCallback::start_document().

◆ on_start_element()

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

Definition at line 107 of file saxparser.cc.

Referenced by xmlpp::SaxParserCallback::start_element().

◆ on_warning()

void xmlpp::SaxParser::on_warning ( const ustring text)
protectedvirtual

Definition at line 123 of file saxparser.cc.

◆ parse()

◆ 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
chunkThe next piece of the XML document.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error

Definition at line 282 of file saxparser.cc.

References parse_chunk_raw().

◆ parse_chunk_raw()

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

Parse a chunk of data.

Since @PACKAGE_NAME@ 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
contentsThe next piece of the XML document as an array of bytes.
bytes_countThe number of bytes in the contents array.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error

Definition at line 287 of file saxparser.cc.

References xmlpp::Parser::check_for_exception(), xmlpp::Parser::context_, xmlpp::KeepBlanks::Default, xmlpp::Parser::exception_, xmlpp::format_xml_error(), xmlpp::format_xml_parser_error(), initialize_context(), and sax_handler_.

Referenced by parse_chunk().

◆ parse_file()

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

Parse an XML document from a file.

Parameters
filenameThe path to the file.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error

Implements xmlpp::Parser.

Definition at line 181 of file saxparser.cc.

References xmlpp::Parser::context_, xmlpp::KeepBlanks::Default, and parse().

◆ parse_memory()

void xmlpp::SaxParser::parse_memory ( const ustring contents)
overridevirtual

Parse an XML document from a string.

Parameters
contentsThe XML document as a string.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error

Implements xmlpp::Parser.

Definition at line 207 of file saxparser.cc.

References parse_memory_raw().

◆ 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
contentsThe XML document as an array of bytes.
bytes_countThe number of bytes in the contents array.
Exceptions
xmlpp::internal_error
xmlpp::parse_error
xmlpp::validity_error

Implements xmlpp::Parser.

Definition at line 194 of file saxparser.cc.

References xmlpp::Parser::context_, xmlpp::KeepBlanks::Default, and parse().

Referenced by parse_memory().

◆ parse_stream()

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

◆ release_underlying()

void xmlpp::SaxParser::release_underlying ( )
overrideprotectedvirtual

Reimplemented from xmlpp::Parser.

Definition at line 365 of file saxparser.cc.

References xmlpp::Parser::release_underlying().

Referenced by finish_chunk_parsing(), parse(), parse_stream(), and ~SaxParser().

Friends And Related Function Documentation

◆ SaxParserCallback

friend struct SaxParserCallback
friend

Definition at line 228 of file saxparser.h.

Member Data Documentation

◆ entity_resolver_doc_

std::unique_ptr<Document> xmlpp::SaxParser::entity_resolver_doc_
private

◆ sax_handler_

std::unique_ptr<_xmlSAXHandler> xmlpp::SaxParser::sax_handler_
private

Definition at line 222 of file saxparser.h.

Referenced by finish_chunk_parsing(), parse(), parse_chunk_raw(), parse_stream(), and SaxParser().


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