mi32/xml.h

Go to the documentation of this file.

/*****************************************************************************
 *
 * \file xml.h <mi32/xml.h>
 * \brief Class wrappers around the libxml library
 *
 * \if NODOC
 * $Log: xml.h_v $
 * Revision 1.23  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.22  2003/09/03 16:39:53  mju
 * Have GetText return bool.
 *
 * Revision 1.21  2003/08/20 19:25:48  mju
 * Add FindNext and STRUTF8 versions of GetProperty/GetText.
 * Make both GetProperty methods return true if property found.
 * Remove pointer-returning versions of GetProperty/GetText.
 *
 * Revision 1.20  2003/06/27 21:06:26  dwilliss
 * Added AddEntity methods
 *
 * Revision 1.19  2003/06/27 20:46:01  dwilliss
 * Moved to misystem.dll and exported.  Can't have inlines anymore as a
 * result
 *
 * Revision 1.15  2002/09/19 15:39:54  dwilliss
 * Changed XMLDOC's copy constructor and assignment operator to be public
 * instead of private.  They are now implemented.
 *
 * Revision 1.13  2002/08/30 16:40:03  dwilliss
 * Added private, unimplemented copy constructors and assignment operators
 * XMLDOC could theoretically be copied, but until implemented it's better to
 * not allow it than to use default assignment/copy constructor.
 *
 * Revision 1.12  2002/08/30 16:27:36  dwilliss
 * Added Unparse methods
 *
 * Revision 1.11  2002/08/23 16:09:31  dwilliss
 * Added GetElementByAttribute method
 *
 * Revision 1.10  2002/08/19 15:43:37  dwilliss
 * Added some methods to node to get property values as bool and number with
 * defaults if they aren't defined
 *
 * Revision 1.9  2002/05/07 16:23:53  dwilliss
 * Added a NewChild method that copies a node
 *
 * Revision 1.8  2002/03/22 20:23:59  dwilliss
 * Added Read/Write HTML
 *
 * Revision 1.6  2002/02/15 20:45:14  dwilliss
 * Added WriteHTML methods
 *
 * Revision 1.5  2002/02/13 23:15:58  dwilliss
 * Added Attach/Detach/Delete/Replace methods
 *
 * Revision 1.4  2001/12/20 23:47:09  dwilliss
 * Added a Parse method
 *
 * Revision 1.3  2001/12/12 20:25:16  dwilliss
 * Read/Write methods take FILEPATH now
 *
 * Revision 1.1  2001/12/07 18:51:46  dwilliss
 * Initial revision
 * \endif
 ****************************************************************************/

#ifndef INC_MI32_XML_H
#define INC_MI32_XML_H

#ifndef __XML_TREE_H__     //!< libxml's include guards, not ours
#include <libxml/tree.h>
#endif
#ifndef __XML_PARSER_H__
#include <libxml/parser.h>
#endif

#ifndef INC_MI32_FILEPATH_H
#include <mi32/filepath.h>
#endif

#ifndef INC_MI32_MISTRING_H
#include <mi32/mistring.h>
#endif

#ifndef INC_MI32_UCSTRING_H
#include <mi32/ucstring.h>
#endif

#ifndef GENERATING_DOXYGEN_OUTPUT
class STRUTF8;
#endif //!< GENERATING_DOXYGEN_OUTPUT

#ifdef MISYSTEMDLL
   #define CLASSLIBEXPORT MI_DLLCLASSEXPORT
#else
   #define CLASSLIBEXPORT MI_DLLCLASSIMPORT
#endif

#ifndef XML_CASE_SENSITIVE
#define XML_CASE_SENSITIVE true
#endif

class XMLDOC;

class XMLNAMESPACE : public _xmlNs {
   public:
      const char* GetHREF() const { return (reinterpret_cast<const char*>(this->href)); }

      //! Get the namespace prefix.  Note that NULL is a valid prefix and
      //! means the default namespace within the subtree.
      const char* GetPrefix() const { return (reinterpret_cast<const char*>(this->prefix)); }
      
      //! Return a copy of this namespace.  Caller should free it later.
      XMLNAMESPACE* Copy() { return (static_cast<XMLNAMESPACE*>(xmlCopyNamespace(this))); }

      //! Free this namespace.
      //! Should only be done if you allocated the namespace.
      //! Note, you can't use "delete" on a namespace pointer, as they're
      //! allocated by libxml using malloc()
      void Free() { xmlFreeNs(this); }

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT
      //! Private and unimplemented.  You can get pointers to these from
      //! libxml, but you cannot create or destroy them yourself
      XMLNAMESPACE();
      XMLNAMESPACE(const XMLNAMESPACE&);
      ~XMLNAMESPACE();

