Base class for XML document parsers. More...

#include <XmlParser.h>

Collaboration diagram for Hypertable::XmlParser:

Public Member Functions
	XmlParser (const char *base, int len)
	Constructor. More...

	XmlParser (const char *base, int len, const std::initializer_list< std::string > &sub_parsers)
	Constructor with sub-parser list. More...

virtual	~XmlParser ()
	Destructor. More...

void	parse ()

virtual void	start_element (const XML_Char name, const XML_Char *atts)
	Start element callback member function. More...

virtual void	end_element (const XML_Char *name, const std::string &content)
	End element callback member function. More...

virtual void	sub_parse (const XML_Char name, const char base, int len)
	Performs a sub-parse. More...

Static Public Member Functions
static int64_t	content_to_i64 (const std::string &name, const std::string &content)
	Helper function to convert content to an int64_t value. More...

static int32_t	content_to_i32 (const std::string &name, const std::string &content)
	Helper function to convert content to an int32_t value. More...

static int16_t	content_to_i16 (const std::string &name, const std::string &content)
	Helper function to convert content to an int16_t value. More...

static bool	content_to_bool (const std::string &name, const std::string &content)
	Helper function to convert content to a boolean value. More...

static const std::string	content_to_text (const std::string &name, const std::string &content, const std::initializer_list< std::string > &valid)
	Helper function to convert content to one of a set of valid text values. More...

Protected Attributes
XML_Parser	m_parser
	eXpat parser More...

const char *	m_base
	Pointer to buffer holding content to be parsed. More...

int	m_length
	Length of data at m_base to be parsed. More...

std::stack< std::string >	m_element_stack
	Element stack. More...

Private Member Functions
bool	open_element (const XML_Char *name)
	Determines if element should be parsed or included in a sub parse. More...

bool	close_element (const XML_Char *name)
	Checks for and performs sub parse. More...

void	add_text (const XML_Char *s, int len)
	Collects text. More...

void	push_element (const XML_Char *name)
	Push element onto element stack. More...

void	pop_element ()
	Pops element from element stack. More...

const std::string	collected_text ()
	Returns collected text. More...

Static Private Member Functions
static void	start_element_handler (void userdata, const XML_Char name, const XML_Char **atts)
	eXpat start element handler. More...

static void	end_element_handler (void userdata, const XML_Char name)
	eXpat end element handler. More...

static void	character_data_handler (void userdata, const XML_Char s, int len)
	eXpat character data handler add_text() is called to add `len` characters starting at `s` to collected text. More...

Private Attributes
std::string	m_collected_text
	Collected element text. More...

std::vector< std::string >	m_sub_parsers
	List of element names for which there is a sub-parser. More...

std::string	m_current_element
	Current element being parsed. More...

int	m_sub_parse_toplevel
	Toplevel element of current sub parse. More...

int	m_sub_parse_base_offset {}
	Raw text offset (from m_base) of beginning of sub parse. More...

Detailed Description

Base class for XML document parsers.

This class is a base class from which can be derived simple parsers for XML documents. It contains virtual methods to handle start and end element processing and also supports sub-parsing where the raw input text of certain elements is collected and passed into the virtual method sub_parse() for external parsing. The following pseudo-code example illustrates how to use this class to create a simple XML parser.

class XmlParserExample : public XmlParser {
public:
  XmlParserExample(MyClass *obj, const char *s, int len) :
    XmlParser(s,len,{"SubParseElement"}), m_object(obj) {}
   void start_element(const XML_Char *name, const XML_Char **atts) override {
     if (m_element_stack.empty()) { // implies toplevel
       for (int i=0; atts[i] != 0; i+=2) {
         if (!strcasecmp(atts[i], "version"))
           m_object->set_version(content_to_i32(atts[i], atts[i+1]));
         else
           /* throw exception ... */;
       }
    }
    else if (strcasecmp(name, "Generation"))
      /* throw exception ... */;
   }
   void end_element(const XML_Char *name, const string &content) override {
     if (!strcasecmp(name, "Generation"))
       m_object->set_generation(content_to_i64(name, content));
     else if (!m_element_stack.empty())
      /* throw exception ... */;
   }
   void sub_parse(const XML_Char *name, const char *s, int len) override {
     if (!strcasecmp(name, "SubParseElement")) {
       OtherClass *foo = external_parse_foo(s, len);
       m_object->set_foo(foo);
     }
  }
 private:
   MyClass *m_object;
};

Definition at line 94 of file XmlParser.h.

Constructor & Destructor Documentation

XmlParser::XmlParser	(	const char *	base,
		int	len
	)

Constructor.

Initializes member variables m_base and m_length to base and len, respectively. Initializes eXpat parser (m_parser), setting the element handlers to start_element_handler() and end_element_handler(), the character data handler to character_data_handler(), and the user data to this.

Parameters

base	Pointer to beginning of XML document
len	Length of XML document

