Syndication

elementwrapper.h
1 /*
2  This file is part of the syndication library
3  SPDX-FileCopyrightText: 2006 Frank Osterfeld <[email protected]>
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  */
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 
272 private:
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-2021 The KDE developers.
Generated on Sat Oct 16 2021 23:04:27 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.