      friend struct _smlNs;   //!< avoids warning that destructor is private
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


//! This class is an interface-only class to allow us to treat
//! an xmlNodePtr as a (NODE*)
//! Constructor/CopyConstructor/Destructor all unimplemented
//! Memory allocation done through library calls, not new/delete
class CLASSLIBEXPORT XMLNODE : public _xmlNode {
   public:

      //! Add a comment to the end of the node
      void AddComment (
         const UNICODE*
         );
      
      //! Append to the text of a node
      void AppendText (
         const UNICODE* text
         );

      //! Attach this node to an XML document. 
      //! This node is first detached from its current location and reattached
      //! as the last node of parent. NOTE:  You cannot use this function to
      //! move a node between documents.  To do that, you must first call
      //! Copy() to make a copy of the node owned by the destination document
      //! and attach the copy.
      void Attach (
         XMLNODE* parent
         );

      //! Returns a copy of this node. 
      //! The caller must either free it or Attach it to a document
      //! If the NewDoc parameter is specified (and not NULL) the copy
      //! will be owned by that document, but is not actually in its
      //! tree anywhere.
      XMLNODE* Copy (
         bool recursive = true,
         XMLDOC* NewDoc = NULL
         ) const;

      //! Unlink a node from its parent and delete it and all its children.
      void Delete ();

      //! Remove a node from it's parent tree.  If you Detach it, you must
      //! eventually call Delete() on it or reattach it somewhere.
      //! The node is still considered part of its source document and
      //! when that document is deleted, the node's children will be too.
      void Detach();
      
      //! Find a child node of a given tag string
      XMLNODE* FindChild (
         const char* TagName           //!< Must be UTF8
         ) const;

      //! Find a child node of a given tag string and a given property
      XMLNODE* FindChild (
         const char* TagName,          //!< Must be UTF8
         const char* PropertyName,     //!< Must be UTF8
         const UNICODE* PropertyValue
         ) const;

      //! Find a child node of a given tag string and a given property
      XMLNODE* FindChild (
         const char* TagName,          //!< Must be UTF8
         const char* PropertyName,     //!< Must be UTF8
         const char* PropertyValue     //!< Must be UTF8
         ) const;

      //! Find next child, matching current or specific tag name and optional property name/value
      XMLNODE* FindNext (
         const char* TagName = 0,      //!< Tag name (UTF8), if NULL will use current node tag name
         const char* PropName = 0,     //!< Property name (UTF8), if NULL will match tag name only
         const char* PropValue = 0     //!< Property value (UTF8), if NULL will not check property value
         ) const;

      //! Finds a child node which has an attribute with the given value.
      //! This is recursive.
      XMLNODE* GetElementByAttribute (
         const char* AttributeName,
         const UNICODE* AttributeValue
         ) const;

      //! Finds a child node which has an attribute with the given value.
      //! This is recursive.
      XMLNODE* GetElementByAttribute (
         const char* AttributeName,
         const char* AttributeValue
         ) const;

      //! Return the first child of this node (NULL if no children)
      XMLNODE* GetFirstChild (
         ) const;

      //! Return the last child of this node (NULL if no children)
      XMLNODE* GetLastChild()  const;

      //! Return the parent node of this node (NULL for root node)
      XMLNODE* GetParent()  const;

      //! Return the previous sibling node (NULL if this is the first node)
      XMLNODE* GetPrevious() const;
      
      //! Get the name of this node.
      //! Note the name is actually UTF8, but 99.9% of the time is
      //! defined by some standards document that requires it to be
      //! limited to the ASCII subset
      const char* GetName() const;

      //! Return the next sibling node (NULL if this is the last node)
      XMLNODE* GetNext() const;

      //! Return the value of a property of this node as an MISTRING.
      //! Returned string is left unchanged if the property is not available
      //! @return true if property exists, false if not.
      bool GetProperty(
         const char* PropName,         //!< Property name (UTF8)
         MISTRING& str,
         bool bCaseSensitive = true
         ) const;

      //! Return the value of a property of this node as STRUTF8.
      //! Returned string is left unchanged if the property is not available
      //! @return true if property exists, false if not.
      bool GetProperty(
         const char* PropName,         //!< Property name (UTF8)
         STRUTF8& retstr,              //!< Property value returned
         bool bCaseSensitive = true
         ) const;

      //! Return the value of a boolean property of this node.
      //! Returns true if the named property is "true" or "yes", false
      //! if it's "false" or "no", and the default if unspecified or
      //! none of the above
      bool GetPropertyBool (
         const char* PropName,         //!< Property name (UTF8)
         bool dft = false,
         bool bCaseSensitive = true
         ) const;

