interface/wx/xml/xml.h

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