KoXmlReader.h 12.3 KB
Newer Older
1
/* This file is part of the KDE project
2
   Copyright (C) 2005-2006 Ariya Hidayat <ariya@kde.org>
3 4 5 6 7 8 9 10 11 12 13 14 15 16

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17
   Boston, MA 02110-1301, USA.
18 19 20 21 22 23 24 25
*/

#ifndef KOFFICE_XMLREADER
#define KOFFICE_XMLREADER

// use standard QDom, useful to test KoXml classes against Qt's QDom
#define KOXML_USE_QDOM

26
#include <kostore_export.h>
27

28 29 30 31 32 33
#include <qxml.h>
#include <qdom.h>

class QIODevice;
class QTextDecoder;

34 35
#ifdef KOXML_USE_QDOM

36 37 38 39 40 41
typedef QDomNode KoXmlNode;
typedef QDomElement KoXmlElement;
typedef QDomText KoXmlText;
typedef QDomCDATASection KoXmlCDATASection;
typedef QDomDocumentType KoXmlDocumentType;
typedef QDomDocument KoXmlDocument;
42 43 44 45 46 47 48 49 50 51

#else

class QString;
class QXmlReader;
class QXmlInputSource;

class KoXmlElement;
class KoXmlText;
class KoXmlCDATASection;
52
class KoXmlDocumentType;
53 54 55 56 57 58 59 60
class KoXmlDocument;
class KoXmlNodeData;

/**
 * KoXmlNode represents a node in a DOM tree.
 *
 * KoXmlNode is a base class for KoXmlElement, KoXmlText.
 * Often, these subclasses are used for getting the data instead of KoXmlNode.
61
 * However, as base class, KoXmlNode is very helpful when for example iterating 
62 63
 * all child nodes within one parent node.
 *
64
 * KoXmlNode implements an explicit sharing, a node shares its data with 
65 66 67 68
 * other copies (if exist).
 *
 * @author Ariya Hidayat <ariya@kde.org>
 */
69
class KOSTORE_EXPORT KoXmlNode
70 71 72
{
public:

73
  enum NodeType 
74 75 76 77 78 79
  {
    NullNode = 0,
    ElementNode,
    TextNode,
    CDATASectionNode,
    ProcessingInstructionNode,
80 81
    DocumentNode,
    DocumentTypeNode
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
  };

  KoXmlNode();
  KoXmlNode( const KoXmlNode& node );
  KoXmlNode& operator=( const KoXmlNode& node );
  bool operator== ( const KoXmlNode& ) const;
  bool operator!= ( const KoXmlNode& ) const;
  virtual ~KoXmlNode();

  virtual KoXmlNode::NodeType nodeType() const;
  virtual bool isNull() const;
  virtual bool isElement() const;
  virtual bool isText() const;
  virtual bool isCDATASection() const;
  virtual bool isDocument() const;
97
  virtual bool isDocumentType() const;
98

99
  virtual void clear();
Ariya Hidayat's avatar
Ariya Hidayat committed
100 101 102 103
  KoXmlElement toElement() const;
  KoXmlText toText() const;
  KoXmlCDATASection toCDATASection() const;
  KoXmlDocument toDocument() const;
104 105 106 107 108 109 110 111 112 113 114 115 116 117

  virtual QString nodeName() const;
  virtual QString namespaceURI() const;
  virtual QString prefix() const;
  virtual QString localName() const;

  KoXmlDocument ownerDocument() const;
  KoXmlNode parentNode() const;

  bool hasChildNodes() const;
  KoXmlNode firstChild() const;
  KoXmlNode lastChild() const;
  KoXmlNode nextSibling() const;
  KoXmlNode previousSibling() const;
118 119 120
  
  // equivalen to node.childNodes().count() if node is a QDomNode instance
  int childNodesCount() const;
121 122 123
  
  // workaround to get and iterate over all attributes
  QStringList attributeNames() const;
124 125 126 127 128 129

  KoXmlNode namedItem( const QString& name ) const;
  KoXmlNode namedItemNS( const QString& nsURI, const QString& name ) const;

  /**
   * Loads all child nodes (if any) of this node. Normally you do not need
130
   * to call this function as the child nodes will be automatically 
131 132 133 134 135
   * loaded when necessary.
   */
  void load( int depth=1 );

  /**
136
   * Releases all child nodes of this node. 
137 138 139
   */
  void unload();

140 141 142
  // compatibility
  QDomNode asQDomNode( QDomDocument ownerDoc ) const;

143 144 145 146 147 148 149 150 151 152 153 154 155
protected:
  KoXmlNodeData* d;
  KoXmlNode( KoXmlNodeData* );
};

/**
 * KoXmlElement represents a tag element in a DOM tree.
 *
 * KoXmlElement holds information about an XML tag, along with its attributes.
 *
 * @author Ariya Hidayat <ariya@kde.org>
 */

