xmlwriter.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/XmlWriter.h
//**

#ifndef __blue_ext_xml_XmlWriter_h_included__
#define __blue_ext_xml_XmlWriter_h_included__

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

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

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


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

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

namespace blue {
namespace ext {
namespace xml {

	/**
	 * Forward declaration.
	 */
	class DomNode;


	/**
	 * \class XmlWriter
	 * \brief Writes Xml as string data to an OutputStream.
	 * \ingroup Xml
	 *
	 * This class allows Xml to be generated easily.  The XmlWriter
	 * has functions that corrispond to all of the aspects of an
	 * Xml document.
	 *
	 * <b>Using the %XmlWriter:</b>
	 * \code
	 *   XmlWriter writer;
	 *   writer.setOutputStream(&output); // output stream reading to write
	 *
	 *   writer.startXml();
	 *   writer.beginDocument();
	 *   writer.beginElement("RootElement");
	 *		writer.beginElement("Child");
	 *          writer.addElementAttribute("attr", "value");
	 *          writer.addComment("You can add comments too!");
	 *          writer.addText("Child Data");
	 *      writer.endElement();
	 *      writer.addElement("ElementWithData", "Data");
	 *      writer.addElement("EmptyElement", String::null);
	 *      writer.beginElement("AnotherChild");
	 *          writer.addCDataText("Here is some \"CDATA\" text.");
	 *          writer.beginElement("NestedChild");
	 *          writer.endElement();
	 *      writer.endElement();
	 *   writer.endElement();
	 *   writer.endXml();
	 * \endcode
	 *
	 * The above code generates the following Xml document:
	 *
	 * \code
	 * <?xml version="1.0" encoding="utf-8"?>
	 * <RootElement>
	 *     <Child attr="value">
	 *         <!--You can add comments too!-->
	 *         Child Data
	 *     </Child>
	 *     <ElementWithData>Data</ElementWithData>
	 *     <EmptyElement/>
	 *     <AnotherChild>
	 *         <![CDATA[Here is some "CDATA" text]]>
	 *         <NestedChild/>
	 *     </AnotherChild>
	 * </RootElement>
	 * \endcode
	 */
	class BLUE_EXPORT_XML XmlWriter
	{
	public:
		/**
		 * Flags that determine how the Xml document is formatted.
		 */
		enum flags_e
		{
			NO_TABS      = (1<<0),  //!< No tabs ('\t') characters will be used
			NO_NEWLINES  = (1<<1),  //!< No newline ('\n') characters will be used
		};

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

		/** Constructor. */
		XmlWriter();

		/** Destructor. */
		~XmlWriter();


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

		/** Gets the OutputStream being used by this %XmlWriter. */
		const data::OutputStream* getOutputStream() const;

		/**
		 * Gets the flags that determine how the Xml document is formatted.
		 * \sa flags_e
		 */
		flags32_t getFormatFlags() const;


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

		/** Sets the OutputStream being used by this %XmlWriter. */
		void setOutputStream( data::OutputStream* output );

		/**
		 * Sets the flags that determine how the Xml document is formatted.
		 * \sa flags_e
		 */
		void setFormatFlags( flags32_t flags );

		/**
		 * Starts the process of writing the Xml document.  This <b>MUST</b>
		 * be called before any of the Xml writing functions.
		 */
		void startXml();
		/**
		 * Ends the process of writing the Xml document.  Once called, no
		 * further calls to any of the Xml writing functions can be made.
		 */
		void endXml();
		/** Determines if the %XmlWriter is in the state of writing Xml. */
		bool hasXmlStarted() const;

		/** Writes the xml version and encoding method to the Xml document. */
		void beginDocument();

		/**
		 * Starts a processing instruction.  Once started, the only valid
		 * functions are addProcInstAttribute() and endProcInst().
		 */
		void beginProcInst( String procinst );
		/**
		 * Adds an attribute to the previously opened processing instruction.
		 * This can only be called after a call to beginProcInst() and before
		 * a call to endProcInst().
		 */
		void addProcInstAttribute( String attribute, String value );
		/**
		 * Ends the previously opened processing instruction.  A call to this
		 * must corrispond to a previous call to beginProcInst().
		 */
		void endProcInst();

		/** Starts an element. */
		void beginElement( String element );
		/**
		 * Adds an element attribute to the currently opened element.  This can
		 * <b>ONLY</b> follow a call to beginElement().  A call made anywhere
		 * else will result in an XmlWriterException being thrown.
		 */
		void addElementAttribute( String attribute, String value );
		/** Adds text to the currently opened element. */
		void addText( String text );
		/** Adds CDATA text to the currently opened element. */
		void addCDataText( String cdata );
		/** Ends the currently opened element. */
		void endElement();
		/**
		 * Opens the element, sets the text of that element and closes the
		 * element.  Essentially, a call to this is the same as:
		 * \code
		 * writer.beginElement(element)
		 * writer.addText(text);
		 * writer.endElement();
		 * \endcode
		 * To form an empty element, simply pass <code>String::null</code> as
		 * the text value.
		 */
		void addElement( String element, String text );

		/** Adds a comment to the Xml document. */
		void addComment( String comment );

		/** 
		 * Writes the Xml document starting at the given DomNode.
		 * \sa DomParser, DomNode
		 */
		void writeDomTree( const DomNode* node );

	private:
		String encode( String text );

		void   elementCapIfNeeded();
		void   elementPush(String element);
		String elementPop();

		void write( String data );
		void writeTabs();
		void writeNewLine();

		enum state_e
		{
			WRITING_NOTHING,
			WRITING_PROCINST,
			WRITING_ELEMENT,
			WRITING_TEXT,
		};

		data::OutputStream* m_output;
		flags32_t           m_flags;
		int                 m_tabLevel;
		state_e             m_state;
		bool                m_lastNewLine;
		Array<String>       m_elementStack;
	};


	/**
	 * \class XmlWriterException
	 * \brief Thrown when an error in formatting the XML document occurs.
	 * \ingroup XmlExceptions
	 */
	class BLUE_EXPORT_XML XmlWriterException :public XmlException
	{
	public:
		XmlWriterException( String desc )
			:XmlException(desc) {}

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

}}}	// namespaces


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

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

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

#endif // include guard