File indexing completed on 2024-04-21 04:52:32
0001 /* 0002 SPDX-FileCopyrightText: 2017 Nicolas Carion 0003 SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-KDE-Accepted-GPL 0004 */ 0005 0006 #pragma once 0007 0008 #include "definitions.h" 0009 #include <QDomElement> 0010 #include <QString> 0011 #include <QVector> 0012 #include <unordered_map> 0013 0014 /** @brief This static class provides helper functions to manipulate Dom objects easily 0015 */ 0016 namespace Xml { 0017 0018 /** @brief Set the content of the given @param doc from a file. 0019 * 0020 * It makes sure that the file is open for reading as required by Qt in the future (as of Qt5 2022-10-08) 0021 * 0022 * @param doc 0023 * @param fileName 0024 * @param namespaceProcessing parameter of QDomDocument::setContent(). If namespaceProcessing is true, the parser recognizes namespaces in the XML file and 0025 * sets the prefix name, local name and namespace URI to appropriate values. If namespaceProcessing is false, the parser does no namespace processing when it 0026 * reads the XML file. 0027 * 0028 * @returns false if an error occurred while reading or parsing the file to the document 0029 */ 0030 bool docContentFromFile(QDomDocument &doc, const QString &fileName, bool namespaceProcessing); 0031 0032 /** @brief Write the content of the given @param doc from to file. 0033 * 0034 * It makes sure that the file is open for writing 0035 * 0036 * @param doc 0037 * @param fileName 0038 * 0039 * @returns false if an error occurred while writing the document to the file 0040 */ 0041 bool docContentToFile(const QDomDocument &doc, const QString &fileName); 0042 0043 /** @brief Returns the content of a given tag within the current DomElement. 0044 For example, if your \@param element looks like <html><title>foo</title><head>bar</head></html>, passing \@tagName = "title" will return foo, and \@tagName 0045 = "head" returns bar 0046 Returns empty string if tag is not found. 0047 */ 0048 QString getSubTagContent(const QDomElement &element, const QString &tagName); 0049 0050 /** @brief Returns the direct children of given \@element whose tag name matches given \@param tagName. 0051 This is an alternative to QDomElement::elementsByTagName which returns also non-direct children 0052 */ 0053 QVector<QDomNode> getDirectChildrenByTagName(const QDomElement &element, const QString &tagName); 0054 0055 /** @brief Returns the content of a children tag of \@param element, which respects the following conditions : 0056 - Its type is \@param tagName 0057 - It as an attribute named \@param attribute with value \@param value 0058 0059 For example, if your element is <html><param val="foo">bar</param></html>, you can retrieve "bar" with parameters: tagName="param", attribute="val", and 0060 value="foo" Returns \@param defaultReturn when nothing is found. The methods returns the first match found, so make sure there can't be more than one. If 0061 \@param directChildren is true, only immediate children of the node are considered 0062 */ 0063 QString getTagContentByAttribute(const QDomElement &element, const QString &tagName, const QString &attribute, const QString &value, 0064 const QString &defaultReturn = QString(), bool directChildren = true); 0065 0066 /** @brief This is a specialization of getTagContentByAttribute with tagName = "property" and attribute = "name". 0067 That is, to match something like <elem><property name="foo">bar</property></elem>, pass propertyName = foo, and this will return bar 0068 */ 0069 QString getXmlProperty(const QDomElement &element, const QString &propertyName, const QString &defaultReturn = QString()); 0070 QString getXmlParameter(const QDomElement &element, const QString &propertyName, const QString &defaultReturn = QString()); 0071 0072 /** @brief Returns true if the element contains a named property 0073 */ 0074 bool hasXmlProperty(const QDomElement &element, const QString &propertyName); 0075 bool hasXmlParameter(const QDomElement &element, const QString &propertyName); 0076 0077 /** @brief Add properties to the given xml element 0078 For each element (n, v) in the properties map, it creates a sub element of the form : <property name="n">v</property> 0079 @param producer is the xml element where to append properties 0080 @param properties is the map of properties 0081 */ 0082 void addXmlProperties(QDomElement &producer, const std::unordered_map<QString, QString> &properties); 0083 void addXmlProperties(QDomElement &producer, const QMap<QString, QString> &properties); 0084 /** @brief Edit or add a property 0085 */ 0086 void setXmlProperty(QDomElement element, const QString &propertyName, const QString &value); 0087 void setXmlParameter(const QDomElement &element, const QString &propertyName, const QString &value); 0088 /** @brief Remove a property 0089 */ 0090 void removeXmlProperty(QDomElement effect, const QString &name); 0091 void removeMetaProperties(QDomElement producer); 0092 0093 void renameXmlProperty(const QDomElement &effect, const QString &oldName, const QString &newName); 0094 0095 QMap<QString, QString> getXmlPropertyByWildcard(const QDomElement &element, const QString &propertyName); 0096 0097 } // namespace Xml