/******************************************************************************

 *

 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

 *

 * Permission to use, copy, modify, and distribute this software and its

 * documentation under the terms of the GNU General Public License is hereby 

 * granted. No representations are made about the suitability of this software 

 * for any purpose. It is provided "as is" without express or implied warranty.

 * See the GNU General Public License for more details.

 *

 */

#ifndef _XMLWRITER_H

#define _XMLWRITER_H

#include <qdir.h>

#include <qfile.h>

#include <qtextstream.h>

#include <qmap.h>

#include <qdict.h>

#include <qstack.h>

typedef QMap<QString, QString> AttributeMap;

typedef QMapConstIterator<QString, QString> AttributeMapIter;

static QString XML_INDENT("\t");

static QString XML_OUTPUT_ENDL("\n");

// TODO: If the output file fails to open then write to an internal string that can be

// accessed by the caller after they call close(). This might be useful for internal

// XML snippets.

/**

Class that handles writing to an XML file. It guarentees well-formedness,

handles the encoding of PCDATA and indents the output.

Individual elements are created as objects, they are written to the file on

creation and closed when the element is destroyed.

*/

class XmlStream

{

	friend class XmlElement;

public:

	/// Create an XML stream that writes to a file with the given encoding

	XmlStream(const QString &fileName,

				const QString &aEncoding="UTF-8",

				const QString &aStandalone="no",

				const QString &doctypeStr="");

	/// Returns true of the file tha tthis stream is writing to is currently open.

	bool isOpen() const { return mIsOpen; }

	/// Write PCDATA to the output file, entities will be translated

	void characters(const QString &aText);

	void characters(char c);

	/// Write a processing instruction to the output file.

	void processingInstruction(const QString &aText);

	/// Write a comment to the output file.

	void comment(const QString &aText);

	/// Output operator overloading, these equate to calling characters()

	XmlStream& operator<<(const QCString &s);

	XmlStream& operator<<(const char *s);

	XmlStream& operator<<(char s);

	/// Write a unicode character to the stream

	XmlStream& writeUnicode(const QCString &s);

	/// Close the XML file (if open), this will flush any unclosed elements

	void close();

	/// Get the file name

	QString getFileName() const { return mFile.name(); }

	/// Suspend and resume output

	void outputSuspend();

	void outputResume();

	/// Destructor, this will call close()

	~XmlStream();

private:

	QDict<char> unicodeCharTable;

	/// Write out the start of element and register that element name on the stack

	void startElement(const QString &aElemName, const AttributeMap &aAttrs);

	/// Write out the end of element and remove that element name on the stack

	void endElement(const QString &aElemName);

	void closeElementDeclIfOpen();

	void indent(unsigned int aInitVal=0);

	inline bool isLegalXmlChar(QChar c) const;

	QString encodeText(const QString &aStr) const;

	QString encodeChar(char c) const;

	bool mustEncodeChar(char c) const;

	bool canIndent();

	void setLastIndent(bool theB);

private:

	QFile mFile;

	QTextStream *mStreamP;

	QStack<QString> mElemStack;

	QList<bool> mCanIndentList;

	bool mInElement;

	//bool mCanIndent;

	bool mIsOpen;

	bool mCanWrite;

private:

	// Private cctor and op=

	XmlStream (const XmlStream &rhs);

	XmlStream& operator=(const XmlStream &rhs);

};

/**

XmlElement

Usage example:

@code

// Start an XML file

XmlStream t(fileName);

if (!t.isOpen()) {

  err("Cannot open file %s for writing!\n", fileName.data());

  return;

}

// Create and persist a root element with no attributes

XmlElement elemRoot(t, QString("root"), AttributeMap());

// Note the use of {} that causes elem to go out of scope an thus

// its destructor will be called so closing the element

{

	// Create and persist a root element with attributes

	// First create the attributes

	AttributeMap attrs;

	attrs["attr_1"]	= "value_1";

	attrs["attr_2"]	= "value_2";

	// Create the element

	XmlElement elem(t, "Element", attrs);

	// Write some text

	t.characters("Some stuff");

	// Now elem is going out of scope

}

// Open and close and element

XmlElement(t, "OpenClose");

// Open and close and element with one attribute

XmlElement(t, "WhatsForDinner", "spam", "eggs");

// t goes out of scope and will close the file

@endcode

The result is:

@verbatim

<?xml version='1.0' encoding='UTF-8' standalone='no'?>

<root>

	<Element attr_1="value_1" attr_2="value_2">Some stuff</Element>

	<OpenClose/>

	<WhatsForDinner spam="eggs"/>

</root>

@endverbatim

*/

class XmlElement

{

public:

	/// Constructor with no attributes

	XmlElement(XmlStream &aStream, const QString &aElemName);

	/// Constructor with one attribute

	XmlElement(XmlStream &aStream, const QString &aElemName, const QString &aAttr, const QString &aAttrValue);

	/// Constructor with one attribute the values of which is a char

	XmlElement(XmlStream &aStream, const QString &aElemName, const QString &aAttr, char aAttrValue);

	/// Constructor with any number of attributes

	XmlElement(XmlStream &aStream, const QString &aElemName, AttributeMap &aAttrs);

	const QString& getElemName() const { return mElemName; }

	/// Destructor, this closes the element on the stream

	~XmlElement();

private:

	XmlStream& mStream;

	QString mElemName;

private:

	// Private cctor and op=

	XmlElement (const XmlElement &rhs);

	XmlElement& operator=(const XmlElement &rhs);

};

/*

This can be used in the case that elements need to persist over scope.

So given this kind of code:

void XmlDocVisitor::visitPre(DocHtmlDescTitle *)

{

  if (m_hide) return;

  m_t << "<varlistentry><term>";

}

void XmlDocVisitor::visitPost(DocHtmlDescTitle *) 

{

  if (m_hide) return;

  m_t << "</term></varlistentry>\n";

}

It can be replaced by this (assuming XmlDocVisitor has a member XmlElementStack m_es;):

void XmlDocVisitor::visitPre(DocHtmlDescTitle *)

{

  if (m_hide) return;

  m_es.push("varlistentry", AttributeMap());

  m_es.push("term", AttributeMap());

}

void XmlDocVisitor::visitPost(DocHtmlDescTitle *) 

{

  if (m_hide) return;

  m_es.pop();

  m_es.pop();

}

*/

class XmlElementStack

{

public:

	XmlElementStack(XmlStream &aStream);

	/// Push element with no attributes

	void push(const QString &aElemName);

	/// Constructor with one attribute

	void push(const QString &aElemName, const QString &aAttr, const QString &aAttrValue);

	/// Push element with any number of attributes

	void push(const QString &aElementName, AttributeMap &aAttrs);

	/// Method that will check the element name matches

	void pop(const QString &aElementName);

	/// Push and pop an element with no attributes

	void pushpop(const QString &aElemName);

	/// Push and pop an element with no attributes but with some content

	void pushpop(const QString &aElemName, const QString &aText);

	/// Add attribute to item currently on top of the stack

	void addAttribute(const QString &name, const QString &value);

	/// Return a reference to the top of the stack. The stack is not modified.

	const XmlElement& peek() const;

	/// Return true if the stack is empty

	bool isEmpty() const;

	void close();

	~XmlElementStack();

private:

	XmlStream& mStream;

	QStack<XmlElement> mElemStack;

private:

	// Private cctor and op=

	XmlElementStack (const XmlElementStack &rhs);

	XmlElementStack& operator=(const XmlElementStack &rhs);

	// Used by destructor

	void pop();

};

#endif // _XMLWRITER_H