1/*
2 This file is part of the syndication library
3 SPDX-FileCopyrightText: 2006 Frank Osterfeld <osterfeld@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef SYNDICATION_ELEMENTWRAPPER_H
9#define SYNDICATION_ELEMENTWRAPPER_H
10
11#include <QSharedPointer>
12#include <QString>
13
14#include "syndication_export.h"
15
16class QDomElement;
17template<class T>
18class QList;
19
20namespace Syndication
21{
22/*!
23 * \class Syndication::ElementWrapper
24 * \inmodule Syndication
25 * \inheaderfile Syndication/ElementWrapper
26 *
27 * \brief A wrapper for XML elements.
28 *
29 * This is the base class for the (lazy) wrappers
30 * used in the RSS2 and Atom parsers. The wrapped element can be accessed
31 * via element(). It also contains several helper functions for XML processing.
32 */
33class SYNDICATION_EXPORT ElementWrapper
34{
35public:
36 /*!
37 * Creates a element wrapper wrapping a null element.
38 * isNull() will return \c true for these instances.
39 */
40 ElementWrapper();
41
42 /*!
43 * Copy constructor. The instances share the same element.
44 *
45 * \a other the element wrapper to copy
46 */
47 ElementWrapper(const ElementWrapper &other);
48
49 /*!
50 * Creates an element wrapper wrapping the DOM element \a element
51 *
52 * \a element the element to wrap
53 */
54 ElementWrapper(const QDomElement &element); // implicit
55
56 virtual ~ElementWrapper();
57
58 /*!
59 * Assigns another element wrapper to this one. Both instances
60 * share the same wrapped element instance.
61 *
62 * \a other the element wrapper to assign
63 *
64 * Returns reference to this instance
65 */
66 ElementWrapper &operator=(const ElementWrapper &other);
67
68 /*!
69 * Compares two wrappers.
70 *
71 * Two wrappers are equal if and only if
72 * the wrapped elements are equal.
73 *
74 * \a other another element wrapper to compare to
75 */
76 bool operator==(const ElementWrapper &other) const;
77
78 /*!
79 * returns the wrapped resource.
80 */
81 const QDomElement &element() const;
82
83 /*!
84 * Returns \c true if isNull() is true for the wrapped element,
85 * \c false otherwise
86 */
87 Q_REQUIRED_RESULT bool isNull() const;
88
89 /*!
90 * Returns the xml:base value to be used for the wrapped element.
91 *
92 * The xml:base attribute establishes the base URI for resolving any
93 * relative references found in its scope (its own element and all
94 * descendants). (See also completeURI())
95 */
96 Q_REQUIRED_RESULT QString xmlBase() const;
97
98 /*!
99 * Returns the xml:lang value to be used for the wrapped element.
100 *
101 * The xml:lang attribute indicates the natural language for its element
102 * and all descendants.
103 */
104 Q_REQUIRED_RESULT QString xmlLang() const;
105
106 /*!
107 * Completes relative URIs with a prefix specified via xml:base.
108 *
109 * Example:
110 * \code
111 * xml:base="http://www.foo.org/", uri="announcements/bar.html"
112 * \endcode
113 *
114 * is completed to \c http://www.foo.org/announcements/bar.html
115 *
116 * See also xmlBase().
117 *
118 * \a uri a possibly relative URI
119 *
120 * Returns the resolved, absolute URI (using xml:base), if \a uri is
121 * a relative, valid URI.
122 *
123 * If \a uri is not valid, absolute, or no
124 * xml:base is set in the scope of this element, \a uri is returned
125 * unmodified.
126 */
127 Q_REQUIRED_RESULT QString completeURI(const QString &uri) const;
128
129 /*!
130 * Extracts the text from a child element, respecting namespaces.
131 * If there is more than one child with the same tag name, the first one is
132 * processed.
133 *
134 * For instance, when the wrapped element is \c <thisElement>:
135 * \badcode
136 * <thisElement>
137 * <atom:title>Hi there</atom:title>
138 * </thisElement>
139 * \endcode
140 * \code
141 * extractElementText("http://www.w3.org/2005/Atom", "title")
142 * \endcode
143 * will return the text content of \c atom:title, "Hi there".
144 * (Assuming that "atom" is defined as "http://www.w3.org/2005/Atom")
145 *
146 * \a namespaceURI the namespace URI of the element to extract
147 *
148 * \a localName the local name (local within its namespace) of the
149 * element to extract
150 *
151 * Returns the (trimmed) text content of \c localName, or a null string
152 * if there is no such tag
153 */
154 Q_REQUIRED_RESULT QString extractElementTextNS(const QString &namespaceURI, const QString &localName) const;
155
156 /*!
157 * Extracts the text from a child element, ignoring namespaces.
158 * For instance, when the wrapped element is \c <thisElement>:
159 * \badcode
160 * <thisElement>
161 * <title>Hi there</title>
162 * </thisElement>
163 * \endcode
164 *
165 * extractElementText("title") will return the text content
166 * of \c title, "Hi there".
167 *
168 * \a tagName the name of the element to extract
169 *
170 * Returns the (trimmed) text content of \a tagName, or a null string if
171 * there is no such tag
172 */
173 Q_REQUIRED_RESULT QString extractElementText(const QString &tagName) const;
174
175 /*!
176 * Returns all child elements with tag name \a tagName
177 *
178 * Contrary to QDomElement::elementsByTagName() only direct descendents
179 * are returned.
180 *
181 * \a tagName the tag name of the elements to extract
182 *
183 * Returns a list of child elements with the given tag name
184 */
185 Q_REQUIRED_RESULT QList<QDomElement> elementsByTagName(const QString &tagName) const;
186
187 /*!
188 * Returns the child nodes of the wrapped element as XML.
189 *
190 * See childNodesAsXML(const QDomElement& parent) for details
191 *
192 * Returns XML serialization of the wrapped element's children
193 */
194 Q_REQUIRED_RESULT QString childNodesAsXML() const;
195
196 /*!
197 * Concatenates the XML representations of all children.
198 *
199 * Example: If \a parent is an \c xhtml:body element like
200 * \badcode
201 * <xhtml:body><p>foo</p><blockquote>bar</blockquote></xhtml:body>
202 * \endcode
203 * this function returns
204 * \badcode
205 * <p>foo</p><blockquote>bar</blockquote>
206 * \endcode
207 *
208 * namespace and xml:base information are preserved.
209 *
210 * \a parent the DOM element whose children should be returned as
211 * XML
212 *
213 * Returns XML serialization of parent's children
214 */
215 Q_REQUIRED_RESULT static QString childNodesAsXML(const QDomElement &parent);
216
217 /*!
218 * Returns all child elements with tag name \a tagName
219 * and namespace URI \a nsURI.
220 *
221 * Contrary to QDomElement::elementsByTagNameNS() only direct
222 * descendents are returned
223 *
224 * \a nsURI the namespace URI
225 *
226 * \a tagName the local name (local within its namespace) of the
227 * element to search for
228 *
229 * Returns a list of child elements with the given namespace URI
230 * and tag name
231 */
232 Q_REQUIRED_RESULT QList<QDomElement> elementsByTagNameNS(const QString &nsURI, const QString &tagName) const;
233
234 /*!
235 * Searches the direct children of the wrapped element for an element
236 * with a given namespace and tag name.
237 *
238 * \a nsURI the namespace URI
239 *
240 * \a tagName the local name (local within its namespace) of the
241 * element to search for
242 *
243 * Returns the first child element with the given namespace URI and tag
244 * name, or a null element if no such element was found.
245 */
246 Q_REQUIRED_RESULT QDomElement firstElementByTagNameNS(const QString &nsURI, const QString &tagName) const;
247
248 /*!
249 * Returns the wrapped element's text or an empty string.
250 *
251 * For more information, see QDomElement::text();
252 */
253 Q_REQUIRED_RESULT QString text() const;
254
255 /*!
256 * Returns the attribute called name.
257 *
258 * If the attribute does not exist
259 * defValue is returned.
260 * (which is a null string by default).
261 *
262 * \a name tag name
263 *
264 * \a defValue the default value
265 */
266 Q_REQUIRED_RESULT QString attribute(const QString &name, const QString &defValue = QString()) const;
267
268 /*!
269 * Returns the attribute with the local name \a localName and the
270 * namespace URI \a nsURI.
271 *
272 * If the attribute does not exist \a defValue is returned (which is a
273 * null string by default).
274 *
275 * \a nsURI namespace URI
276 *
277 * \a localName local tag name
278 *
279 * \a defValue the default value
280 */
281 Q_REQUIRED_RESULT QString attributeNS(const QString &nsURI, const QString &localName, const QString &defValue = QString()) const;
282
283 /*!
284 * Returns \c true if this element has an attribute called \a name;
285 * otherwise returns \c false.
286 *
287 * \a name the attribute name (without namespace)
288 */
289 Q_REQUIRED_RESULT bool hasAttribute(const QString &name) const;
290
291 /*!
292 * Returns \c true if this element has an attribute with the local name
293 * \a localName and the namespace URI \a nsURI; otherwise returns \c false.
294 *
295 * \a nsURI namespace URI
296 *
297 * \a localName local attribute name
298 */
299 Q_REQUIRED_RESULT bool hasAttributeNS(const QString &nsURI, const QString &localName) const;
300
301private:
302 class ElementWrapperPrivate;
303 QSharedPointer<ElementWrapperPrivate> d;
304};
305
306} // namespace Syndication
307
308#endif // SYNDICATION_ELEMENTWRAPPER_H
309

source code of syndication/src/elementwrapper.h