xmlwrapp
Public Types | Public Member Functions | Protected Member Functions
xml::event_parser Class Reference

The xml::event_parser is used to parse an XML document by calling member functions when certain things in the XML document are parsed. More...

#include <event_parser.h>

List of all members.

Public Types

typedef std::map< std::string,
std::string > 
attrs_type
 a type for holding XML node attributes
typedef std::size_t size_type
 size type

Public Member Functions

 event_parser ()
 Default constructor.
bool parse_file (const char *filename)
 Call this member function to parse the given file.
bool parse_stream (std::istream &stream)
 Parse what ever data that can be read from the given stream.
bool parse_chunk (const char *chunk, size_type length)
 Call this function to parse a chunk of xml data.
bool parse_finish ()
 Finish parsing chunked data.
const std::string & get_error_message () const
 If there was an error parsing the XML data, (indicated by one of the parsing functions returning false), you can call this function to get a message describing the error.

Protected Member Functions

virtual bool start_element (const std::string &name, const attrs_type &attrs)=0
 Override this member function to receive the start_element message.
virtual bool end_element (const std::string &name)=0
 Override this member function to receive the end_element message.
virtual bool text (const std::string &contents)=0
 Override this member function to receive the text message.
virtual bool cdata (const std::string &contents)
 Override this member function to receive the cdata mesage.
virtual bool processing_instruction (const std::string &target, const std::string &data)
 Override this member function to receive the procesing_instruction message.
virtual bool comment (const std::string &contents)
 Override this member function to receive the comment message.
virtual bool warning (const std::string &message)
 Override this memeber function to receive parser warnings.
void set_error_message (const char *message)
 Set the error message that will be returned from the get_error_message() member function.

Detailed Description

The xml::event_parser is used to parse an XML document by calling member functions when certain things in the XML document are parsed.

In order to use this class you derive a sub-class from it and override the protected virtual functions.


Member Typedef Documentation

typedef std::map<std::string, std::string> xml::event_parser::attrs_type

a type for holding XML node attributes

typedef std::size_t xml::event_parser::size_type

size type


Constructor & Destructor Documentation

Default constructor.


Member Function Documentation

virtual bool xml::event_parser::cdata ( const std::string &  contents) [protected, virtual]

Override this member function to receive the cdata mesage.

This member function is called when the parser encounters a <![CDATA[]]> section in the XML data.

The default implementation just calls the text() member function to handle the text inside the CDATA section.

Parameters:
contentsThe contents of the CDATA section.
Returns:
You should return true to continue parsing.
Return false if you want to stop.
virtual bool xml::event_parser::comment ( const std::string &  contents) [protected, virtual]

Override this member function to receive the comment message.

This member function will be called when the XML parser encounters a comment .

The default implementation will ignore XML comments and return true.

Parameters:
contentsThe contents of the XML comment.
Returns:
You should return true to continue parsing.
Return false if you want to stop.
virtual bool xml::event_parser::end_element ( const std::string &  name) [protected, pure virtual]

Override this member function to receive the end_element message.

This member function is called when the parser encounters the closing of an element.

Parameters:
nameThe name of the element that was closed.
Returns:
You should return true to continue parsing; false to stop.
const std::string& xml::event_parser::get_error_message ( ) const

If there was an error parsing the XML data, (indicated by one of the parsing functions returning false), you can call this function to get a message describing the error.

Returns:
A description of the XML parsing error.
bool xml::event_parser::parse_chunk ( const char *  chunk,
size_type  length 
)

Call this function to parse a chunk of xml data.

When you are done feeding the parser chucks of data you need to call the parse_finish member function.

Parameters:
chunkThe xml data chuck to parse.
lengthThe size of the given data chunk
Returns:
True if the chunk was parsed sucessfully; false otherwise.
bool xml::event_parser::parse_file ( const char *  filename)

Call this member function to parse the given file.

Parameters:
filenameThe name of the file to parse.
Returns:
True if the file was successfully parsed; false otherwise.

Finish parsing chunked data.

You only need to call this member function is you were parsing chunked xml data via the parse_chunk member function.

Returns:
True if all parsing was successful; false otherwise.
bool xml::event_parser::parse_stream ( std::istream &  stream)

Parse what ever data that can be read from the given stream.

Parameters:
streamThe stream to read data from.
Returns:
True if the stream was successfully parsed; false otherwise.
virtual bool xml::event_parser::processing_instruction ( const std::string &  target,
const std::string &  data 
) [protected, virtual]

Override this member function to receive the procesing_instruction message.

This member function will be called when the XML parser encounters a processing instruction <?target data?>.

The default implementation will ignore processing instructions and return true.

Parameters:
targetThe target of the processing instruction
dataThe data of the processing instruction.
Returns:
You should return true to continue parsing.
Return false if you want to stop.
void xml::event_parser::set_error_message ( const char *  message) [protected]

Set the error message that will be returned from the get_error_message() member function.

If one of your callback functions returns false and does not first call this memeber function, "Unknown Error" will be returned from get_error_message().

Parameters:
messageThe message to return from get_error_message().
virtual bool xml::event_parser::start_element ( const std::string &  name,
const attrs_type attrs 
) [protected, pure virtual]

Override this member function to receive the start_element message.

This member function is called when the parser encounters an xml element.

Parameters:
nameThe name of the element
attrsThe element's attributes
Returns:
You should return true to continue parsing; false to stop.
virtual bool xml::event_parser::text ( const std::string &  contents) [protected, pure virtual]

Override this member function to receive the text message.

This member function is called when the parser encounters text nodes.

Parameters:
contentsThe contents of the text node.
Returns:
You should return true to continue parsing; false to stop.
virtual bool xml::event_parser::warning ( const std::string &  message) [protected, virtual]

Override this memeber function to receive parser warnings.

The default behaviour is to ignore warnings.

Parameters:
messageThe warning message from the compiler.
Returns:
You should return true to continue parsing.
Return false if you want to stop.

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