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     ~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     void AddAttribute(const wxString& name, const wxString& value);
 117
 118     /**
 119         Appends given attribute to the list of attributes for this node.
 120     */
 121     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     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     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     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     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     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 precedingNode
 267             The node to insert @a child after. As a special case, this can be
 268             @NULL if this node has no children yet -- in that case, @a child
 269             will become this node's only child node.
 270
 271         @since 2.8.8
 272
 273         @see InsertChild(), AddChild()
 274     */
 275     bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);
 276
 277     /**
 278         Returns @true if the content of this node is a string containing only
 279         whitespaces (spaces, tabs, new lines, etc).
 280
 281         Note that this function is locale-independent since the parsing of XML
 282         documents must always produce the exact same tree regardless of the
 283         locale it runs under.
 284     */
 285     bool IsWhitespaceOnly() const;
 286
 287     /**
 288         Removes the given node from the children list.
 289
 290         Returns @true if the node was found and removed or @false if the node
 291         could not be found.
 292         Note that the caller is reponsible for deleting the removed node in order
 293         to avoid memory leaks.
 294     */
 295     bool RemoveChild(wxXmlNode* child);
 296
 297     /**
 298         Sets as first attribute the given wxXmlAttribute object.
 299
 300         The caller is responsible to delete any previously present attributes
 301         attached to this node.
 302     */
 303     void SetAttributes(wxXmlAttribute* attr);
 304
 305     /**
 306         Sets as first child the given node.
 307
 308         The caller is responsible to delete any previously present children node.
 309     */
 310     void SetChildren(wxXmlNode* child);
 311
 312     /**
 313         Sets the content of this node.
 314     */
 315     void SetContent(const wxString& con);
 316
 317     /**
 318         Sets the name of this node.
 319     */
 320     void SetName(const wxString& name);
 321
 322     /**
 323         Sets as sibling the given node.
 324
 325         The caller is responsible to delete any previously present sibling node.
 326     */
 327     void SetNext(wxXmlNode* next);
 328
 329     /**
 330         Sets as parent the given node.
 331
 332         The caller is responsible to delete any previously present parent node.
 333     */
 334     void SetParent(wxXmlNode* parent);
 335
 336     /**
 337         Sets the type of this node.
 338     */
 339     void SetType(wxXmlNodeType type);
 340
 341     /**
 342         See the copy constructor for more info.
 343     */
 344     wxXmlNode& operator=(const wxXmlNode& node);
 345 };
 346
 347
 348
 349 /**
 350     @class wxXmlAttribute
 351
 352     Represents a node attribute.
 353
 354     Example: in @c "\<img src="hello.gif" id="3"/\>", @c "src" is attribute with value
 355     @c "hello.gif" and @c "id" is a attribute with value @c "3".
 356
 357     @library{wxxml}
 358     @category{xml}
 359
 360     @see wxXmlDocument, wxXmlNode
 361 */
 362 class wxXmlAttribute
 363 {
 364 public:
 365     /**
 366         Default constructor.
 367     */
 368     wxXmlAttribute();
 369
 370     /**
 371         Creates the attribute with given @a name and @a value.
 372         If @a next is not @NULL, then sets it as sibling of this attribute.
 373     */
 374     wxXmlAttribute(const wxString& name, const wxString& value,
 375                    wxXmlAttribute* next = NULL);
 376
 377     /**
 378         The virtual destructor.
 379     */
 380     ~wxXmlAttribute();
 381
 382     /**
 383         Returns the name of this attribute.
 384     */
 385     wxString GetName() const;
 386
 387     /**
 388         Returns the sibling of this attribute or @NULL if there are no siblings.
 389     */
 390     wxXmlAttribute* GetNext() const;
 391
 392     /**
 393         Returns the value of this attribute.
 394     */
 395     wxString GetValue() const;
 396
 397     /**
 398         Sets the name of this attribute.
 399     */
 400     void SetName(const wxString& name);
 401
 402     /**
 403         Sets the sibling of this attribute.
 404     */
 405     void SetNext(wxXmlAttribute* next);
 406
 407     /**
 408         Sets the value of this attribute.
 409     */
 410     void SetValue(const wxString& value);
 411 };
 412
 413
 414
 415 /**
 416     @class wxXmlDocument
 417
 418     This class holds XML data/document as parsed by XML parser in the root node.
 419
 420     wxXmlDocument internally uses the expat library which comes with wxWidgets to
 421     parse the given stream.
 422
 423     A simple example of using XML classes is:
 424
 425     @code
 426     wxXmlDocument doc;
 427     if (!doc.Load(wxT("myfile.xml")))
 428         return @false;
 429
 430     // start processing the XML file
 431     if (doc.GetRoot()-GetName() != wxT("myroot-node"))
 432         return @false;
 433
 434     wxXmlNode *child = doc.GetRoot()-GetChildren();
 435     while (child) {
 436
 437         if (child-GetName() == wxT("tag1")) {
 438
 439             // process text enclosed by tag1/tag1
 440             wxString content = child-GetNodeContent();
 441
 442             ...
 443
 444             // process attributes of tag1
 445             wxString attrvalue1 =
 446                 child-GetAttribute(wxT("attr1"),
 447                                   wxT("default-value"));
 448             wxString attrvalue2 =
 449                 child-GetAttribute(wxT("attr2"),
 450                                   wxT("default-value"));
 451
 452             ...
 453
 454         } else if (child-GetName() == wxT("tag2")) {
 455
 456             // process tag2 ...
 457         }
 458
 459         child = child-GetNext();
 460     }
 461     @endcode
 462
 463     Note that if you want to preserve the original formatting of the loaded file
 464     including whitespaces and indentation, you need to turn off whitespace-only
 465     textnode removal and automatic indentation:
 466
 467     @code
 468     wxXmlDocument doc;
 469     doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
 470
 471     // myfile2.xml will be indentic to myfile.xml saving it this way:
 472     doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
 473     @endcode
 474
 475     Using default parameters, you will get a reformatted document which in general
 476     is different from the original loaded content:
 477
 478     @code
 479     wxXmlDocument doc;
 480     doc.Load(wxT("myfile.xml"));
 481     doc.Save(wxT("myfile2.xml"));  // myfile2.xml != myfile.xml
 482     @endcode
 483
 484     @library{wxxml}
 485     @category{xml}
 486
 487     @see wxXmlNode, wxXmlAttribute
 488 */
 489 class wxXmlDocument : public wxObject
 490 {
 491 public:
 492     /**
 493         Default constructor.
 494     */
 495     wxXmlDocument();
 496
 497     /**
 498         Copy constructor. Deep copies all the XML tree of the given document.
 499     */
 500     wxXmlDocument(const wxXmlDocument& doc);
 501
 502     /**
 503         Loads the given filename using the given encoding. See Load().
 504     */
 505     wxXmlDocument(const wxString& filename,
 506                   const wxString& encoding = wxT("UTF-8"));
 507
 508     /**
 509         Loads the XML document from given stream using the given encoding. See Load().
 510     */
 511     wxXmlDocument(wxInputStream& stream,
 512                   const wxString& encoding = wxT("UTF-8"));
 513
 514     /**
 515         Virtual destructor. Frees the document root node.
 516     */
 517     ~wxXmlDocument();
 518
 519     /**
 520         Detaches the document root node and returns it.
 521
 522         The document root node will be set to @NULL and thus IsOk() will
 523         return @false after calling this function.
 524
 525         Note that the caller is reponsible for deleting the returned node in order
 526         to avoid memory leaks.
 527     */
 528     wxXmlNode* DetachRoot();
 529
 530     /**
 531         Returns encoding of in-memory representation of the document
 532         (same as passed to Load() or constructor, defaults to UTF-8).
 533
 534         @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
 535     */
 536     wxString GetEncoding() const;
 537
 538     /**
 539         Returns encoding of document (may be empty).
 540
 541         @note This is the encoding original file was saved in, @b not the
 542               encoding of in-memory representation!
 543     */
 544     wxString GetFileEncoding() const;
 545
 546     /**
 547         Returns the root node of the document.
 548     */
 549     wxXmlNode* GetRoot() const;
 550
 551     /**
 552         Returns the version of document.
 553
 554         This is the value in the @c \<?xml version="1.0"?\> header of the XML document.
 555         If the version attribute was not explicitely given in the header, this function
 556         returns an empty string.
 557     */
 558     wxString GetVersion() const;
 559
 560     /**
 561         Returns @true if the document has been loaded successfully.
 562     */
 563     bool IsOk() const;
 564
 565
 566     /**
 567         Parses @a filename as an xml document and loads its data.
 568
 569         If @a flags does not contain wxXMLDOC_KEEP_WHITESPACE_NODES, then, while loading,
 570         all nodes of type @c wxXML_TEXT_NODE (see wxXmlNode) are automatically skipped
 571         if they contain whitespaces only.
 572
 573         The removal of these nodes makes the load process slightly faster and requires
 574         less memory however makes impossible to recreate exactly the loaded text with a
 575         Save() call later. Read the initial description of this class for more info.
 576
 577         Returns true on success, false otherwise.
 578     */
 579     virtual bool Load(const wxString& filename,
 580                       const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 581
 582     /**
 583         Like Load(const wxString&, const wxString&, int) but takes the data from
 584         given input stream.
 585     */
 586     virtual bool Load(wxInputStream& stream,
 587                       const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 588
 589     /**
 590         Saves XML tree creating a file named with given string.
 591
 592         If @a indentstep is greater than or equal to zero, then, while saving,
 593         an automatic indentation is added with steps composed by indentstep spaces.
 594
 595         If @a indentstep is @c wxXML_NO_INDENTATION, then, automatic indentation
 596         is turned off.
 597     */
 598     virtual bool Save(const wxString& filename, int indentstep = 1) const;
 599
 600     /**
 601         Saves XML tree in the given output stream.
 602         See Save(const wxString&, int) for a description of @a indentstep.
 603     */
 604     virtual bool Save(wxOutputStream& stream, int indentstep = 1) const;
 605
 606     /**
 607         Sets the enconding of the document.
 608     */
 609     void SetEncoding(const wxString& enc);
 610
 611     /**
 612         Sets the enconding of the file which will be used to save the document.
 613     */
 614     void SetFileEncoding(const wxString& encoding);
 615
 616     /**
 617         Sets the root node of this document. Deletes previous root node.
 618         Use DetachRoot() and then SetRoot() if you want to replace the root
 619         node without deleting the old document tree.
 620     */
 621     void SetRoot(wxXmlNode* node);
 622
 623     /**
 624         Sets the version of the XML file which will be used to save the document.
 625     */
 626     void SetVersion(const wxString& version);
 627
 628     /**
 629         Deep copies the given document.
 630     */
 631     wxXmlDocument& operator=(const wxXmlDocument& doc);
 632 };
 633