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.
  38
  39     Example: in <tt>\<title\>hi\</title\></tt> there is an element with the name
  40     @c title and irrelevant content and one child of type @c wxXML_TEXT_NODE
  41     with @c hi as content.
  42
  43     If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
  44     wxXmlDocument::Load (default is UTF-8).
  45
  46     @library{wxxml}
  47     @category{xml}
  48
  49     @see wxXmlDocument, wxXmlAttribute
  50 */
  51 class wxXmlNode
  52 {
  53 public:
  54     /**
  55         Creates this XML node and eventually insert it into an existing XML tree.
  56
  57         @param parent
  58             The parent node to which append this node instance.
  59             If this argument is @NULL this new node will be floating and it can
  60             be appended later to another one using the AddChild() or InsertChild()
  61             functions. Otherwise the child is already added to the XML tree by
  62             this constructor and it shouldn't be done again.
  63         @param type
  64             One of the ::wxXmlNodeType enumeration value.
  65         @param name
  66             The name of the node. This is the string which appears between angular brackets.
  67         @param content
  68             The content of the node.
  69             Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
  70         @param attrs
  71             If not @NULL, this wxXmlAttribute object and its eventual siblings are attached to the node.
  72         @param next
  73             If not @NULL, this node and its eventual siblings are attached to the node.
  74         @param lineNo
  75             Number of line this node was present at in input file or -1.
  76     */
  77     wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
  78               const wxString& name,
  79               const wxString& content = wxEmptyString,
  80               wxXmlAttribute* attrs = NULL,
  81               wxXmlNode* next = NULL, int lineNo = -1);
  82
  83     /**
  84         A simplified version of the first constructor form, assuming a @NULL parent.
  85
  86         @param type
  87             One of the ::wxXmlNodeType enumeration value.
  88         @param name
  89             The name of the node. This is the string which appears between angular brackets.
  90         @param content
  91             The content of the node.
  92             Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
  93         @param lineNo
  94             Number of line this node was present at in input file or -1.
  95     */
  96     wxXmlNode(wxXmlNodeType type, const wxString& name,
  97               const wxString& content = wxEmptyString,
  98               int lineNo = -1);
  99
 100     /**
 101         Copy constructor.
 102
 103         Note that this does NOT copy syblings and parent pointer, i.e. GetParent()
 104         and GetNext() will return @NULL after using copy ctor and are never unmodified by operator=().
 105         On the other hand, it DOES copy children and attributes.
 106     */
 107     wxXmlNode(const wxXmlNode& node);
 108
 109     /**
 110         The virtual destructor. Deletes attached children and attributes.
 111     */
 112     virtual ~wxXmlNode();
 113
 114     /**
 115         Appends a attribute with given @a name and @a value to the list of
 116         attributes for this node.
 117     */
 118     virtual void AddAttribute(const wxString& name, const wxString& value);
 119
 120     /**
 121         Appends given attribute to the list of attributes for this node.
 122     */
 123     virtual void AddAttribute(wxXmlAttribute* attr);
 124
 125     /**
 126         Adds node @a child as the last child of this node.
 127
 128         @note
 129         Note that this function works in O(n) time where @e n is the number
 130         of existing children. Consequently, adding large number of child
 131         nodes using this method can be expensive, because it has O(n^2) time
 132         complexity in number of nodes to be added. Use InsertChildAfter() to
 133         populate XML tree in linear time.
 134
 135         @see InsertChild(), InsertChildAfter()
 136     */
 137     virtual void AddChild(wxXmlNode* child);
 138
 139     /**
 140         Removes the first attributes which has the given @a name from the list of
 141         attributes for this node.
 142     */
 143     virtual bool DeleteAttribute(const wxString& name);
 144
 145     /**
 146         Returns true if a attribute named attrName could be found.
 147         The value of that attribute is saved in value (which must not be @NULL).
 148     */
 149     bool GetAttribute(const wxString& attrName, wxString* value) const;
 150
 151     /**
 152         Returns the value of the attribute named @a attrName if it does exist.
 153         If it does not exist, the @a defaultVal is returned.
 154     */
 155     wxString GetAttribute(const wxString& attrName,
 156                           const wxString& defaultVal = wxEmptyString) const;
 157
 158     /**
 159         Return a pointer to the first attribute of this node.
 160     */
 161     wxXmlAttribute* GetAttributes() const;
 162
 163     /**
 164         Returns the first child of this node.
 165         To get a pointer to the second child of this node (if it does exist), use the
 166         GetNext() function on the returned value.
 167     */
 168     wxXmlNode* GetChildren() const;
 169
 170     /**
 171         Returns the content of this node. Can be an empty string.
 172         Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
 173         the content is an empty string. See GetNodeContent() for more details.
 174     */
 175     const wxString& GetContent() const;
 176
 177     /**
 178         Returns the number of nodes which separe this node from @c grandparent.
 179
 180         This function searches only the parents of this node until it finds
 181         @a grandparent or the @NULL node (which is the parent of non-linked
 182         nodes or the parent of a wxXmlDocument's root node).
 183     */
 184     int GetDepth(wxXmlNode* grandparent = NULL) const;
 185
 186     /**
 187         Returns line number of the node in the input XML file or @c -1 if it is unknown.
 188     */
 189     int GetLineNumber() const;
 190
 191     /**
 192         Returns the name of this node.
 193         Can be an empty string (e.g. for nodes of type @c wxXML_TEXT_NODE or
 194         @c wxXML_CDATA_SECTION_NODE).
 195     */
 196     const wxString& GetName() const;
 197
 198     /**
 199         Returns a pointer to the sibling of this node or @NULL if there are no
 200         siblings.
 201     */
 202     wxXmlNode* GetNext() const;
 203
 204     /**
 205         Returns the content of the first child node of type @c wxXML_TEXT_NODE
 206         or @c wxXML_CDATA_SECTION_NODE.
 207         This function is very useful since the XML snippet @c "tagnametagcontent/tagname"
 208         is represented by expat with the following tag tree:
 209
 210         @code
 211         wxXML_ENTITY_NODE name="tagname", content=""
 212         |-- wxXML_TEXT_NODE name="", content="tagcontent"
 213         @endcode
 214
 215         or eventually:
 216
 217         @code
 218         wxXML_ENTITY_NODE name="tagname", content=""
 219         |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
 220         @endcode
 221
 222         An empty string is returned if the node has no children of type
 223         @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content
 224         of the first child of such types is empty.
 225     */
 226     wxString GetNodeContent() const;
 227
 228     /**
 229         Returns a pointer to the parent of this node or @NULL if this node has no
 230         parent.
 231     */
 232     wxXmlNode* GetParent() const;
 233
 234     /**
 235         Returns the type of this node.
 236     */
 237     wxXmlNodeType GetType() const;
 238
 239     /**
 240         Returns @true if this node has a attribute named @a attrName.
 241     */
 242     bool HasAttribute(const wxString& attrName) const;
 243
 244     /**
 245         Inserts the @a child node immediately before @a followingNode in the
 246         children list.
 247
 248         @return @true if @a followingNode has been found and the @a child
 249                 node has been inserted.
 250
 251         @note
 252         For historical reasons, @a followingNode may be @NULL. In that case,
 253         then @a child is prepended to the list of children and becomes the
 254         first child of this node, i.e. it behaves identically to using the
 255         first children (as returned by GetChildren()) for @a followingNode).
 256
 257         @see AddChild(), InsertChildAfter()
 258     */
 259     virtual bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);
 260
 261     /**
 262         Inserts the @a child node immediately after @a precedingNode in the
 263         children list.
 264
 265         @return @true if @a precedingNode has been found and the @a child
 266                 node has been inserted.
 267
 268         @param child
 269             The child to insert.
 270         @param precedingNode
 271             The node to insert @a child after. As a special case, this can be
 272             @NULL if this node has no children yet -- in that case, @a child
 273             will become this node's only child node.
 274
 275         @since 2.8.8
 276
 277         @see InsertChild(), AddChild()
 278     */
 279     virtual bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);
 280
 281     /**
 282         Returns @true if the content of this node is a string containing only
 283         whitespaces (spaces, tabs, new lines, etc).
 284
 285         Note that this function is locale-independent since the parsing of XML
 286         documents must always produce the exact same tree regardless of the
 287         locale it runs under.
 288     */
 289     bool IsWhitespaceOnly() const;
 290
 291     /**
 292         Removes the given node from the children list.
 293
 294         Returns @true if the node was found and removed or @false if the node
 295         could not be found.
 296         Note that the caller is reponsible for deleting the removed node in order
 297         to avoid memory leaks.
 298     */
 299     virtual bool RemoveChild(wxXmlNode* child);
 300
 301     /**
 302         Sets as first attribute the given wxXmlAttribute object.
 303
 304         The caller is responsible to delete any previously present attributes
 305         attached to this node.
 306     */
 307     void SetAttributes(wxXmlAttribute* attr);
 308
 309     /**
 310         Sets as first child the given node.
 311
 312         The caller is responsible to delete any previously present children node.
 313     */
 314     void SetChildren(wxXmlNode* child);
 315
 316     /**
 317         Sets the content of this node.
 318     */
 319     void SetContent(const wxString& con);
 320
 321     /**
 322         Sets the name of this node.
 323     */
 324     void SetName(const wxString& name);
 325
 326     /**
 327         Sets as sibling the given node.
 328
 329         The caller is responsible to delete any previously present sibling node.
 330     */
 331     void SetNext(wxXmlNode* next);
 332
 333     /**
 334         Sets as parent the given node.
 335
 336         The caller is responsible to delete any previously present parent node.
 337     */
 338     void SetParent(wxXmlNode* parent);
 339
 340     /**
 341         Sets the type of this node.
 342     */
 343     void SetType(wxXmlNodeType type);
 344
 345     /**
 346         See the copy constructor for more info.
 347     */
 348     wxXmlNode& operator=(const wxXmlNode& node);
 349 };
 350
 351
 352
 353 /**
 354     @class wxXmlAttribute
 355
 356     Represents a node attribute.
 357
 358     Example: in <tt>\<img src="hello.gif" id="3"/\></tt>, @c src is an attribute
 359     with value @c hello.gif and @c id is an attribute with value @c 3.
 360
 361     @library{wxxml}
 362     @category{xml}
 363
 364     @see wxXmlDocument, wxXmlNode
 365 */
 366 class wxXmlAttribute
 367 {
 368 public:
 369     /**
 370         Default constructor.
 371     */
 372     wxXmlAttribute();
 373
 374     /**
 375         Creates the attribute with given @a name and @a value.
 376         If @a next is not @NULL, then sets it as sibling of this attribute.
 377     */
 378     wxXmlAttribute(const wxString& name, const wxString& value,
 379                    wxXmlAttribute* next = NULL);
 380
 381     /**
 382         The virtual destructor.
 383     */
 384     virtual ~wxXmlAttribute();
 385
 386     /**
 387         Returns the name of this attribute.
 388     */
 389     wxString GetName() const;
 390
 391     /**
 392         Returns the sibling of this attribute or @NULL if there are no siblings.
 393     */
 394     wxXmlAttribute* GetNext() const;
 395
 396     /**
 397         Returns the value of this attribute.
 398     */
 399     wxString GetValue() const;
 400
 401     /**
 402         Sets the name of this attribute.
 403     */
 404     void SetName(const wxString& name);
 405
 406     /**
 407         Sets the sibling of this attribute.
 408     */
 409     void SetNext(wxXmlAttribute* next);
 410
 411     /**
 412         Sets the value of this attribute.
 413     */
 414     void SetValue(const wxString& value);
 415 };
 416
 417
 418
 419 /**
 420     @class wxXmlDocument
 421
 422     This class holds XML data/document as parsed by XML parser in the root node.
 423
 424     wxXmlDocument internally uses the expat library which comes with wxWidgets to
 425     parse the given stream.
 426
 427     A simple example of using XML classes is:
 428
 429     @code
 430     wxXmlDocument doc;
 431     if (!doc.Load("myfile.xml"))
 432         return false;
 433
 434     // start processing the XML file
 435     if (doc.GetRoot()->GetName() != "myroot-node")
 436         return false;
 437
 438     wxXmlNode *child = doc.GetRoot()->GetChildren();
 439     while (child) {
 440
 441         if (child->GetName() == "tag1") {
 442
 443             // process text enclosed by tag1/tag1
 444             wxString content = child->GetNodeContent();
 445
 446             ...
 447
 448             // process attributes of tag1
 449             wxString attrvalue1 =
 450                 child->GetAttribute("attr1", "default-value");
 451             wxString attrvalue2 =
 452                 child->GetAttribute("attr2", "default-value");
 453
 454             ...
 455
 456         } else if (child->GetName() == "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("myfile.xml", "UTF-8", wxXMLDOC_KEEP_WHITESPACE_NODES);
 472
 473     // myfile2.xml will be indentic to myfile.xml saving it this way:
 474     doc.Save("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("myfile.xml");
 483     doc.Save("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 = "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 = "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 = "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 = "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