      //! Return the value of a numeric property of this node.
      double GetPropertyNum (
         const char* PropName,         //!< Property name (UTF8)
         double dft = 0.0,
         bool bCaseSensitive = true
         ) const;

      //! Get node text as MISTRING.
      //! @return true if text non-empty, false if not.
      bool GetText (
         MISTRING& str
         ) const;

      //! Get node text as STRUTF8.
      //! @return true if text non-empty, false if not.
      bool GetText (
         STRUTF8& str
         ) const;

      //! Determine if a node has a given property
      //! Note the name is actually UTF8, but 99.9% of the time is
      //! defined by some standards document that requires it to be
      //! limited to the ASCII subset
      bool HasProperty (
         const char* name, 
         bool bCaseSensitive=true
         ) const;

      //! Returns true if this node is empty
      bool IsEmpty() const;

      //! Returns true if this node is text-only
      bool IsText() const;

      //! Create a new, empty child node.
      XMLNODE* NewChild (
         const char* Tag,              //!< Node tag name (UTF8)
         XMLNAMESPACE* NameSpace = 0
         );
         
      //! Create a new, empty child node.
      //! If any characters in "value" need to be escaped into entity
      //! references (eg: &amp;), this method will do it for you.
      XMLNODE* NewChild (
         const char* Tag,              //!< Node tag name (UTF8)
         const UNICODE* value,
         XMLNAMESPACE* NameSpace = 0
         );
         
      //! Copies a node into this document. The source node does not have
      //! to be from the same document.
      XMLNODE* NewChild (
         const XMLNODE* NodeToCopy
         );

      //! Create a new CDATA node.
      //! A CDATA node can contain any text, except the sequence "]]>"
      //! (not counting the quotes) which indicates the end of a CDATA
      //! section in XML.
      //! Note that the UNICODE version of this method doesn't have a
      //! "length" parameter for a reason.  The UNICODE string will be
      //! converted to UTF8, and the only length we're really interested
      //! in is the length of the UTF8
      XMLNODE* NewCDATAChild (
         const char* Tag,              //!< Node tag name (UTF8)
         const UNICODE* value,
         XMLNAMESPACE* NameSpace = 0
         );

      //! Create a new CDATA node.
      //! A CDATA node can contain any text, except the sequence "]]>"
      //! (not counting the quotes) which indicates the end of a CDATA
      //! section in XML.
      XMLNODE* NewCDATAChild (
         const char* Tag,              //!< Node tag name (UTF8)
         const UINT8 * value,          //!< UTF8
         int len = -1,                 //!< Length of UTF8 string (-1 to use strlen)
         XMLNAMESPACE* NameSpace = 0
         );

      //! Create a new child node containing text
      //! If any characters in "value" need to be escaped into entity
      //! references (eg: &amp;), this method will do it for you.
      //! This method exists because the xml library claims that
      //! xmlNewChild and xmlNewTextChild have some difference.
      //! I have yet to figure what that difference actually is.
      XMLNODE* NewTextChild (
         const char* Tag,              //!< Node tag name (UTF8)
         const UNICODE* value,
         XMLNAMESPACE* NameSpace = 0
         );

      //! Replace a node in an XMLDOC with this node.
      //! The NodeToReplace is removed from its parent and deleted.
      //! This node is grafted into the document in its place
      void Replace (
         XMLNODE* NodeToReplace
         );

      //! Set the namespace for this node
      void SetNamespace ( 
         XMLNAMESPACE* NameSpace
         );

      //! Set a property on a node.
      //! Note:  The value string may contain single or double quotes,
      //! but it is an error for it to contain both.
      void SetProperty (
         const char* PropName,         //!< Must be UTF8
         const UNICODE* value
         );

      //! Set a property on a node.
      //! Note:  The value string may contain single or double quotes,
      //! but it is an error for it to contain both.
      void SetProperty (
         const char* PropName,         //!< Must be UTF8
         const char* value             //!< Must be UTF8
         );

      //! Set the text of a node
      void SetText (
         const UNICODE* text
         );

      //! Unset a property on a node.
      void UnsetProperty (
         const char* PropName          //!< Property name (UTF8)
         );

   private:
      #ifndef GENERATING_DOXYGEN_OUTPUT

      //! Constructor/CopyConstructor/Destructor all unimplemented
      //! Memory allocation done through library calls, not new/delete
      XMLNODE();
      XMLNODE(const XMLNODE&);
      ~XMLNODE();

      //! Assignment operator (private and unimplemented)
      XMLNODE& operator= (
         const XMLNODE&
         );

   friend struct _xmlNode;

      //! NO DATA!  The actual structure is allocated by libxml and we can't
      //! expand it.  We just cast their pointer to an XMLNODE.
      #endif // GENERATING_DOXYGEN_OUTPUT
   };


class CLASSLIBEXPORT XMLDOC {
   public:

      
      //! Constructor.  Constructs an empty document
      XMLDOC();

