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 | |
16 | class QDomElement; |
17 | template<class T> |
18 | class QList; |
19 | |
20 | namespace 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 | */ |
29 | class SYNDICATION_EXPORT ElementWrapper |
30 | { |
31 | public: |
32 | /** |
33 | * creates a element wrapper wrapping a null element. |
34 | * isNull() will return @c true for these instances. |
35 | */ |
36 | ElementWrapper(); |
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 <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 <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 | |
272 | private: |
273 | class ElementWrapperPrivate; |
274 | QSharedPointer<ElementWrapperPrivate> d; |
275 | }; |
276 | |
277 | } // namespace Syndication |
278 | |
279 | #endif // SYNDICATION_ELEMENTWRAPPER_H |
280 | |