xmlparser.h

简单的xml解析类

//************************************************************************************************************************** 
//* Blue Xml Extension
//* Copyright (c) 2002-2004 Josh Harler
//* 
//* Blue - General Purpose C++ Library
//* Copyright (c) 2002-2004 Josh Harler
//* 
//* This software is provided 'as-is', without any express or implied warranty. In no event
//* will the authors be held liable for any damages arising from the use of this software.
//* 
//* Permission is granted to anyone to use this software for any purpose, including commercial
//* applications, and to alter it and redistribute it freely, subject to the following restrictions:
//* 
//* 	1. The origin of this software must not be misrepresented; you must not claim that you
//* 	wrote the original software. If you use this software in a product, an acknowledgment in the
//* 	product documentation would be appreciated but is not required.
//* 
//* 	2. Altered source versions must be plainly marked as such, and must not be misrepresented as
//* 	being the original software.
//* 
//* 	3. This notice may not be removed or altered from any source distribution.
//*
//*
//* file   Blue/Extension/Xml/XmlParser.h
//**

#ifndef __blue_ext_xml_XmlParser_h_included__
#define __blue_ext_xml_XmlParser_h_included__

// Public Headers ==========================================================================================================

// Extension headers
#include "Blue/Extension/Xml/Xml.h"

// Blue library headers
#include "Blue/Data/InputStream.h"


// Public Defines/Enums/Typedefs/Etc. ======================================================================================

namespace blue {
namespace ext {
namespace xml {

	// Forward declaration of internal class
	class Tokenizer;

}}}

// Public Classes/Structs ==================================================================================================

namespace blue {
namespace ext {
namespace xml {

	/**
	 * \class XmlParser
	 * \brief Base class for Xml parsers.
	 * \ingroup Xml
	 */
	class BLUE_EXPORT_XML XmlParser
	{
	public:

		// ===========================================================
		//  creation/destruction
		// ===========================================================

		/** Destructor. */
		virtual ~XmlParser();


		// ===========================================================
		//  query
		// ===========================================================

		/** Gets the input stream being used by this parser. */
		const data::InputStream* getInputStream() const;

		/**
		 * Takes the given text and replaces all entity references
		 * found with their corresponding values.
		 */
		String decodeText( String text ) const;

		/**
		 * Returns an array containing the entities being searched
		 * for by this parser.
		 */
		Array<String> getEntities() const;

		/**
		 * Gets the value of the given entity.  The entity name
		 * should not contain an ampersand or a semicolon.
		 */
		String getEntityValue( String entity );


		// ===========================================================
		//  manipulation
		// ===========================================================

		/** Sets the input stream for this parser to use. */
		void setInputStream( data::InputStream* input );

		/**
		 * Adds an entity value to use with the document.
		 * Entities are the tokens in Xml text that begin with an
		 * ampersand (&) and ends with a semicolon (;).  These are
		 * typically used to represent characters that cannot legally
		 * exist in an Xml string (such as '<', '>', and '&'), but can
		 * be used to represent any sort of variable value.
		 *
		 * The entity name passed in should not contain the ampersand
		 * or the semicolon.
		 */
		void addEntity( String entity, String value );

		/** Removes an entity from use with the document. */
		void removeEntity( String entity );

		/** Parses the Xml. */
		void parse();

		/**
		 * Resets the state of the Xml parser.  Any information received
		 * from the parser concerning the previous Xml document should be
		 * discarded and considered invalid.
		 */
		void reset();

  protected:
		/** Constructor. */
		XmlParser();
		/** Constructor. */
		XmlParser( data::InputStream* input );

		
		/**
		 * Called when the state of the Xml parser is being reset.  Any
		 * information about the previous parsed Xml should be discarded.
		 */
		virtual void xmlReset();

		/** Called when the Xml document begins. */
		virtual void xmlDocumentBegin();
		/** Called when the Xml document comes to an end. */
		virtual void xmlDocumentEnd();

		/** Called when a processing instruction begins. */
		virtual void xmlProcInstBegin( String instruction );
		/** Called when a processing instruction attribute is encountered. */
		virtual void xmlProcInstAttribute( String name, String value );
		/** Called when a processing instruction ends. */
		virtual void xmlProcInstEnd( String instruction );

		/** Called when an element begins. */
		virtual void xmlElementBegin( String element );
		/** Called when an element attribute is encountered. */
		virtual void xmlElementAttribute( String name, String value );
		/** Called when an element's text is encountered. */
		virtual void xmlElementText( String text );
		/** Called when an element's text is encountered via a CDATA tag. */
		virtual void xmlElementCData( String cdata );
		/** Called when an element ends. */
		virtual void xmlElementEnd( String element );

		/** Called when a comment is encountered. */
		virtual void xmlComment( String comment );


	private:
		/**
		 * Copy constructor. Private because XmlParsers should not be
		 * manipulated by more than one instance.
		 */
		XmlParser( const XmlParser& );
		/** Private assignment operator. See copy constructor documentation. */
		const XmlParser& operator=( const XmlParser& );


		void init();

		bool readGeneral( Tokenizer& tokenizer );
		void readElement( Tokenizer& tokenizer, String elementToken );
		void readExclamation( Tokenizer& tokenizer );
		void readProcInst( Tokenizer& tokenizer );
		
		Array<String> parseAttributes( String list );

		void processInstruction( String instruction, Array<String> attributes );

		void elementPush( String& name );
		void elementPop();

		data::InputStream* m_input;
		Array<String>      m_elemNames;
		int                m_elemIdx;

		struct entity_item
		{
			String m_entity;
			String m_value;
		};

		Array<entity_item> m_entities;
	};


	/**
	 * \class XmlSyntaxException
	 * \brief Thrown when a syntax error is encountered in the Xml document.
	 * \ingroup XmlExceptions
	 */
	class BLUE_EXPORT_XML XmlSyntaxException :public XmlException
	{
	public:
		XmlSyntaxException( String desc )
			:XmlException(desc) {}

		virtual String getException() const {
			return (String("XmlSyntaxException", String::STATIC));
		}
	};

}}}	// namespaces


// Public External Variables ===============================================================================================

// Public Function Prototypes ==============================================================================================

// Public Inline Functions =================================================================================================

#endif // include guard