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("myfile.xml"))
 430         return @false;
 431
 432     // start processing the XML file
 433     if (doc.GetRoot()->GetName() != "myroot-node")
 434         return @false;
 435
 436     wxXmlNode *child = doc.GetRoot()->GetChildren();
 437     while (child) {
 438
 439         if (child-GetName() == "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("attr1", "default-value");
 449             wxString attrvalue2 =
 450                 child->GetAttribute("attr2", "default-value");
 451
 452             ...
 453
 454         } else if (child->GetName() == "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("myfile.xml", "UTF-8", wxXMLDOC_KEEP_WHITESPACE_NODES);
 470
 471     // myfile2.xml will be indentic to myfile.xml saving it this way:
 472     doc.Save("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("myfile.xml");
 481     doc.Save("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 = "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     virtual ~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     const 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     const 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