Definition at line 43 of file XmlParser.cc.

XmlParser::XmlParser	(	const char *	base,
		int	len,
		const std::initializer_list< std::string > &	sub_parsers
	)

Constructor with sub-parser list.

Delegates construction to XmlParser() and initializes m_sub_parsers to sub_parsers.

Parameters

base	Pointer to beginning of XML document
len	Length of XML document
sub_parsers	List of element names for which sub parsers exist

Definition at line 50 of file XmlParser.cc.

XmlParser::~XmlParser ( )

virtual

Destructor.

Frees m_parser.

Definition at line 57 of file XmlParser.cc.

Member Function Documentation

void XmlParser::add_text	(	const XML_Char *	s,
		int	len
	)

private

Collects text.

Adds len characters of text from s to m_collected_text.

Parameters

s	Pointer to buffer of characters of text to collect
len	Number of characters to collect

Definition at line 190 of file XmlParser.cc.

void XmlParser::character_data_handler	(	void *	userdata,
		const XML_Char *	s,
		int	len
	)

staticprivate

eXpat character data handler add_text() is called to add len characters starting at s to collected text.

Parameters

userdata	Pointer to parser
s	Pointer to character buffer
len	Length of character buffer

Definition at line 227 of file XmlParser.cc.

bool XmlParser::close_element ( const XML_Char * name )

private

Checks for and performs sub parse.

If m_sub_parse_toplevel >= 0 and we've arrived back to the sub parse toplevel (e.g. m_sub_parse_toplevel == element stack size), then sub_parse() is called to parse the collected text with a different (sub) parser.

Parameters

name	Element name

Returns: true if the element should be parsed or skipped because it is part of a sub parse.

Exceptions

Exception with code set to Error::SCHEMA_PARSE_ERROR if closing tag is not well formed.

Definition at line 169 of file XmlParser.cc.

const std::string Hypertable::XmlParser::collected_text ( )

inlineprivate

Returns collected text.

Returns m_collected_text.

Returns: Collected text.

Definition at line 269 of file XmlParser.h.

bool XmlParser::content_to_bool	(	const std::string &	name,
		const std::string &	content
	)

static

Helper function to convert content to a boolean value.

This method will convert content to a boolean value by doing a case insensitive match against the strings "true" and "false". If there is a match, the corresponding boolean value is returned, otherwise an exception is thrown.

Parameters

name	Name of element or attribute from which content originated
content	Content of element or attribute

Exceptions

Exception with code set to Error::SCHEMA_PARSE_ERROR if content is empty or does not case insensitively match either "true" or "false".

Definition at line 124 of file XmlParser.cc.

int16_t XmlParser::content_to_i16	(	const std::string &	name,
		const std::string &	content
	)

static

Helper function to convert content to an int16_t value.

This method will convert content to an int16_t value.

Parameters

name	Name of element or attribute from which content originated
content	Content of element or attribute

Exceptions

Exception with code set to Error::SCHEMA_PARSE_ERROR if content is empty or does not contain an ASCII value representing a valid 16-bit integer.

Definition at line 114 of file XmlParser.cc.

int32_t XmlParser::content_to_i32	(	const std::string &	name,
		const std::string &	content
	)

static

Helper function to convert content to an int32_t value.

This method will convert content to an int32_t value.

Parameters

name	Name of element or attribute from which content originated
content	Content of element or attribute

Exceptions

Exception with code set to Error::SCHEMA_PARSE_ERROR if content is empty or does not contain an ASCII value representing a valid 32-bit integer.

Definition at line 104 of file XmlParser.cc.

int64_t XmlParser::content_to_i64	(	const std::string &	name,
		const std::string &	content
	)

static

Helper function to convert content to an int64_t value.

This method will convert content to an int64_t value.

Parameters

name	Name of element or attribute from which content originated
content	Content of element or attribute

Exceptions

Exception with code set to Error::SCHEMA_PARSE_ERROR if content is empty or does not contain an ASCII value representing a valid 64-bit integer.

Definition at line 90 of file XmlParser.cc.

const std::string XmlParser::content_to_text	(	const std::string &	name,
		const std::string &	content,
		const std::initializer_list< std::string > &	valid
	)

static

Helper function to convert content to one of a set of valid text values.

This helper function does a case insensitive match of content to each of the values in valid, returning the corresponding value from valid if a match is found. Otherwise an exception is thrown.

Parameters

name	Name of element or attribute from which content originated
content	Content of element or attribute
valid	Set of valid text values.

Exceptions

Exception with code set to Error::SCHEMA_PARSE_ERROR if content is empty or does not match one of the values in valid

Definition at line 137 of file XmlParser.cc.

virtual void Hypertable::XmlParser::end_element	(	const XML_Char *	name,
		const std::string &	content
	)

inlinevirtual

End element callback member function.

This virtual member function can be defined in concrete parser classes to handle close element parsing.

