XMLIO.hh

#ifndef __BIAS_XMLIO_hh__
#define __BIAS_XMLIO_hh__

/*
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009    (see file CONTACT for details)
  Multimediale Systeme der Informationsverarbeitung
  Institut fuer Informatik
  Christian-Albrechts-Universitaet Kiel


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

BIAS 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 Lesser General Public License for more details.

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

#include <bias_config.h>

// for dependant code:
#ifndef BIAS_HAVE_XML2
#  error BIAS_HAVE_XML2 required to use XMLIO.hh. Please recompile BIAS with USE_XML2 or dont include this file.
#endif

#ifdef BIAS_HAVE_XML2

//forward declarations for avoiding xml-headers
typedef struct _xmlAttr xmlAttr;
typedef xmlAttr *xmlAttrPtr;
typedef struct _xmlNode xmlNode;
typedef xmlNode* xmlNodePtr;
typedef struct _xmlDoc xmlDoc;
typedef xmlDoc* xmlDocPtr;

#include <vector>
#include <Base/Debug/Error.hh>
#include <Base/Debug/Debug.hh>

namespace BIAS {

  /** @class XMLIO
      @ingroup g_utils
      @brief Wrapper class for reading and writing XML files based on the
             XML library libxml2

      @author streckel 05/2004

      Implements a tree-oriented reader and writer for XML files

      the naming convention for this class is:
      <rootNode>
        <childNodeName AttributeName="AttributeValue">
          Content of childNodeName
        </childNodeName>
      </rootNode>

      The class first creates a tree in memory, this tree is written to
      a file in one flush using write().
      A new tree is created with create().
      A tree is read from file and parsed with read().
  */
  class BIASCommon_EXPORT XMLIO : public Debug {

  public:
    XMLIO();
    ~XMLIO();

    void clear();

    // ****************************************************************
    // * Static conversion methods between character encoding formats
    // ****************************************************************

    /** @brief Convert character string from UTF-8 format to ISO 8895-1.
        @returns 0 in case of success, -1 if conversion failed
        @author esquivel
        @date 08/2008 */
    static int IsoLatin1ToUtf8(const std::string& isoLatin1, std::string& utf8);

    /** @brief Convert character string from ISO 8895-1 format to UTF-8.
        @returns 0 in case of success, -1 if conversion failed
        @author esquivel
        @date 08/2008 */
    static int Utf8ToIsoLatin1(const std::string& utf8, std::string& isoLatin1);

    // ****************************************************************
    // * Write methods
    // ****************************************************************

    /** @brief Create the base of a new XML-Tree in memory, already with a
        one and only root node.
        @author streckel 05/2004 */
    xmlNodePtr create(const std::string& RootNodeName);

    /** @brief Add a child node to an incoming node with the given name.
        @author streckel 05/2004 */
    xmlNodePtr addChildNode(const xmlNodePtr ParentNode,
                            const std::string& NewNodeName);

    /** @brief Add an attribute to a node.
        @author apetersen 07/2005 */
    void addAttribute(const xmlNodePtr Node,
                      const std::string& AttributeName,
                      bool AttributeValue);
    /** @brief Add an attribute to a node.
        @author streckel 05/2004 */
    void addAttribute(const xmlNodePtr Node,
                      const std::string& AttributeName,
                      const std::string& AttributeValue);
    /** @brief Add an attribute to a node.
        */
    void addAttribute(const xmlNodePtr Node,
                      const std::string& AttributeName,
                      const char* AttributeValue);

    /** @brief Add an attribute to a node.
        @author streckel 05/2004 */
    void addAttribute(const xmlNodePtr Node,
                      const std::string& AttributeName,
                      int AttributeValue);
    /** @brief Add an attribute to a node.
        @author streckel 05/2004 */
    void addAttribute(const xmlNodePtr Node,
                      const std::string& AttributeName,
                      double AttributeValue);
    /** @brief Add an attribute to a node.
        @author apetersen 07/2005 */
    void addAttribute(const xmlNodePtr Node,
                      const std::string& AttributeName,
                      const std::vector<double> &AttributeValue);
    /** @brief Add an attribute to a node.
        @author apetersen 07/2005 */
    void addAttribute(const xmlNodePtr Node,
                      const std::string& AttributeName,
                      const std::vector<int> &AttributeValue);
    /** @brief Add content to a node.
        @author streckel 05/2004 */
    void addContent(const xmlNodePtr Node, const std::string& Content);
    void addContent(const xmlNodePtr Node, const int Content);
    void addContent(const xmlNodePtr Node, const double Content);
    void addContent(const xmlNodePtr Node, const std::vector<int> Content);

    /** @brief Add comment to a node.
        @author streckel 05/2004 */
    void addComment(const xmlNodePtr Node, const std::string& Comment);

    /** @brief Set content of a node.
        Method will replace existent content.
        @author bartczak 08/2004 */
    void setContent(const xmlNodePtr Node, const std::string& Content);
    void setContent(const xmlNodePtr Node, const int Content);
    void setContent(const xmlNodePtr Node, const double Content);
    void setContent(const xmlNodePtr Node, const std::vector<int> Content);

    /** @brief Write the whole tree that was constructed in memory to disk.
        @param AutoAddCompressionSuffix relevant only if compression is active
        true means .z is attached, false means filename is used as is
        @author streckel 05/2004 */
    int write(const std::string& Filename,
              bool AutoAddCompressionSuffix = true) const;

    // ****************************************************************
    // * Read & analysis methods
    // ****************************************************************

    /** @brief Read and parse an XML file from disk, DtD validation is not
        yet implemented. Returns pointer to the RootNode or NULL if parse
        errors occurred.
        @author streckel 05/2004 */
    xmlNodePtr read(const std::string& Filename);

    /** @brief Get the first child of a given parent, or NULL for no childs.
        @author streckel 05/2004 */
    xmlNodePtr getFirstChild(const xmlNodePtr ParentNode);

    /** @brief Get the next child of the parent specified in the last
        getFirstChild() call, the class remembers the last returned child.
        NULL is returned the last child was reached.
        @author streckel 05/2004 */
    xmlNodePtr getNextChild();

    /** @brief Get the next sibling of the given node. Do not give the
        parent node but the previous sibling node.
        @author streckel 05/2004 */
    xmlNodePtr getNextChild(const xmlNodePtr SiblingNode);

    /** @brief Get a child of a Parent node by specifying the childs name,
        NULL is returned if the ParentNode has no child of the given name.
        @author streckel 05/2004 */
    xmlNodePtr getChild(const xmlNodePtr ParentNode,
                        const std::string& ChildName);

    /** Convenience wrapper: returns a vector of pointors to every (direct) child with the specified name.
    & \author bartczak 03/2009
    **/
    void GetChildren(const xmlNodePtr ParentNode,
      const std::string& ChildName,
      std::vector<xmlNodePtr>& childrenWithSameName);

    /** Finds the 'first' child with name ChildName and an attribute named AttributeName that
    * has the string value AttributeValue, return NULL if unsuccessful.
    * \author bartczak 03/2009
    */
    xmlNodePtr GetChildWithAttributeValueString(const xmlNodePtr ParentNode,
                                                  const std::string& ChildName,
                                                  const std::string& AttributeName,
                                                  const std::string& AttributeValue);

    /** @brief Get the name of a given Node.
        @author streckel 05/2004 */
    std::string getNodeName(const xmlNodePtr Node) const;

    /** @brief accesor functions for recursive usage
        @author woelk 02/2006 */
    void GetChildren(const xmlNodePtr ParentNode,
                     std::vector<xmlNodePtr>& children);

    /** @brief Get the content of a given Node.
        @author streckel 05/2004 */
    std::string getNodeContentString(const xmlNodePtr Node) const;
    int getNodeContentInt(const xmlNodePtr Node) const;
    double getNodeContentDouble(const xmlNodePtr Node) const;
    std::vector<int> getNodeContentVectorInt(const xmlNodePtr Node) const;
    std::vector<double> getNodeContentVectorDouble(const xmlNodePtr Node) const;

    /** @brief Get the first attribute of a given parent, or NULL for no
        attributes.
        @author streckel 05/2004 */
    xmlAttrPtr getFirstAttribute(const xmlNodePtr Node);

    /** @brief Get the next attribute of the parent specified in the last
        getFirstAttribute() call, the class remembers the last returned
        attribute. NULL iis returned if the last attribute was reached.
        @author streckel 05/2004 */
    xmlAttrPtr getNextAttribute();

    /** @brief accesor functions for recursive usage
        @author woelk 02/2006 */
    void GetAttributes(const xmlNodePtr Node,
                       std::vector<xmlAttrPtr>& attributes);

    /** @brief Get the name of a given Attribute.
        @author streckel 05/2004 */
    std::string getAttributeName(const xmlAttrPtr Attribute) const;

    /** @brief search for a specific attribute
        @return NULL if not found
        @author woelk 02/2006 */
    xmlAttrPtr getAttributeByName(const xmlNodePtr Node,
                                  const std::string& attribute_name);

    /** @brief Get the value of a given Attribute, with type-cast overloads
        for different attribute types. Use getAttributeValueString() for
        unknown attribute types.
        @author streckel 05/2004 & apetersen 07/2005 */
    bool getAttributeValueBool(const xmlAttrPtr Attribute) const;
    std::string getAttributeValueString(const xmlAttrPtr Attribute) const;
    int getAttributeValueInt(const xmlAttrPtr Attribute) const;
    double getAttributeValueDouble(const xmlAttrPtr Attribute) const;
    std::vector<double> getAttributeValueVecDbl(const xmlAttrPtr Attribute) const;
    std::vector<int> getAttributeValueVecInt(const xmlAttrPtr Attribute) const;

    /** @brief Get the value of an Attribute stecified by the attributes
        name, with type-cast overloads for different attribute types.
        Use getAttributeValueString() for unknown attribute types.
        @author streckel 05/2004 & apetersen 07/2005 */
    bool getAttributeValueBool(const xmlNodePtr Node,
                                   const std::string& AttributeName) const;
    std::string getAttributeValueString(const xmlNodePtr Node,
                                   const std::string& AttributeName) const;
    int getAttributeValueInt(const xmlNodePtr Node,
                             const std::string& AttributeName) const;
    double getAttributeValueDouble(const xmlNodePtr Node,
                                   const std::string& AttributeName) const;
    std::vector<double> getAttributeValueVecDbl(const xmlNodePtr Node,
                                   const std::string& AttributeName) const;
    std::vector<int> getAttributeValueVecInt(const xmlNodePtr Node,
    const std::string& AttributeName) const;

    /** @brief set level of compression, needs zlib
        @param level 0=compression off, ... , 9 means highest
        @return previous compression level
        @author koeser 01/2005 */
    int SetCompression(int level=9);

    /** serialize tree to string
        @author evers
    */
    int WriteToString(std::string &str);

    /** construct tree from string
        @author evers
    */
    xmlNodePtr ReadFromString(const std::string &str);

    xmlNodePtr getRootNode() { return RootNode_;}

    void SetEncoding(const std::string &encoding) {
      Encoding_ = encoding;}

    std::string GetEncoding(){return Encoding_;}

  protected:

    xmlDocPtr xmlDoc_;

    xmlNodePtr RootNode_;
    xmlNodePtr CurrNode_;

    xmlAttrPtr CurrAttr_;

    bool isInitialized_;
    std::string Encoding_;

  };


} // namespace

#endif // BIAS_HAVE_XML2

#endif // __BIAS_XMLIO_hh__