Syndication

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

KDE's Doxygen guidelines are available online.