156
class KOSTORE_EXPORT KoXmlElement: public KoXmlNode
157 158 159 160 161 162 163 164 165 166 167 168 169 170
{
public:
  KoXmlElement();
  KoXmlElement( const KoXmlElement& element );
  KoXmlElement& operator=( const KoXmlElement& element );
  virtual ~KoXmlElement();
  bool operator== ( const KoXmlElement& ) const;
  bool operator!= ( const KoXmlElement& ) const;

  QString tagName() const;
  QString text() const;

  QString attribute( const QString& name ) const;
  QString attribute( const QString& name, const QString& defaultValue ) const;
171
  QString attributeNS( const QString& namespaceURI, const QString& localName, 
172 173 174 175 176 177 178 179 180 181 182 183 184 185
    const QString& defaultValue ) const;
  bool hasAttribute( const QString& name ) const;
  bool hasAttributeNS( const QString& namespaceURI, const QString& localName ) const;

private:
  friend class KoXmlNode;
  friend class KoXmlDocument;
  KoXmlElement( KoXmlNodeData* );
};

/**
 * KoXmlText represents a text in a DOM tree.
 * @author Ariya Hidayat <ariya@kde.org>
 */
186
class KOSTORE_EXPORT KoXmlText: public KoXmlNode
187 188 189 190 191 192 193 194 195 196 197 198 199
{
public:
  KoXmlText();
  KoXmlText( const KoXmlText& text );
  KoXmlText& operator=( const KoXmlText& text );
  virtual ~KoXmlText();

  QString data() const;
  void setData( const QString& data );
  virtual bool isText() const;

private:
  friend class KoXmlNode;
200
  friend class KoXmlCDATASection;
201 202 203 204 205 206 207 208
  friend class KoXmlDocument;
  KoXmlText( KoXmlNodeData* );
};

/**
 * KoXmlCDATASection represents a CDATA section in a DOM tree.
 * @author Ariya Hidayat <ariya@kde.org>
 */
209
class KOSTORE_EXPORT KoXmlCDATASection: public KoXmlText
210 211 212 213 214 215 216 217 218 219 220 221 222 223 224
{
public:
  KoXmlCDATASection();
  KoXmlCDATASection( const KoXmlCDATASection& cdata );
  KoXmlCDATASection& operator=( const KoXmlCDATASection& cdata );
  virtual ~KoXmlCDATASection();

  virtual bool isCDATASection() const;

private:
  friend class KoXmlNode;
  friend class KoXmlDocument;
  KoXmlCDATASection( KoXmlNodeData* );
};

225 226 227 228 229 230 231 232
/**
 * KoXmlDocumentType represents the DTD of the document. At the moment,
 * it can used only to get the document type, i.e. no support for 
 * entities etc.
 *
 * @author Ariya Hidayat <ariya@kde.org>
 */

233
class KOSTORE_EXPORT KoXmlDocumentType: public KoXmlNode
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
{
public:
  KoXmlDocumentType();
  KoXmlDocumentType( const KoXmlDocumentType& );
  KoXmlDocumentType& operator=( const KoXmlDocumentType& );
  virtual ~KoXmlDocumentType();
  
  QString name() const;

private:
  friend class KoXmlNode;
  friend class KoXmlDocument;
  KoXmlDocumentType( KoXmlNodeData* );
};


250 251 252
/**
 * KoXmlDocument represents an XML document, structured in a DOM tree.
 *
253
 * KoXmlDocument is designed to be memory efficient. Unlike QDomDocument from 
254 255 256 257 258 259 260 261
 * Qt's XML module, KoXmlDocument does not store all nodes in the DOM tree.
 * Some nodes will be loaded and parsed on-demand only.
 *
 * KoXmlDocument is read-only, you can not modify its content.
 *
 * @author Ariya Hidayat <ariya@kde.org>
 */

262
class KOSTORE_EXPORT KoXmlDocument: public KoXmlNode
263 264 265 266 267 268 269 270 271 272
{
public:
  KoXmlDocument();
  KoXmlDocument( const KoXmlDocument& node );
  KoXmlDocument& operator=( const KoXmlDocument& node );
  bool operator==( const KoXmlDocument& ) const;
  bool operator!=( const KoXmlDocument& ) const;
  virtual ~KoXmlDocument();

  KoXmlElement documentElement() const;
273 274
  
  KoXmlDocumentType doctype() const;
275

276 277
  virtual QString nodeName() const;
  virtual void clear();
278

279
  bool setContent( QIODevice* device, bool namespaceProcessing, 
280
    QString* errorMsg = 0, int* errorLine = 0, int* errorColumn = 0 );
281
  bool setContent( QIODevice* device, 
282
    QString* errorMsg = 0, int* errorLine = 0, int* errorColumn = 0 );
283
  bool setContent( QXmlInputSource *source, QXmlReader *reader, 
284 285
    QString* errorMsg = 0, int* errorLine = 0, int* errorColumn = 0 );
  bool setContent( const QByteArray& text, bool namespaceProcessing,
286 287 288 289 290 291
    QString *errorMsg=0, int *errorLine=0, int *errorColumn=0  );    
  bool setContent( const QString& text, bool namespaceProcessing, 
    QString *errorMsg=0, int *errorLine=0, int *errorColumn=0  );
    
  // no namespace processing
  bool setContent( const QString& text, 
292
    QString *errorMsg=0, int *errorLine=0, int *errorColumn=0  );
293

294 295
private:
  friend class KoXmlNode;
296
  KoXmlDocumentType dt;
297 298 299 300 301
  KoXmlDocument( KoXmlNodeData* );
};

