mirror of
https://bitbucket.org/smil3y/kde-extraapps.git
synced 2025-02-23 18:32:53 +00:00
301 lines
10 KiB
C++
301 lines
10 KiB
C++
/*
|
|
* This file is part of the syndication library
|
|
*
|
|
* Copyright (C) 2006 Frank Osterfeld <osterfeld@kde.org>
|
|
*
|
|
* 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,
|
|
* Boston, MA 02110-1301, USA.
|
|
*
|
|
*/
|
|
#ifndef SYNDICATION_ELEMENTWRAPPER_H
|
|
#define SYNDICATION_ELEMENTWRAPPER_H
|
|
|
|
#include <QtCore/QString>
|
|
|
|
#include <boost/shared_ptr.hpp>
|
|
|
|
#include "ksyndication_export.h"
|
|
|
|
#include <QDomElement>
|
|
#include <QList>
|
|
|
|
namespace Syndication {
|
|
|
|
/**
|
|
* A wrapper for XML elements. This is the base class for the (lazy) wrappers
|
|
* used in the RSS2 and Atom parsers. The wrapped element can be accessed
|
|
* via element(). It also contains several helper functions for XML processing.
|
|
*
|
|
* @author Frank Osterfeld
|
|
*/
|
|
class SYNDICATION_EXPORT ElementWrapper
|
|
{
|
|
public:
|
|
|
|
/**
|
|
* creates a element wrapper wrapping a null element.
|
|
* isNull() will return @c true for these instances.
|
|
*/
|
|
ElementWrapper();
|
|
|
|
/**
|
|
* Copy constructor.The instances share the same element.
|
|
* @param other the element wrapper to copy
|
|
*/
|
|
ElementWrapper(const ElementWrapper& other);
|
|
|
|
/**
|
|
* Creates an element wrapper wrapping the DOM element @c element
|
|
* @param element the element to wrap
|
|
*/
|
|
ElementWrapper(const QDomElement& element); // implicit
|
|
|
|
/**
|
|
* destructor
|
|
*/
|
|
virtual ~ElementWrapper();
|
|
|
|
/**
|
|
* Assigns another element wrapper to this one. Both instances
|
|
* share the same wrapped element instance.
|
|
*
|
|
* @param other the element wrapper to assign
|
|
* @return reference to this instance
|
|
*/
|
|
ElementWrapper& operator=(const ElementWrapper& other);
|
|
|
|
/**
|
|
* compares two wrappers. Two wrappers are equal if and only if
|
|
* the wrapped elements are equal.
|
|
* @param other another element wrapper to compare to
|
|
*/
|
|
bool operator==(const ElementWrapper& other) const;
|
|
|
|
/**
|
|
* returns the wrapped resource.
|
|
*/
|
|
const QDomElement& element() const;
|
|
|
|
/**
|
|
* returns whether the wrapped element is a null element
|
|
* @return @c true if isNull() is true for the wrapped element,
|
|
* @c false otherwise
|
|
*/
|
|
bool isNull() const;
|
|
|
|
/**
|
|
* returns the xml:base value to be used for the wrapped element.
|
|
* The xml:base attribute establishes the base URI for resolving any
|
|
* relative references found in its scope (its own element and all
|
|
* descendants). (See also completeURI())
|
|
*
|
|
* @return the xml:base value, or a null string if not set
|
|
*/
|
|
QString xmlBase() const;
|
|
|
|
/**
|
|
* returns the xml:lang value to be used for the wrapped element.
|
|
* The xml:lang attribute indicates the natural language for its element
|
|
* and all descendants.
|
|
*
|
|
* @return the xml:lang value, or a null string if not set
|
|
*/
|
|
QString xmlLang() const;
|
|
|
|
/**
|
|
* completes relative URIs with a prefix specified via xml:base.
|
|
*
|
|
* Example:
|
|
* @code
|
|
* xml:base="http://www.foo.org/", uri="announcements/bar.html"
|
|
* @endcode
|
|
*
|
|
* is completed to @c http://www.foo.org/announcements/bar.html
|
|
*
|
|
* See also xmlBase().
|
|
*
|
|
* @param uri a possibly relative URI
|
|
* @return the resolved, absolute URI (using xml:base), if @c uri is
|
|
* a relative, valid URI. If @c uri is not valid, absolute, or no
|
|
* xml:base is set in the scope of this element, @c uri is returned
|
|
* unmodified.
|
|
*/
|
|
QString completeURI(const QString& uri) const;
|
|
|
|
/**
|
|
* extracts the text from a child element, respecting namespaces. If
|
|
* there is more than one child with the same tag name, the first one is
|
|
* processed.
|
|
* For instance, when the wrapped element is @c <hisElement>:
|
|
* @code
|
|
* <thisElement>
|
|
* <atom:title>Hi there</atom:title>
|
|
* </thisElement>
|
|
* @endcode
|
|
* @code
|
|
* extractElementText("http://www.w3.org/2005/Atom", "title")
|
|
* @endcode
|
|
* will return the text content of @c atom:title, "Hi there".
|
|
* (Assuming that "atom" is defined as "http://www.w3.org/2005/Atom")
|
|
*
|
|
* @param namespaceURI the namespace URI of the element to extract
|
|
* @param localName the local name (local within its namespace) of the
|
|
* element to extract
|
|
* @return the (trimmed) text content of @c localName, or a null string
|
|
* if there is no such tag
|
|
*/
|
|
|
|
QString extractElementTextNS(const QString& namespaceURI,
|
|
const QString& localName) const;
|
|
|
|
/**
|
|
* extracts the text from a child element, ignoring namespaces. For
|
|
* instance, when the wrapped element is @c <thisElement>:
|
|
* @code
|
|
* <thisElement>
|
|
* <title>Hi there</title>
|
|
* </thisElement>
|
|
* @endcode
|
|
* @c extractElementText("title") will return the text content
|
|
* of @c title, "Hi there".
|
|
*
|
|
* @param tagName the name of the element to extract
|
|
* @return the (trimmed) text content of @c tagName, or a null string if
|
|
* there is no such tag
|
|
*/
|
|
QString extractElementText(const QString& tagName) const;
|
|
|
|
/**
|
|
* returns all child elements with tag name @c tagName
|
|
* Contrary to QDomElement::elementsByTagName() only direct descendents
|
|
* are returned.
|
|
*
|
|
* @param tagName the tag name of the elements to extract
|
|
* @return a list of child elements with the given tag name
|
|
*/
|
|
QList<QDomElement> elementsByTagName(const QString& tagName) const;
|
|
|
|
/**
|
|
* returns the child nodes of the wrapped element as XML.
|
|
*
|
|
* See childNodesAsXML(const QDomElement& parent) for details
|
|
* @return XML serialization of the wrapped element's children
|
|
*/
|
|
QString childNodesAsXML() const;
|
|
|
|
/**
|
|
* concatenates the XML representations of all children. Example: If
|
|
* @c parent is an @c xhtml:body element like
|
|
* @code
|
|
* <xhtml:body><p>foo</p><blockquote>bar</blockquote></xhtml:body>
|
|
* @endcode
|
|
* this function returns
|
|
* @code
|
|
* <p>foo</p><blockquote>bar</blockquote>
|
|
* @endcode
|
|
*
|
|
* namespace and xml:base information are preserved.
|
|
*
|
|
* @param parent the DOM element whose children should be returned as
|
|
* XML
|
|
* @return XML serialization of parent's children
|
|
*/
|
|
static QString childNodesAsXML(const QDomElement& parent);
|
|
|
|
/**
|
|
* returns all child elements with tag name @c tagname
|
|
* and namespace URI @c nsURI.
|
|
* Contrary to QDomElement::elementsByTagNameNS() only direct
|
|
* descendents are returned
|
|
*
|
|
* @param nsURI the namespace URI
|
|
* @param tagName the local name (local within its namespace) of the
|
|
* element to search for
|
|
* @return a list of child elements with the given namespace URI
|
|
* and tag name
|
|
*/
|
|
QList<QDomElement> elementsByTagNameNS(const QString& nsURI,
|
|
const QString& tagName) const;
|
|
|
|
/**
|
|
* searches the direct children of the wrapped element for an element
|
|
* with a given namespace and tag name.
|
|
*
|
|
* @param nsURI the namespace URI
|
|
* @param tagName the local name (local within its namespace) of the
|
|
* element to search for
|
|
* @return the first child element with the given namespace URI and tag
|
|
* name, or a null element if no such element was found.
|
|
*/
|
|
QDomElement firstElementByTagNameNS(const QString& nsURI,
|
|
const QString& tagName) const;
|
|
|
|
/**
|
|
* Returns the wrapped element's text or an empty string.
|
|
* For more information, see QDomElement::text();
|
|
*/
|
|
QString text() const;
|
|
|
|
/**
|
|
* Returns the attribute called name. If the attribute does not exist
|
|
* defValue is returned.
|
|
* (which is a null string by default).
|
|
*
|
|
* @param name tag name
|
|
* @param defValue the default value
|
|
*/
|
|
QString attribute(const QString& name,
|
|
const QString& defValue=QString()) const;
|
|
|
|
/**
|
|
* Returns the attribute with the local @c name localName and the
|
|
* namespace URI @c nsURI.
|
|
* If the attribute does not exist @c defValue is returned (which is a
|
|
* null string by default).
|
|
*
|
|
* @param nsURI namespace URI
|
|
* @param localName local tag name
|
|
* @param defValue the default value
|
|
*/
|
|
QString attributeNS(const QString& nsURI, const QString& localName,
|
|
const QString& defValue=QString()) const;
|
|
|
|
|
|
/**
|
|
* Returns true if this element has an attribute called @c name;
|
|
* otherwise returns @c false.
|
|
*
|
|
* @param name the attribute name (without namespace)
|
|
*/
|
|
bool hasAttribute(const QString& name) const;
|
|
|
|
/**
|
|
* Returns true if this element has an attribute with the local name
|
|
* localName and the namespace URI nsURI; otherwise returns false.
|
|
*
|
|
* @param nsURI namespace URI
|
|
* @param localName local attribute name
|
|
*/
|
|
bool hasAttributeNS(const QString& nsURI, const QString& localName) const;
|
|
|
|
private:
|
|
|
|
class ElementWrapperPrivate;
|
|
boost::shared_ptr<ElementWrapperPrivate> d;
|
|
};
|
|
|
|
} // namespace Syndication
|
|
|
|
#endif // SYNDICATION_ELEMENTWRAPPER_H
|