include/wx/xml/xml.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/xml/xml.h
   3 // Purpose:     wxXmlDocument - XML parser & data holder class
   4 // Author:      Vaclav Slavik
   5 // Created:     2000/03/05
   6 // Copyright:   (c) 2000 Vaclav Slavik
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10
  11 #ifndef _WX_XML_H_
  12 #define _WX_XML_H_
  13
  14 #include "wx/defs.h"
  15
  16 #if wxUSE_XML
  17
  18 #include "wx/string.h"
  19 #include "wx/object.h"
  20 #include "wx/list.h"
  21 #include "wx/versioninfo.h"
  22
  23 #ifdef WXMAKINGDLL_XML
  24     #define WXDLLIMPEXP_XML WXEXPORT
  25 #elif defined(WXUSINGDLL)
  26     #define WXDLLIMPEXP_XML WXIMPORT
  27 #else // not making nor using DLL
  28     #define WXDLLIMPEXP_XML
  29 #endif
  30
  31 class WXDLLIMPEXP_FWD_XML wxXmlNode;
  32 class WXDLLIMPEXP_FWD_XML wxXmlAttribute;
  33 class WXDLLIMPEXP_FWD_XML wxXmlDocument;
  34 class WXDLLIMPEXP_FWD_XML wxXmlIOHandler;
  35 class WXDLLIMPEXP_FWD_BASE wxInputStream;
  36 class WXDLLIMPEXP_FWD_BASE wxOutputStream;
  37
  38 // Represents XML node type.
  39 enum wxXmlNodeType
  40 {
  41     // note: values are synchronized with xmlElementType from libxml
  42     wxXML_ELEMENT_NODE       =  1,
  43     wxXML_ATTRIBUTE_NODE     =  2,
  44     wxXML_TEXT_NODE          =  3,
  45     wxXML_CDATA_SECTION_NODE =  4,
  46     wxXML_ENTITY_REF_NODE    =  5,
  47     wxXML_ENTITY_NODE        =  6,
  48     wxXML_PI_NODE            =  7,
  49     wxXML_COMMENT_NODE       =  8,
  50     wxXML_DOCUMENT_NODE      =  9,
  51     wxXML_DOCUMENT_TYPE_NODE = 10,
  52     wxXML_DOCUMENT_FRAG_NODE = 11,
  53     wxXML_NOTATION_NODE      = 12,
  54     wxXML_HTML_DOCUMENT_NODE = 13
  55 };
  56
  57
  58 // Represents node property(ies).
  59 // Example: in <img src="hello.gif" id="3"/> "src" is property with value
  60 //          "hello.gif" and "id" is prop. with value "3".
  61
  62 class WXDLLIMPEXP_XML wxXmlAttribute
  63 {
  64 public:
  65     wxXmlAttribute() : m_next(NULL) {}
  66     wxXmlAttribute(const wxString& name, const wxString& value,
  67                   wxXmlAttribute *next = NULL)
  68             : m_name(name), m_value(value), m_next(next) {}
  69     virtual ~wxXmlAttribute() {}
  70
  71     const wxString& GetName() const { return m_name; }
  72     const wxString& GetValue() const { return m_value; }
  73     wxXmlAttribute *GetNext() const { return m_next; }
  74
  75     void SetName(const wxString& name) { m_name = name; }
  76     void SetValue(const wxString& value) { m_value = value; }
  77     void SetNext(wxXmlAttribute *next) { m_next = next; }
  78
  79 private:
  80     wxString m_name;
  81     wxString m_value;
  82     wxXmlAttribute *m_next;
  83 };
  84
  85 #if WXWIN_COMPATIBILITY_2_8
  86     // NB: #define is used instead of typedef so that forward declarations
  87     //     continue to work
  88     #define wxXmlProperty wxXmlAttribute
  89 #endif
  90
  91
  92 // Represents node in XML document. Node has name and may have content and
  93 // attributes. Most common node types are wxXML_TEXT_NODE (name and attributes
  94 // are irrelevant) and wxXML_ELEMENT_NODE (e.g. in <title>hi</title> there is
  95 // element with name="title", irrelevant content and one child (wxXML_TEXT_NODE
  96 // with content="hi").
  97 //
  98 // If wxUSE_UNICODE is 0, all strings are encoded in the encoding given to Load
  99 // (default is UTF-8).
 100
 101 class WXDLLIMPEXP_XML wxXmlNode
 102 {
 103 public:
 104     wxXmlNode()
 105         : m_attrs(NULL), m_parent(NULL), m_children(NULL), m_next(NULL),
 106           m_lineNo(-1), m_noConversion(false)
 107     {
 108     }
 109
 110     wxXmlNode(wxXmlNode *parent, wxXmlNodeType type,
 111               const wxString& name, const wxString& content = wxEmptyString,
 112               wxXmlAttribute *attrs = NULL, wxXmlNode *next = NULL,
 113               int lineNo = -1);
 114
 115     virtual ~wxXmlNode();
 116
 117     // copy ctor & operator=. Note that this does NOT copy siblings
 118     // and parent pointer, i.e. m_parent and m_next will be NULL
 119     // after using copy ctor and are never unmodified by operator=.
 120     // On the other hand, it DOES copy children and attributes.
 121     wxXmlNode(const wxXmlNode& node);
 122     wxXmlNode& operator=(const wxXmlNode& node);
 123
 124     // user-friendly creation:
 125     wxXmlNode(wxXmlNodeType type, const wxString& name,
 126               const wxString& content = wxEmptyString,
 127               int lineNo = -1);
 128     virtual void AddChild(wxXmlNode *child);
 129     virtual bool InsertChild(wxXmlNode *child, wxXmlNode *followingNode);
 130     virtual bool InsertChildAfter(wxXmlNode *child, wxXmlNode *precedingNode);
 131     virtual bool RemoveChild(wxXmlNode *child);
 132     virtual void AddAttribute(const wxString& name, const wxString& value);
 133     virtual bool DeleteAttribute(const wxString& name);
 134
 135     // access methods:
 136     wxXmlNodeType GetType() const { return m_type; }
 137     const wxString& GetName() const { return m_name; }
 138     const wxString& GetContent() const { return m_content; }
 139
 140     bool IsWhitespaceOnly() const;
 141     int GetDepth(wxXmlNode *grandparent = NULL) const;
 142
 143     // Gets node content from wxXML_ENTITY_NODE
 144     // The problem is, <tag>content<tag> is represented as
 145     // wxXML_ENTITY_NODE name="tag", content=""
 146     //    |-- wxXML_TEXT_NODE or
 147     //        wxXML_CDATA_SECTION_NODE name="" content="content"
 148     wxString GetNodeContent() const;
 149
 150     wxXmlNode *GetParent() const { return m_parent; }
 151     wxXmlNode *GetNext() const { return m_next; }
 152     wxXmlNode *GetChildren() const { return m_children; }
 153
 154     wxXmlAttribute *GetAttributes() const { return m_attrs; }
 155     bool GetAttribute(const wxString& attrName, wxString *value) const;
 156     wxString GetAttribute(const wxString& attrName,
 157                           const wxString& defaultVal = wxEmptyString) const;
 158     bool HasAttribute(const wxString& attrName) const;
 159
 160     int GetLineNumber() const { return m_lineNo; }
 161
 162     void SetType(wxXmlNodeType type) { m_type = type; }
 163     void SetName(const wxString& name) { m_name = name; }
 164     void SetContent(const wxString& con) { m_content = con; }
 165
 166     void SetParent(wxXmlNode *parent) { m_parent = parent; }
 167     void SetNext(wxXmlNode *next) { m_next = next; }
 168     void SetChildren(wxXmlNode *child) { m_children = child; }
 169
 170     void SetAttributes(wxXmlAttribute *attr) { m_attrs = attr; }
 171     virtual void AddAttribute(wxXmlAttribute *attr);
 172
 173     // If true, don't do encoding conversion to improve efficiency - node content is ACII text
 174     bool GetNoConversion() const { return m_noConversion; }
 175     void SetNoConversion(bool noconversion) { m_noConversion = noconversion; }
 176
 177 #if WXWIN_COMPATIBILITY_2_8
 178     wxDEPRECATED( inline wxXmlAttribute *GetProperties() const );
 179     wxDEPRECATED( inline bool GetPropVal(const wxString& propName,
 180                                          wxString *value) const );
 181     wxDEPRECATED( inline wxString GetPropVal(const wxString& propName,
 182                                              const wxString& defaultVal) const );
 183     wxDEPRECATED( inline bool HasProp(const wxString& propName) const );
 184
 185     wxDEPRECATED( inline void SetProperties(wxXmlAttribute *prop) );
 186 #endif // WXWIN_COMPATIBILITY_2_8
 187
 188     // The following three functions are backward compatibility, but because
 189     // they were virtual, we must make it possible to override them. This
 190     // is done by calling e.g. AddProperty() from AddAttribute(), so we have
 191     // to keep AddProperty() even if 2.8 compatibility is off. To prevent
 192     // old code from compiling in that case, we make them private and
 193     // non-virtual. (This can be removed when WXWIN_COMPATIBILITY_2_8 is
 194     // removed, we'll have just *Attribute versions then.)
 195 #if WXWIN_COMPATIBILITY_2_8
 196     wxDEPRECATED_BUT_USED_INTERNALLY(
 197         virtual void AddProperty(const wxString& name, const wxString& value) );
 198     wxDEPRECATED_BUT_USED_INTERNALLY(
 199         virtual bool DeleteProperty(const wxString& name) );
 200     wxDEPRECATED_BUT_USED_INTERNALLY(
 201         virtual void AddProperty(wxXmlAttribute *attr) );
 202 #else
 203 private:
 204     void AddProperty(const wxString& name, const wxString& value);
 205     bool DeleteProperty(const wxString& name);
 206     void AddProperty(wxXmlAttribute *attr);
 207 #endif // WXWIN_COMPATIBILITY_2_8/!WXWIN_COMPATIBILITY_2_8
 208
 209 private:
 210     wxXmlNodeType m_type;
 211     wxString m_name;
 212     wxString m_content;
 213     wxXmlAttribute *m_attrs;
 214     wxXmlNode *m_parent, *m_children, *m_next;
 215     int m_lineNo; // line number in original file, or -1
 216     bool m_noConversion; // don't do encoding conversion - node is plain text
 217
 218     void DoFree();
 219     void DoCopy(const wxXmlNode& node);
 220 };
 221
 222 #if WXWIN_COMPATIBILITY_2_8
 223 inline wxXmlAttribute *wxXmlNode::GetProperties() const
 224     { return GetAttributes(); }
 225 inline bool wxXmlNode::GetPropVal(const wxString& propName,
 226                                   wxString *value) const
 227     { return GetAttribute(propName, value); }
 228 inline wxString wxXmlNode::GetPropVal(const wxString& propName,
 229                                       const wxString& defaultVal) const
 230     { return GetAttribute(propName, defaultVal); }
 231 inline bool wxXmlNode::HasProp(const wxString& propName) const
 232     { return HasAttribute(propName); }
 233 inline void wxXmlNode::SetProperties(wxXmlAttribute *prop)
 234     { SetAttributes(prop); }
 235 #endif // WXWIN_COMPATIBILITY_2_8
 236
 237
 238
 239 // special indentation value for wxXmlDocument::Save
 240 #define wxXML_NO_INDENTATION           (-1)
 241
 242 // flags for wxXmlDocument::Load
 243 enum wxXmlDocumentLoadFlag
 244 {
 245     wxXMLDOC_NONE = 0,
 246     wxXMLDOC_KEEP_WHITESPACE_NODES = 1
 247 };
 248
 249
 250 // This class holds XML data/document as parsed by XML parser.
 251
 252 class WXDLLIMPEXP_XML wxXmlDocument : public wxObject
 253 {
 254 public:
 255     wxXmlDocument();
 256     wxXmlDocument(const wxString& filename,
 257                   const wxString& encoding = wxT("UTF-8"));
 258     wxXmlDocument(wxInputStream& stream,
 259                   const wxString& encoding = wxT("UTF-8"));
 260     virtual ~wxXmlDocument() { wxDELETE(m_docNode); }
 261
 262     wxXmlDocument(const wxXmlDocument& doc);
 263     wxXmlDocument& operator=(const wxXmlDocument& doc);
 264
 265     // Parses .xml file and loads data. Returns TRUE on success, FALSE
 266     // otherwise.
 267     virtual bool Load(const wxString& filename,
 268                       const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 269     virtual bool Load(wxInputStream& stream,
 270                       const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 271
 272     // Saves document as .xml file.
 273     virtual bool Save(const wxString& filename, int indentstep = 2) const;
 274     virtual bool Save(wxOutputStream& stream, int indentstep = 2) const;
 275
 276     bool IsOk() const { return GetRoot() != NULL; }
 277
 278     // Returns root node of the document.
 279     wxXmlNode *GetRoot() const;
 280     // Returns the document node.
 281     wxXmlNode *GetDocumentNode() const { return m_docNode; }
 282
 283
 284     // Returns version of document (may be empty).
 285     const wxString& GetVersion() const { return m_version; }
 286     // Returns encoding of document (may be empty).
 287     // Note: this is the encoding original file was saved in, *not* the
 288     // encoding of in-memory representation!
 289     const wxString& GetFileEncoding() const { return m_fileEncoding; }
 290
 291     // Write-access methods:
 292     wxXmlNode *DetachDocumentNode() { wxXmlNode *old=m_docNode; m_docNode=NULL; return old; }
 293     void SetDocumentNode(wxXmlNode *node) { wxDELETE(m_docNode); m_docNode = node; }
 294     wxXmlNode *DetachRoot();
 295     void SetRoot(wxXmlNode *node);
 296     void SetVersion(const wxString& version) { m_version = version; }
 297     void SetFileEncoding(const wxString& encoding) { m_fileEncoding = encoding; }
 298     void AppendToProlog(wxXmlNode *node);
 299
 300 #if !wxUSE_UNICODE
 301     // Returns encoding of in-memory representation of the document
 302     // (same as passed to Load or ctor, defaults to UTF-8).
 303     // NB: this is meaningless in Unicode build where data are stored as wchar_t*
 304     wxString GetEncoding() const { return m_encoding; }
 305     void SetEncoding(const wxString& enc) { m_encoding = enc; }
 306 #endif
 307
 308     static wxVersionInfo GetLibraryVersionInfo();
 309
 310 private:
 311     wxString   m_version;
 312     wxString   m_fileEncoding;
 313 #if !wxUSE_UNICODE
 314     wxString   m_encoding;
 315 #endif
 316     wxXmlNode *m_docNode;
 317
 318     void DoCopy(const wxXmlDocument& doc);
 319
 320     DECLARE_CLASS(wxXmlDocument)
 321 };
 322
 323 #endif // wxUSE_XML
 324
 325 #endif // _WX_XML_H_