XmlElement.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the Water library.
   Copyright (c) 2016 ROLI Ltd.
   Copyright (C) 2017-2022 Filipe Coelho <falktx@falktx.com>
 
   Permission is granted to use this software under the terms of the ISC license
   http://www.isc.org/downloads/software-support-policy/isc-license/
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
   copyright notice and this permission notice appear in all copies.
 
   THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
   TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
   FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
   OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
   USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
   TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
   OF THIS SOFTWARE.
 
  ==============================================================================
*/
 
#ifndef WATER_XMLELEMENT_H_INCLUDED
#define WATER_XMLELEMENT_H_INCLUDED
 
#include "../containers/LinkedListPointer.h"
#include "../memory/HeapBlock.h"
#include "../text/Identifier.h"
 
namespace water {
 
//==============================================================================
#define __forEachXmlChildElement(parentXmlElement, childElementVariableName) \
\
    for (water::XmlElement* childElementVariableName = (parentXmlElement).getFirstChildElement(); \
         childElementVariableName != nullptr; \
         childElementVariableName = childElementVariableName->getNextElement())

#define __forEachXmlChildElementWithTagName(parentXmlElement, childElementVariableName, requiredTagName) \
\
    for (water::XmlElement* childElementVariableName = (parentXmlElement).getChildByName (requiredTagName); \
         childElementVariableName != nullptr; \
         childElementVariableName = childElementVariableName->getNextElementWithTagName (requiredTagName))
 
 
//==============================================================================
class XmlElement
{
public:
    //==============================================================================
    explicit XmlElement (const String& tagName);

    explicit XmlElement (const char* tagName);

    explicit XmlElement (const Identifier& tagName);

    explicit XmlElement (StringRef tagName);

    XmlElement (CharPointer_UTF8 tagNameBegin, CharPointer_UTF8 tagNameEnd);

    XmlElement (const XmlElement&);

    XmlElement& operator= (const XmlElement&);

    ~XmlElement() noexcept;
 
    //==============================================================================
    bool isEquivalentTo (const XmlElement* other,
                         bool ignoreOrderOfAttributes) const noexcept;
 
    //==============================================================================
    String createDocument (StringRef dtdToUse,
                           bool allOnOneLine = false,
                           bool includeXmlHeader = true,
                           StringRef encodingType = "UTF-8",
                           int lineWrapLength = 60) const;

    void writeToStream (OutputStream& output,
                        StringRef dtdToUse,
                        bool allOnOneLine = false,
                        bool includeXmlHeader = true,
                        StringRef encodingType = "UTF-8",
                        int lineWrapLength = 60) const;
 
#if 0
    bool writeToFile (const File& destinationFile,
                      StringRef dtdToUse,
                      StringRef encodingType = "UTF-8",
                      int lineWrapLength = 60) const;
#endif
 
    //==============================================================================
    const String& getTagName() const noexcept            { return tagName; }

    String getNamespace() const;

    String getTagNameWithoutNamespace() const;

    bool hasTagName (StringRef possibleTagName) const noexcept;

    bool hasTagNameIgnoringNamespace (StringRef possibleTagName) const;
 
    //==============================================================================
    int getNumAttributes() const noexcept;

    const std::string& getAttributeName (int attributeIndex) const noexcept;

    const String& getAttributeValue (int attributeIndex) const noexcept;
 
    //==============================================================================
    // Attribute-handling methods..

    bool hasAttribute (StringRef attributeName) const noexcept;

    const String& getStringAttribute (StringRef attributeName) const noexcept;

    String getStringAttribute (StringRef attributeName, const String& defaultReturnValue) const;

    bool compareAttribute (StringRef attributeName,
                           StringRef stringToCompareAgainst,
                           bool ignoreCase = false) const noexcept;

    int getIntAttribute (StringRef attributeName, int defaultReturnValue = 0) const;

    double getDoubleAttribute (StringRef attributeName, double defaultReturnValue = 0.0) const;

    bool getBoolAttribute (StringRef attributeName, bool defaultReturnValue = false) const;

    void setAttribute (const Identifier& attributeName, const String& newValue);

    void setAttribute (const Identifier& attributeName, int newValue);

    void setAttribute (const Identifier& attributeName, double newValue);

    void removeAttribute (const Identifier& attributeName) noexcept;

    void removeAllAttributes() noexcept;
 
    //==============================================================================
    // Child element methods..

    XmlElement* getFirstChildElement() const noexcept       { return firstChildElement; }

    inline XmlElement* getNextElement() const noexcept          { return nextListItem; }

    XmlElement* getNextElementWithTagName (StringRef requiredTagName) const;

    int getNumChildElements() const noexcept;

    XmlElement* getChildElement (int index) const noexcept;

    XmlElement* getChildByName (StringRef tagNameToLookFor) const noexcept;

    XmlElement* getChildByAttribute (StringRef attributeName,
                                     StringRef attributeValue) const noexcept;
 
    //==============================================================================
    void addChildElement (XmlElement* newChildElement) noexcept;

    void insertChildElement (XmlElement* newChildElement,
                             int indexToInsertAt) noexcept;

    void prependChildElement (XmlElement* newChildElement) noexcept;

    XmlElement* createNewChildElement (StringRef tagName);

    bool replaceChildElement (XmlElement* currentChildElement,
                              XmlElement* newChildNode) noexcept;

    void removeChildElement (XmlElement* childToRemove,
                             bool shouldDeleteTheChild) noexcept;

    void deleteAllChildElements() noexcept;

    void deleteAllChildElementsWithTagName (StringRef tagName) noexcept;

    bool containsChildElement (const XmlElement* possibleChild) const noexcept;

    XmlElement* findParentElementOf (const XmlElement* childToSearchFor) noexcept;
 
    //==============================================================================
    bool isTextElement() const noexcept;

    const String& getText() const noexcept;

    void setText (const String& newText);

    String getAllSubText() const;

    String getChildElementAllSubText (StringRef childTagName,
                                      const String& defaultReturnValue) const;

    void addTextElement (const String& text);

    void deleteAllTextElements() noexcept;

    static XmlElement* createTextElement (const String& text);

    static bool isValidXmlName (StringRef possibleName) noexcept;
 
    //==============================================================================
private:
    struct XmlAttributeNode
    {
        XmlAttributeNode (const XmlAttributeNode&) noexcept;
        XmlAttributeNode (const Identifier&, const String&) noexcept;
        XmlAttributeNode (CharPointer_UTF8, CharPointer_UTF8);
 
        LinkedListPointer<XmlAttributeNode> nextListItem;
        Identifier name;
        String value;
 
    private:
        XmlAttributeNode& operator= (const XmlAttributeNode&) WATER_DELETED_FUNCTION;
    };
 
    friend class XmlDocument;
    friend class LinkedListPointer<XmlAttributeNode>;
    friend class LinkedListPointer<XmlElement>;
    friend class LinkedListPointer<XmlElement>::Appender;
    friend class NamedValueSet;
 
    LinkedListPointer<XmlElement> nextListItem;
    LinkedListPointer<XmlElement> firstChildElement;
    LinkedListPointer<XmlAttributeNode> attributes;
    String tagName;
 
    XmlElement (int) noexcept;
    void copyChildrenAndAttributesFrom (const XmlElement&);
    void writeElementAsText (OutputStream&, int indentationLevel, int lineWrapLength) const;
    void getChildElementsAsArray (XmlElement**) const noexcept;
    void reorderChildElements (XmlElement**, int) noexcept;
    XmlAttributeNode* getAttribute (StringRef) const noexcept;
};
 
}
 
#endif // WATER_XMLELEMENT_H_INCLUDED