Parameters

name	Name of element
content	Text content collected between the start and end element with leading and trailing whitespace trimmed.

Definition at line 136 of file XmlParser.h.

void XmlParser::end_element_handler	(	void *	userdata,
		const XML_Char *	name
	)

staticprivate

eXpat end element handler.

pop_element() is called to pop the top element off the element stack. Then close_element() is called and if it returns false, the function returns. Otherwise, the collected text is obtained from the parser, leading and trailing whitespace are trimmed, and it's passed into end_element().

Parameters

userdata	Pointer to parser
name	Name of element

Definition at line 217 of file XmlParser.cc.

bool XmlParser::open_element ( const XML_Char * name )

private

Determines if element should be parsed or included in a sub parse.

If m_sub_parse_toplevel >= 0, then the element is pushed onto the stack with push_element() and false is returned. Otherwise, name is checked against the element names in m_sub_parsers. If there is a match, m_sub_parse_base_offset is set to the current byte index of the parse, m_sub_parse_toplevel is set to the current element stack size, the element is pushed onto the stack with push_element(), and false is returned. Otherwise, true is returned signaling that the element should be parsed by the current parser.

Parameters

name	Element name

Returns: true if the element and its attributes should be passed to start_element(), false if the element is to be skipped because it is being collected for a sub-parse

Definition at line 152 of file XmlParser.cc.

void XmlParser::parse ( )

Definition at line 61 of file XmlParser.cc.

void XmlParser::pop_element ( )

private

Pops element from element stack.

Pops top element from m_element_stack and sets m_current_element to the element on the top of the stack if it is not empty, otherwise sets it to "".

Definition at line 201 of file XmlParser.cc.

void XmlParser::push_element ( const XML_Char * name )

private

Push element onto element stack.

Pushes name onto m_element_stack, sets m_current_element to name, and clears m_collected_text.

Parameters

name	Element name

Definition at line 194 of file XmlParser.cc.

virtual void Hypertable::XmlParser::start_element	(	const XML_Char *	name,
		const XML_Char **	atts
	)

inlinevirtual

Start element callback member function.

This virtual member function can be defined in concrete parser classes to handle open element parsing.

Parameters

name	Name of element
atts	Attribute list of even length with each attribute name immediately followed by its corresponding value

Definition at line 128 of file XmlParser.h.

void XmlParser::start_element_handler	(	void *	userdata,
		const XML_Char *	name,
		const XML_Char **	atts
	)

staticprivate

eXpat start element handler.

Calls open_element() and returns immediately if it returns false. Otherwise, start_element() is called and then push_element() is called to push the element onto the element stack.

Parameters

userdata	Pointer to parser
name	Name of element
atts	Attribute list of even length with each attribute name immediately followed by its corresponding value

Definition at line 208 of file XmlParser.cc.

virtual void Hypertable::XmlParser::sub_parse	(	const XML_Char *	name,
		const char *	base,
		int	len
	)

inlinevirtual

Performs a sub-parse.

This virtual member function is meant to be used in conjunction with a set of element names passed into the constructor to be parsed with a separate parser. The parsing framework will skip the raw text associated with a sub-parse element and will pass it into this method for parsing. Concrete parser classes should define this member function and should parse the element defined by base and len using a different (sub) parser.

Parameters

name	Name of element
base	Pointer to raw element text to be parsed
len	Length of raw element text

Definition at line 149 of file XmlParser.h.

Member Data Documentation

const char* Hypertable::XmlParser::m_base

protected

Pointer to buffer holding content to be parsed.

Definition at line 209 of file XmlParser.h.

std::string Hypertable::XmlParser::m_collected_text

private

Collected element text.

Definition at line 302 of file XmlParser.h.

std::string Hypertable::XmlParser::m_current_element

private

Current element being parsed.

Definition at line 308 of file XmlParser.h.

std::stack<std::string> Hypertable::XmlParser::m_element_stack

protected

Element stack.

Definition at line 215 of file XmlParser.h.

int Hypertable::XmlParser::m_length

protected

Length of data at m_base to be parsed.

Definition at line 212 of file XmlParser.h.

XML_Parser Hypertable::XmlParser::m_parser

protected

eXpat parser

Definition at line 206 of file XmlParser.h.

int Hypertable::XmlParser::m_sub_parse_base_offset {}

private

Raw text offset (from m_base) of beginning of sub parse.

Definition at line 314 of file XmlParser.h.

int Hypertable::XmlParser::m_sub_parse_toplevel

private

Toplevel element of current sub parse.

Definition at line 311 of file XmlParser.h.

std::vector<std::string> Hypertable::XmlParser::m_sub_parsers

private

List of element names for which there is a sub-parser.

Definition at line 305 of file XmlParser.h.

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

/home/doug/src/hypertable/src/cc/Common/XmlParser.h
/home/doug/src/hypertable/src/cc/Common/XmlParser.cc

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation