/***************************************************************************
                          SIMPLY POWERFUL TOOLKIT (SPTK)
                          CXmlHandler.h  -  description
                             -------------------
    begin                : Sun May 22 2003
    based on the code    : Mikko Lahteenmaki <Laza@Flashmail.com>
    copyright            : (C) 2003-2005 by Alexey S.Parshin
    email                : alexeyp@gmail.com
 ***************************************************************************/

/***************************************************************************
   This library is free software; you can redistribute it and/or modify it 
   under the terms of the GNU Library General Public License as published by
   the Free Software Foundation; either version 2 of the License, or (at 
   your option) any later version.

   This library is distributed in the hope that it will be useful, but 
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library
   General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; if not, write to the Free Software Foundation, 
   Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

   Please report all bugs and problems to "alexeyp@gmail.com"
 ***************************************************************************/

#ifndef __CXMLHANDLER_H__
#define __CXMLHANDLER_H__

#include <sptk3/xml/CXmlDoc.h>
#include <string>

/// @addtogroup XML
/// @{ 

/// @brief XML parser event handler (SAX).
///
/// Re-implement this class and set to
/// context event handler before loading file
class CXmlHandler {
public:
   /// Constructor
   CXmlHandler() { }

   /// Destructor
   virtual ~CXmlHandler() { }

   /// The reader calls this function before it starts parsing the document. 
   /// The argument locator is a pointer to a CXmlLocator which allows the application 
   /// to get the parsing position within the document. 
   virtual void setLocator(CXmlLocator **locator) { }

   /// The reader calls this function when it starts parsing the document. 
   /// The reader calls this function only once.
   virtual void startDocument() { }

   /// The reader calls this function after it has finished parsing. 
   /// It is called only once, and is the last handler function called. 
   /// It is called after the reader has read all input. 
   virtual void endDocument() { }

   /// The reader calls this function when it has parsed a processing instruction. 
   /// @param target const std::string &, the target name of the processing instruction.
   /// @param data const std::string &, the data in the processing instruction. 
   virtual void processingInstruction(const std::string &target, const std::string &data) { }

   /// The reader calls this function when it has parsed a start element tag.
   /// There is a corresponding end_node() call when the corresponding end element tag is read. 
   /// start_node() and end_node() calls are always nested correctly. 
   /// Empty element tags (e.g. <mytag/>) cause a start_node() call immediately followed by an end_node() call. 
   /// @param name const std::string &, name of parsed start tag
   /// @param attrs const CXmlAttributes &, attribute list that contains attributes of node.
   virtual void startNode(const std::string &name, const CXmlAttributes &attrs) { }

   /// The reader calls this function when it has parsed an end element tag.
   /// @param name const std::string &, name of parsed end tag.
   virtual void endNode(const std::string &name) { }

   /// The reader calls this function, when it has parsed a character data.
   /// Entities are converted to their actual values before calling this.
   /// @param cdata const std::string &, parsed character data
   virtual void cdata(const std::string &cdata) { }

   /// The parser calls this function, when it has parsed comment
   /// @param comment const std::string &, content of comment
   virtual void comment(const std::string &comment) { }

   /// Returns document type for parsed document. 
   /// Entities are stored here.
   CXmlDocType &docType() { return m_doctype; }

private:
   CXmlDocType m_doctype;  ///< Document type
};

/// @}

#endif