#endif // KOXML_USE_QDOM

302
class KOSTORE_EXPORT KoXmlInputSource: public QXmlInputSource
303 304
{
public:
305
  explicit KoXmlInputSource(QIODevice *dev);
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
  ~KoXmlInputSource();

  virtual void setData(const QString& dat);
  virtual void setData(const QByteArray& dat);
  virtual void fetchData();
  virtual QString data() const;
  virtual QChar next();
  virtual void reset();

protected:
  virtual QString fromRawData(const QByteArray &data, bool beginning = false);
    
private:
  QIODevice* device;
  QTextDecoder* decoder;
  QString stringData;
  int stringLength;
  int stringIndex;
  char* buffer;
};

327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362
/**
 * This namespace contains a few convenience functions to simplify code using QDom
 * (when loading OASIS documents, in particular).
 *
 * To find the child element with a given name, use KoXml::namedItemNS.
 *
 * To find all child elements with a given name, use
 * QDomElement e;
 * forEachElement( e, parent )
 * {
 *     if ( e.localName() == "..." && e.namespaceURI() == KoXmlNS::... )
 *     {
 *         ...
 *     }
 * }
 * Note that this means you don't ever need to use QDomNode nor toElement anymore!
 * Also note that localName is the part without the prefix, this is the whole point
 * of namespace-aware methods.
 *
 * To find the attribute with a given name, use QDomElement::attributeNS.
 *
 * Do not use getElementsByTagNameNS, it's recursive (which is never needed in KOffice).
 * Do not use tagName() or nodeName() or prefix(), since the prefix isn't fixed.
 *
 * @author David Faure <faure@kde.org>
 */
namespace KoXml {

    /**
     * A namespace-aware version of QDomNode::namedItem(),
     * which also takes care of casting to a QDomElement.
     * Use this when a domelement is known to have only *one* child element
     * with a given tagname.
     *
     * Note: do *NOT* use getElementsByTagNameNS, it's recursive!
     */
363
    KOSTORE_EXPORT KoXmlElement namedItemNS( const KoXmlNode& node, 
364 365 366 367 368 369
        const char* nsURI, const char* localName );

    /**
     * Explicitly load child nodes of specified node, up to given depth.
     * This function has no effect if QDom is used.
     */
370
    KOSTORE_EXPORT void load( KoXmlNode& node, int depth = 1 );
371 372 373 374 375

    /**
     * Unload child nodes of specified node.
     * This function has no effect if QDom is used.
     */
376
    KOSTORE_EXPORT void unload( KoXmlNode& node );
377 378 379 380
    
    /**
     * Get the number of child nodes of specified node.
     */
381
    KOSTORE_EXPORT int childNodesCount( const KoXmlNode& node );
382
    
383 384 385
    /**
     * Return the name of all attributes of specified node.
     */
386
    KOSTORE_EXPORT QStringList attributeNames( const KoXmlNode& node );
387
    
388 389 390 391
    /**
     * Convert KoXml classes to the corresponding QDom classes, which has 
     * 'ownerDoc' as the owner document (QDomDocument instance).     
     */
392 393 394
   	KOSTORE_EXPORT QDomNode asQDomNode( QDomDocument ownerDoc, const KoXmlNode& node );
   	KOSTORE_EXPORT QDomElement asQDomElement( QDomDocument ownerDoc, const KoXmlElement& element );
   	KOSTORE_EXPORT QDomDocument asQDomDocument( QDomDocument ownerDoc, const KoXmlDocument& document );
395 396 397 398 399 400 401 402 403 404

    /*
     * Load an XML document from specified device to a document. You can of 
     * course use it with QFile (which inherits QIODevice).     
     * This is much more memory efficient than standard QDomDocument::setContent
     * because the data from the device is buffered, unlike 
     * QDomDocument::setContent which just loads everything in memory.
     * 
     * Note: it is assumed that the XML uses UTF-8 encoding.	      
     */     
405
    KOSTORE_EXPORT bool setDocument( KoXmlDocument& doc, QIODevice* device,
406 407 408
      bool namespaceProcessing, QString* errorMsg = 0, 
	  int* errorLine = 0, int* errorColumn = 0 );

409
    KOSTORE_EXPORT bool setDocument( KoXmlDocument& doc, QIODevice* device,
410 411
      QXmlSimpleReader* reader, QString* errorMsg = 0, 
	  int* errorLine = 0, int* errorColumn = 0 );
412 413 414 415 416 417 418 419
}

#define forEachElement( elem, parent ) \
      for ( KoXmlNode _node = parent.firstChild(); !_node.isNull(); _node = _node.nextSibling() ) \
        if ( !( elem = _node.toElement() ).isNull() )


#endif // KOFFICE_XMLREADER