      //! Constructor.  Constructs an XML document given one read into memory.
      //! Note:  UNICODE string gets converted to UTF8 before parsing.  If you
      //! are reading it in UTF8 to begin with, converting it to Unicode and
      //! constructing it that way is a waste of time.  Use the constructor
      //! that takes UTF8 instead.
      XMLDOC (
         const UNICODE* xmlbuffer
         );

      //! Constructor.  Constructs an XML document given one read into memory
      //! (Buffer must be in UTF8 encoding)
      XMLDOC (
         const UINT8* xmlbuffer
         );

      //! Copy constructor. 
      //! Note, copy constructor is expensive.  It has to copy the whole
      //! document tree in memory.
      XMLDOC (
         const XMLDOC&
         );

      //! Destructor
      ~XMLDOC();
      
      //! Assignment operator 
      //! Note, asignment is expensive.  It has to copy the whole
      //! document tree in memory.
      XMLDOC& operator= (
         const XMLDOC&
         );

      //! Add an entity to the XML document defintion.
      //! Allows you to register non-standard entities such as \&deg;
      //! This method is the generic case, multiple-character entity.
      void AddEntity (
         const char* name, //!< Without the "&" or ";"
         const UNICODE* content
         );

      //! Add an entity to the XML document defintion.
      //! Allows you to register non-standard entities such as \&deg;
      //! This method is the simple case. A single character entity.
      void AddEntity (
         const char* name, //!< Without the "&" or ";"
         UNICODE content
         );

      //! Reset the document to a single, empty <root> node.
      void Clear();

      //! Returns a string holding the error message from the last call
      //! to Parse or Read.
      const MISTRING& GetErrorMessage (
         ) const;

      //! Read an HTML file.
      //! Similar to Read() but HTML has more relaxed rules
      //! The file must be in UTF8 encoding
      ERRVALUE ReadHTML (
         const FILEPATH& filepath
         );

      //! Read an HTML file
      //! Similar to Read() but HTML has more relaxed rules
      //! The file must be in UTF8 encoding
      ERRVALUE ReadHTML (
         const UNICODE* filename
         );
      
      //! Read an XML file
      //! The file must be in UTF8 encoding
      ERRVALUE Read (
         const FILEPATH& filepath
         );

      //! Read an XML file
      //! The file must be in UTF8 encoding
      ERRVALUE Read (
         const UNICODE* filename
         ) {
         return (Read(FILEPATH(filename)));
         }
      
      //! Parse an XML document already read into memory 
      //! (Buffer must be in UTF8 encoding)
      ERRVALUE Parse (
         const UINT8* xmlbuffer
         );

      //! Convert the in-memory structure to an MISTRING.
      void Unparse (
         MISTRING& string,
         bool bIndentTreeOutput = true
         );

      void SetCompression(
         int compression
         );

      //! Convert the in-memory structure to an MISTRING using HTML formatting rules.
      void UnparseHTML (
         MISTRING& string,
         bool bIndentTreeOutput = true
         );

      //! Write out to an XML file
      //! The resulting file will be in UTF8 encoding
      ERRVALUE Write (
         const FILEPATH& filepath
         ) const;

      //! Write out to an XML file
      //! The resulting file will be in UTF8 encoding
      ERRVALUE Write (
         const UNICODE* filename
         ) const;

      //! Write out to an XML file as an HTML file
      //! Same as Write, but HTML has slightly different formatting rules
      ERRVALUE WriteHTML (
         const FILEPATH& filepath
         ) const;

      //! Write out to an XML file
      //! Same as Write, but HTML has slightly different formatting rules
      ERRVALUE WriteHTML (
         const UNICODE* filename
         ) const;

      xmlDocPtr* GetDocPtr() const;

      //! Get the root node of the document.  
      XMLNODE* GetRootNode (
         ) const;

      protected:
         //! Will be called by Read and Parse methods to inform derived class
         //! that the whole document has been changed out from under it.
         virtual void OnDocReplaced();

      private:
         #ifndef GENERATING_DOXYGEN_OUTPUT
         
         class ERRORTRAP {
            public:
               ERRORTRAP(XMLDOC*);
               ~ERRORTRAP();
            private:
               MISTRING& m_string;

               static void MyErrorFunc(void*, const char*, ...);
            };

         xmlDocPtr m_doc;
         MISTRING m_ErrorMessage;

         friend class XMLNODE;
         friend class ERRORTRAP;
      #endif // GENERATING_DOXYGEN_OUTPUT

   };

#undef CLASSLIBEXPORT

#endif
 

---