interface/wx/xml/xml.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        xml/xml.h
   3 // Purpose:     interface of wxXmlNode, wxXmlAttribute, wxXmlDocument
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /// Represents XML node type.
  11 enum wxXmlNodeType
  12 {
  13     // note: values are synchronized with xmlElementType from libxml
  14     wxXML_ELEMENT_NODE       =  1,
  15     wxXML_ATTRIBUTE_NODE     =  2,
  16     wxXML_TEXT_NODE          =  3,
  17     wxXML_CDATA_SECTION_NODE =  4,
  18     wxXML_ENTITY_REF_NODE    =  5,
  19     wxXML_ENTITY_NODE        =  6,
  20     wxXML_PI_NODE            =  7,
  21     wxXML_COMMENT_NODE       =  8,
  22     wxXML_DOCUMENT_NODE      =  9,
  23     wxXML_DOCUMENT_TYPE_NODE = 10,
  24     wxXML_DOCUMENT_FRAG_NODE = 11,
  25     wxXML_NOTATION_NODE      = 12,
  26     wxXML_HTML_DOCUMENT_NODE = 13
  27 };
  28
  29 /**
  30     @class wxXmlNode
  31
  32     Represents a node in an XML document. See wxXmlDocument.
  33
  34     Node has a name and may have content and attributes.
  35
  36     Most common node types are @c wxXML_TEXT_NODE (name and attributes are irrelevant)
  37     and @c wxXML_ELEMENT_NODE (e.g. in @c \<title\>hi\</title\> there is an element
  38     with name="title", irrelevant content and one child @c wxXML_TEXT_NODE
  39     with content="hi").
  40
  41     If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
  42     wxXmlDocument::Load (default is UTF-8).
  43
  44     @library{wxxml}
  45     @category{xml}
  46
  47     @see wxXmlDocument, wxXmlAttribute
  48 */
  49 class wxXmlNode
  50 {
  51 public:
  52     /**
  53         Creates this XML node and eventually insert it into an existing XML tree.
  54
  55         @param parent
  56             The parent node to which append this node instance.
  57             If this argument is @NULL this new node will be floating and it can
  58             be appended later to another one using the AddChild() or InsertChild()
  59             functions. Otherwise the child is already added to the XML tree by
  60             this constructor and it shouldn't be done again.
  61         @param type
  62             One of the ::wxXmlNodeType enumeration value.
  63         @param name
  64             The name of the node. This is the string which appears between angular brackets.
  65         @param content
  66             The content of the node.
  67             Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
  68         @param attrs
  69             If not @NULL, this wxXmlAttribute object and its eventual siblings are attached to the node.
  70         @param next
  71             If not @NULL, this node and its eventual siblings are attached to the node.
  72         @param lineNo
  73             Number of line this node was present at in input file or -1.
  74     */
  75     wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
  76               const wxString& name,
  77               const wxString& content = wxEmptyString,
  78               wxXmlAttribute* attrs = NULL,
  79               wxXmlNode* next = NULL, int lineNo = -1);
  80
  81     /**
  82         A simplified version of the first constructor form, assuming a @NULL parent.
  83
  84         @param type
  85             One of the ::wxXmlNodeType enumeration value.
  86         @param name
  87             The name of the node. This is the string which appears between angular brackets.
  88         @param content
  89             The content of the node.
  90             Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
  91         @param lineNo
  92             Number of line this node was present at in input file or -1.
  93     */
  94     wxXmlNode(wxXmlNodeType type, const wxString& name,
  95               const wxString& content = wxEmptyString,
  96               int lineNo = -1);
  97
  98     /**
  99         Copy constructor.
 100
 101         Note that this does NOT copy syblings and parent pointer, i.e. GetParent()
 102         and GetNext() will return @NULL after using copy ctor and are never unmodified by operator=().
 103         On the other hand, it DOES copy children and attributes.
 104     */
 105     wxXmlNode(const wxXmlNode& node);
 106
 107     /**
 108         The virtual destructor. Deletes attached children and attributes.
 109     */
 110     virtual ~wxXmlNode();
 111
 112     /**
 113         Appends a attribute with given @a name and @a value to the list of
 114         attributes for this node.
 115     */
 116     virtual void AddAttribute(const wxString& name, const wxString& value);
 117
 118     /**
 119         Appends given attribute to the list of attributes for this node.
 120     */
 121     virtual void AddAttribute(wxXmlAttribute* attr);
 122
 123     /**
 124         Adds node @a child as the last child of this node.
 125
 126         @note
 127         Note that this function works in O(n) time where @e n is the number
 128         of existing children. Consequently, adding large number of child
 129         nodes using this method can be expensive, because it has O(n^2) time
 130         complexity in number of nodes to be added. Use InsertChildAfter() to
 131         populate XML tree in linear time.
 132
 133         @see InsertChild(), InsertChildAfter()
 134     */
 135     virtual void AddChild(wxXmlNode* child);
 136
 137     /**
 138         Removes the first attributes which has the given @a name from the list of
 139         attributes for this node.
 140     */
 141     virtual bool DeleteAttribute(const wxString& name);
 142
 143     /**
 144         Returns true if a attribute named attrName could be found.
 145         The value of that attribute is saved in value (which must not be @NULL).
 146     */
 147     bool GetAttribute(const wxString& attrName, wxString* value) const;
 148
 149     /**
 150         Returns the value of the attribute named @a attrName if it does exist.
 151         If it does not exist, the @a defaultVal is returned.
 152     */
 153     wxString GetAttribute(const wxString& attrName,
 154                           const wxString& defaultVal = wxEmptyString) const;
 155
 156     /**
 157         Return a pointer to the first attribute of this node.
 158     */
 159     wxXmlAttribute* GetAttributes() const;
 160
 161     /**
 162         Returns the first child of this node.
 163         To get a pointer to the second child of this node (if it does exist), use the
 164         GetNext() function on the returned value.
 165     */
 166     wxXmlNode* GetChildren() const;
 167
 168     /**
 169         Returns the content of this node. Can be an empty string.
 170         Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
 171         the content is an empty string. See GetNodeContent() for more details.
 172     */
 173     const wxString& GetContent() const;
 174
 175     /**
 176         Returns the number of nodes which separe this node from @c grandparent.
 177
 178         This function searches only the parents of this node until it finds
 179         @a grandparent or the @NULL node (which is the parent of non-linked
 180         nodes or the parent of a wxXmlDocument's root node).
 181     */
 182     int GetDepth(wxXmlNode* grandparent = NULL) const;
 183
 184     /**
 185         Returns line number of the node in the input XML file or @c -1 if it is unknown.
 186     */
 187     int GetLineNumber() const;
 188
 189     /**
 190         Returns the name of this node.
 191         Can be an empty string (e.g. for nodes of type @c wxXML_TEXT_NODE or
 192         @c wxXML_CDATA_SECTION_NODE).
 193     */
 194     const wxString& GetName() const;
 195
 196     /**
 197         Returns a pointer to the sibling of this node or @NULL if there are no
 198         siblings.
 199     */
 200     wxXmlNode* GetNext() const;
 201
 202     /**
 203         Returns the content of the first child node of type @c wxXML_TEXT_NODE
 204         or @c wxXML_CDATA_SECTION_NODE.
 205         This function is very useful since the XML snippet @c "tagnametagcontent/tagname"
 206         is represented by expat with the following tag tree:
 207
 208         @code
 209         wxXML_ENTITY_NODE name="tagname", content=""
 210         |-- wxXML_TEXT_NODE name="", content="tagcontent"
 211         @endcode
 212
 213         or eventually:
 214
 215         @code
 216         wxXML_ENTITY_NODE name="tagname", content=""
 217         |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
 218         @endcode
 219
 220         An empty string is returned if the node has no children of type
 221         @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content
 222         of the first child of such types is empty.
 223     */
 224     wxString GetNodeContent() const;
 225
 226     /**
 227         Returns a pointer to the parent of this node or @NULL if this node has no
 228         parent.
 229     */
 230     wxXmlNode* GetParent() const;
 231
 232     /**
 233         Returns the type of this node.
 234     */
 235     wxXmlNodeType GetType() const;
 236
 237     /**
 238         Returns @true if this node has a attribute named @a attrName.
 239     */
 240     bool HasAttribute(const wxString& attrName) const;
 241
 242     /**
 243         Inserts the @a child node immediately before @a followingNode in the
 244         children list.
 245
 246         @return @true if @a followingNode has been found and the @a child
 247                 node has been inserted.
 248
 249         @note
 250         For historical reasons, @a followingNode may be @NULL. In that case,
 251         then @a child is prepended to the list of children and becomes the
 252         first child of this node, i.e. it behaves identically to using the
 253         first children (as returned by GetChildren()) for @a followingNode).
 254
 255         @see AddChild(), InsertChildAfter()
 256     */
 257     virtual bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);
 258
 259     /**
 260         Inserts the @a child node immediately after @a precedingNode in the
 261         children list.
 262
 263         @return @true if @a precedingNode has been found and the @a child
 264                 node has been inserted.
 265
 266         @param child
 267             The child to insert.
 268         @param precedingNode
 269             The node to insert @a child after. As a special case, this can be
 270             @NULL if this node has no children yet -- in that case, @a child
 271             will become this node's only child node.
 272
 273         @since 2.8.8
 274
 275         @see InsertChild(), AddChild()
 276     */
 277     virtual bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);
 278
 279     /**
 280         Returns @true if the content of this node is a string containing only
 281         whitespaces (spaces, tabs, new lines, etc).
 282
 283         Note that this function is locale-independent since the parsing of XML
 284         documents must always produce the exact same tree regardless of the
 285         locale it runs under.
 286     */
 287     bool IsWhitespaceOnly() const;
 288
 289     /**
 290         Removes the given node from the children list.
 291
 292         Returns @true if the node was found and removed or @false if the node
 293         could not be found.
 294         Note that the caller is reponsible for deleting the removed node in order
 295         to avoid memory leaks.
 296     */
 297     virtual bool RemoveChild(wxXmlNode* child);
 298
 299     /**
 300         Sets as first attribute the given wxXmlAttribute object.
 301
 302         The caller is responsible to delete any previously present attributes
 303         attached to this node.
 304     */
 305     void SetAttributes(wxXmlAttribute* attr);
 306
 307     /**
 308         Sets as first child the given node.
 309
 310         The caller is responsible to delete any previously present children node.
 311     */
 312     void SetChildren(wxXmlNode* child);
 313
 314     /**
 315         Sets the content of this node.
 316     */
 317     void SetContent(const wxString& con);
 318
 319     /**
 320         Sets the name of this node.
 321     */
 322     void SetName(const wxString& name);
 323
 324     /**
 325         Sets as sibling the given node.
 326
 327         The caller is responsible to delete any previously present sibling node.
 328     */
 329     void SetNext(wxXmlNode* next);
 330
 331     /**
 332         Sets as parent the given node.
 333
 334         The caller is responsible to delete any previously present parent node.
 335     */
 336     void SetParent(wxXmlNode* parent);
 337
 338     /**
 339         Sets the type of this node.
 340     */
 341     void SetType(wxXmlNodeType type);
 342
 343     /**
 344         See the copy constructor for more info.
 345     */
 346     wxXmlNode& operator=(const wxXmlNode& node);
 347 };
 348
 349
 350
 351 /**
 352     @class wxXmlAttribute
 353
 354     Represents a node attribute.
 355
 356     Example: in @c "\<img src="hello.gif" id="3"/\>", @c "src" is attribute with value
 357     @c "hello.gif" and @c "id" is a attribute with value @c "3".
 358
 359     @library{wxxml}
 360     @category{xml}
 361
 362     @see wxXmlDocument, wxXmlNode
 363 */
 364 class wxXmlAttribute
 365 {
 366 public:
 367     /**
 368         Default constructor.
 369     */
 370     wxXmlAttribute();
 371
 372     /**
 373         Creates the attribute with given @a name and @a value.
 374         If @a next is not @NULL, then sets it as sibling of this attribute.
 375     */
 376     wxXmlAttribute(const wxString& name, const wxString& value,
 377                    wxXmlAttribute* next = NULL);
 378
 379     /**
 380         The virtual destructor.
 381     */
 382     virtual ~wxXmlAttribute();
 383
 384     /**
 385         Returns the name of this attribute.
 386     */
 387     wxString GetName() const;
 388
 389     /**
 390         Returns the sibling of this attribute or @NULL if there are no siblings.
 391     */
 392     wxXmlAttribute* GetNext() const;
 393
 394     /**
 395         Returns the value of this attribute.
 396     */
 397     wxString GetValue() const;
 398
 399     /**
 400         Sets the name of this attribute.
 401     */
 402     void SetName(const wxString& name);
 403
 404     /**
 405         Sets the sibling of this attribute.
 406     */
 407     void SetNext(wxXmlAttribute* next);
 408
 409     /**
 410         Sets the value of this attribute.
 411     */
 412     void SetValue(const wxString& value);
 413 };
 414
 415
 416
 417 /**
 418     @class wxXmlDocument
 419
 420     This class holds XML data/document as parsed by XML parser in the root node.
 421
 422     wxXmlDocument internally uses the expat library which comes with wxWidgets to
 423     parse the given stream.
 424
 425     A simple example of using XML classes is:
 426
 427     @code
 428     wxXmlDocument doc;
 429     if (!doc.Load(wxT("myfile.xml")))
 430         return @false;
 431
 432     // start processing the XML file
 433     if (doc.GetRoot()-GetName() != wxT("myroot-node"))
 434         return @false;
 435
 436     wxXmlNode *child = doc.GetRoot()-GetChildren();
 437     while (child) {
 438
 439         if (child-GetName() == wxT("tag1")) {
 440
 441             // process text enclosed by tag1/tag1
 442             wxString content = child-GetNodeContent();
 443
 444             ...
 445
 446             // process attributes of tag1
 447             wxString attrvalue1 =
 448                 child-GetAttribute(wxT("attr1"),
 449                                   wxT("default-value"));
 450             wxString attrvalue2 =
 451                 child-GetAttribute(wxT("attr2"),
 452                                   wxT("default-value"));
 453
 454             ...
 455
 456         } else if (child-GetName() == wxT("tag2")) {
 457
 458             // process tag2 ...
 459         }
 460
 461         child = child-GetNext();
 462     }
 463     @endcode
 464
 465     Note that if you want to preserve the original formatting of the loaded file
 466     including whitespaces and indentation, you need to turn off whitespace-only
 467     textnode removal and automatic indentation:
 468
 469     @code
 470     wxXmlDocument doc;
 471     doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
 472
 473     // myfile2.xml will be indentic to myfile.xml saving it this way:
 474     doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
 475     @endcode
 476
 477     Using default parameters, you will get a reformatted document which in general
 478     is different from the original loaded content:
 479
 480     @code
 481     wxXmlDocument doc;
 482     doc.Load(wxT("myfile.xml"));
 483     doc.Save(wxT("myfile2.xml"));  // myfile2.xml != myfile.xml
 484     @endcode
 485
 486     @library{wxxml}
 487     @category{xml}
 488
 489     @see wxXmlNode, wxXmlAttribute
 490 */
 491 class wxXmlDocument : public wxObject
 492 {
 493 public:
 494     /**
 495         Default constructor.
 496     */
 497     wxXmlDocument();
 498
 499     /**
 500         Copy constructor. Deep copies all the XML tree of the given document.
 501     */
 502     wxXmlDocument(const wxXmlDocument& doc);
 503
 504     /**
 505         Loads the given filename using the given encoding. See Load().
 506     */
 507     wxXmlDocument(const wxString& filename,
 508                   const wxString& encoding = wxT("UTF-8"));
 509
 510     /**
 511         Loads the XML document from given stream using the given encoding. See Load().
 512     */
 513     wxXmlDocument(wxInputStream& stream,
 514                   const wxString& encoding = wxT("UTF-8"));
 515
 516     /**
 517         Virtual destructor. Frees the document root node.
 518     */
 519     virtual ~wxXmlDocument();
 520
 521     /**
 522         Detaches the document root node and returns it.
 523
 524         The document root node will be set to @NULL and thus IsOk() will
 525         return @false after calling this function.
 526
 527         Note that the caller is reponsible for deleting the returned node in order
 528         to avoid memory leaks.
 529     */
 530     wxXmlNode* DetachRoot();
 531
 532     /**
 533         Returns encoding of in-memory representation of the document
 534         (same as passed to Load() or constructor, defaults to UTF-8).
 535
 536         @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
 537     */
 538     wxString GetEncoding() const;
 539
 540     /**
 541         Returns encoding of document (may be empty).
 542
 543         @note This is the encoding original file was saved in, @b not the
 544               encoding of in-memory representation!
 545     */
 546     const wxString& GetFileEncoding() const;
 547
 548     /**
 549         Returns the root node of the document.
 550     */
 551     wxXmlNode* GetRoot() const;
 552
 553     /**
 554         Returns the version of document.
 555
 556         This is the value in the @c \<?xml version="1.0"?\> header of the XML document.
 557         If the version attribute was not explicitely given in the header, this function
 558         returns an empty string.
 559     */
 560     const wxString& GetVersion() const;
 561
 562     /**
 563         Returns @true if the document has been loaded successfully.
 564     */
 565     bool IsOk() const;
 566
 567
 568     /**
 569         Parses @a filename as an xml document and loads its data.
 570
 571         If @a flags does not contain wxXMLDOC_KEEP_WHITESPACE_NODES, then, while loading,
 572         all nodes of type @c wxXML_TEXT_NODE (see wxXmlNode) are automatically skipped
 573         if they contain whitespaces only.
 574
 575         The removal of these nodes makes the load process slightly faster and requires
 576         less memory however makes impossible to recreate exactly the loaded text with a
 577         Save() call later. Read the initial description of this class for more info.
 578
 579         Returns true on success, false otherwise.
 580     */
 581     virtual bool Load(const wxString& filename,
 582                       const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 583
 584     /**
 585         Like Load(const wxString&, const wxString&, int) but takes the data from
 586         given input stream.
 587     */
 588     virtual bool Load(wxInputStream& stream,
 589                       const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 590
 591     /**
 592         Saves XML tree creating a file named with given string.
 593
 594         If @a indentstep is greater than or equal to zero, then, while saving,
 595         an automatic indentation is added with steps composed by indentstep spaces.
 596
 597         If @a indentstep is @c wxXML_NO_INDENTATION, then, automatic indentation
 598         is turned off.
 599     */
 600     virtual bool Save(const wxString& filename, int indentstep = 1) const;
 601
 602     /**
 603         Saves XML tree in the given output stream.
 604         See Save(const wxString&, int) for a description of @a indentstep.
 605     */
 606     virtual bool Save(wxOutputStream& stream, int indentstep = 1) const;
 607
 608     /**
 609         Sets the enconding of the document.
 610     */
 611     void SetEncoding(const wxString& enc);
 612
 613     /**
 614         Sets the enconding of the file which will be used to save the document.
 615     */
 616     void SetFileEncoding(const wxString& encoding);
 617
 618     /**
 619         Sets the root node of this document. Deletes previous root node.
 620         Use DetachRoot() and then SetRoot() if you want to replace the root
 621         node without deleting the old document tree.
 622     */
 623     void SetRoot(wxXmlNode* node);
 624
 625     /**
 626         Sets the version of the XML file which will be used to save the document.
 627     */
 628     void SetVersion(const wxString& version);
 629
 630     /**
 631         Deep copies the given document.
 632     */
 633     wxXmlDocument& operator=(const wxXmlDocument& doc);
 634 };
 635