XMLDom.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 by
 *   MetraLabs GmbH (MLAB), GERMANY
 * and
 *   Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
 * All rights reserved.
 *
 * Contact: info@mira-project.org
 *
 * Commercial Usage:
 *   Licensees holding valid commercial licenses may use this file in
 *   accordance with the commercial license agreement provided with the
 *   software or, alternatively, in accordance with the terms contained in
 *   a written agreement between you and MLAB or NICR.
 *
 * GNU General Public License Usage:
 *   Alternatively, this file may be used under the terms of the GNU
 *   General Public License version 3.0 as published by the Free Software
 *   Foundation and appearing in the file LICENSE.GPL3 included in the
 *   packaging of this file. Please review the following information to
 *   ensure the GNU General Public License version 3.0 requirements will be
 *   met: http://www.gnu.org/copyleft/gpl.html.
 *   Alternatively you may (at your option) use any later version of the GNU
 *   General Public License if such license has been publicly approved by
 *   MLAB and NICR (or its successors, if any).
 *
 * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
 * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
 * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
 */

#ifndef _MIRA_XMLDOM_H_
#define _MIRA_XMLDOM_H_

#include <iostream>
#include <string>
#ifndef Q_MOC_RUN
#include <boost/noncopyable.hpp>
#endif

#include <error/Exceptions.h>
#include <platform/Types.h>
#include <utils/Path.h>
#include <utils/ToString.h>

struct _xmlNode;
struct _xmlAttr;
struct _xmlDoc;
struct _xmlNs;

namespace mira {


class XMLDom : boost::noncopyable
{
private:
    enum
    {
        TEXT_NODE,
        COMMENT_NODE
    };
public:

    typedef std::pair<std::string, std::string> Attribute;

    struct NameSpace
    {
        NameSpace() {}
        NameSpace(const std::string& p, const std::string& h="") :
            prefix(p),
            href(h) {}

        std::string prefix;
        std::string href;
    };


public:

    // forward decl.
    class sibling_iterator;
    class const_sibling_iterator;

    static constexpr size_t npos = std::numeric_limits<size_t>::max();

    class const_attribute_iterator
    {
    public:
        typedef std::string value_type;
        typedef const std::string* pointer;
        typedef const std::string& reference;
        typedef ptrdiff_t difference_type;
        typedef std::bidirectional_iterator_tag iterator_category;

        const_attribute_iterator();

        const_attribute_iterator(_xmlNode* iNode, _xmlAttr* iAttribute);

        bool operator==(const const_attribute_iterator& other) const;
        bool operator!=(const const_attribute_iterator& other) const;
        const_attribute_iterator& operator++();
        const_attribute_iterator& operator--();

        Attribute operator*() const;
        std::string name() const;
        std::string value() const;
        NameSpace nameSpace() const;

    private:
        _xmlNode* mNode;
        _xmlAttr* mAttribute;
    };

    class attribute_iterator
    {
    public:
        typedef std::string value_type;
        typedef std::string* pointer;
        typedef std::string& reference;
        typedef ptrdiff_t difference_type;
        typedef std::bidirectional_iterator_tag iterator_category;

        attribute_iterator();

        attribute_iterator(_xmlNode* iNode, _xmlAttr* iAttribute);

        const attribute_iterator& operator=(const std::string& value);
        bool operator==(const attribute_iterator& other) const;
        bool operator!=(const attribute_iterator& other) const;
        attribute_iterator& operator++();
        attribute_iterator& operator--();

        Attribute operator*() const;
        std::string name() const;
        std::string value() const;
        NameSpace nameSpace() const;

    private:
        friend class sibling_iterator; // sibling_iterator needs direct access on in remove

        _xmlNode* mNode;
        _xmlAttr* mAttribute;
    };

    class namespace_iterator
    {
    public:
        using value_type = std::string;
        using pointer = std::string *;
        using reference = std::string &;
        using difference_type = ptrdiff_t;
        using iterator_category = std::bidirectional_iterator_tag;

        namespace_iterator() = default;

        namespace_iterator(_xmlNs* ns) : mNamespace(ns) {}

        namespace_iterator& operator++();

        bool operator==(const namespace_iterator& other) const;
        bool operator!=(const namespace_iterator& other) const;

        [[nodiscard]] std::string prefix() const;
        [[nodiscard]] std::string href() const;

    private:
        _xmlNs* mNamespace = nullptr;
    };

    template <int Type>
    class const_data_iterator
    {
    public:
        typedef std::string value_type;
        typedef const std::string* pointer;
        typedef const std::string& reference;
        typedef ptrdiff_t difference_type;
        typedef std::bidirectional_iterator_tag iterator_category;

        const_data_iterator();

        const_data_iterator(_xmlNode* iNode);

        uint32 line() const;

        size_t position() const;

        bool operator==(const const_data_iterator& other) const;
        bool operator!=(const const_data_iterator& other) const;
        const_data_iterator& operator++();
        const_data_iterator& operator--();

        std::string operator*() const;

    private:

        friend class sibling_iterator;
        _xmlNode* mNode;
    };

    template <int Type>
    class data_iterator
    {
    public:
        typedef std::string value_type;
        typedef std::string* pointer;
        typedef std::string& reference;
        typedef ptrdiff_t difference_type;
        typedef std::bidirectional_iterator_tag iterator_category;


        data_iterator();

        data_iterator(_xmlNode* iNode);

        const data_iterator& operator=(const std::string& value);
        bool operator==(const data_iterator& other) const;
        bool operator!=(const data_iterator& other) const;
        data_iterator& operator++();
        data_iterator& operator--();

        std::string operator*() const;

        data_iterator remove();

    private:
        _xmlNode* mNode;
    };

    typedef const_data_iterator<COMMENT_NODE> const_comment_iterator;
    typedef const_data_iterator<TEXT_NODE> const_content_iterator;
    typedef data_iterator<COMMENT_NODE> comment_iterator;
    typedef data_iterator<TEXT_NODE> content_iterator;

    class iterator_base
    {
    public:
        iterator_base(_xmlNode* node, const std::string& name);
        std::string operator*() const;

        void setName(const std::string& name);

        std::string uri() const;

        void setUri(const std::string& uri);

        NameSpace nameSpace() const;

        uint32 line() const;

        size_t position() const;

        const_sibling_iterator cparent() const;
        const_sibling_iterator parent() const { return cparent(); }
        const_sibling_iterator cbegin() const;
        const_sibling_iterator begin() const { return cbegin(); }
        const_sibling_iterator cbegin(const std::string& name) const;
        const_sibling_iterator begin(const std::string& name) const {
            return cbegin(name);
        }
        const_sibling_iterator cend() const;
        const_sibling_iterator end() const { return cend(); }
        const_content_iterator content_cbegin() const;
        const_content_iterator content_cend() const;
        const_content_iterator content_begin() const { return content_cbegin(); }
        const_content_iterator content_end() const { return content_cend(); }

        const_comment_iterator comment_cbegin() const;
        const_comment_iterator comment_cend() const;
        const_comment_iterator comment_begin() const { return comment_cbegin(); }
        const_comment_iterator comment_end() const { return comment_cend(); }

        const_attribute_iterator attribute_cbegin() const;
        const_attribute_iterator attribute_cend() const;
        const_attribute_iterator attribute_begin() const 
        {
            return attribute_cbegin(); 
        }
        const_attribute_iterator attribute_end() const 
        {
            return attribute_cend(); 
        }
        const_attribute_iterator find_attribute(const std::string& name) const;
        bool has_attribute(const std::string& name) const
        {
            return find_attribute(name) != attribute_end();
        }
        template <typename T>
        T get_attribute(const std::string& name) const
        {
            const_attribute_iterator a = find_attribute(name);
            if ( a == attribute_end() )
                MIRA_THROW(XInvalidConfig, "The attribute '" << name
                           << "' could not be found in node '" << *(*this) << "'");
            return fromString<T>((*a).second);
        }

        template <typename T>
        T get_attribute(const std::string& name, const T& defaultValue) const
        {
            const_attribute_iterator a = find_attribute(name);
            if ( a == attribute_end() )
                return defaultValue;
            return fromString<T>((*a).second);
        }

        [[nodiscard]] namespace_iterator ns_begin() const;

        [[nodiscard]] namespace_iterator ns_end() const;

    protected:
        _xmlNode* mNode;
        std::string mName;
    };

    class const_sibling_iterator : public iterator_base
    {
    public:
        friend class sibling_iterator;
        typedef std::string value_type;
        typedef const std::string* pointer;
        typedef const std::string& reference;
        typedef ptrdiff_t difference_type;
        typedef std::bidirectional_iterator_tag iterator_category;

        const_sibling_iterator();
        const_sibling_iterator(_xmlNode* iNode, const std::string& name = "");

        const_sibling_iterator(const const_sibling_iterator& other) :
            iterator_base(other.mNode, other.mName)
        {
        }

        bool operator==(const const_sibling_iterator& other) const {
            return mNode == other.mNode;
        }
        bool operator!=(const const_sibling_iterator& other) const {
            return mNode != other.mNode;
        }
        const_sibling_iterator& operator++();
        const_sibling_iterator& operator+=(std::size_t increment);
        const_sibling_iterator operator+(std::size_t increment) const;
        const_sibling_iterator& operator--();

        const_sibling_iterator find(const std::string& name, std::size_t nth = 0) const;
    };

    class sibling_iterator : public iterator_base
    {
    public:
        typedef std::string value_type;
        typedef std::string* pointer;
        typedef std::string& reference;
        typedef ptrdiff_t difference_type;
        typedef std::bidirectional_iterator_tag iterator_category;

        sibling_iterator();
        sibling_iterator(_xmlNode* iNode, const std::string& name = "");

        sibling_iterator(const sibling_iterator& other) :
            iterator_base(other.mNode, other.mName)
        {
        }

        bool operator==(const sibling_iterator& other) const {
            return mNode == other.mNode;
        }
        bool operator!=(const sibling_iterator& other) const {
            return mNode != other.mNode;
        }

        operator const_sibling_iterator() const
        {
            return const_sibling_iterator(mNode, mName);
        }

        const sibling_iterator& operator=(const std::string& name);
        sibling_iterator& operator++();
        sibling_iterator& operator+=(std::size_t increment);
        sibling_iterator operator+(std::size_t increment) const;
        sibling_iterator& operator--();

        sibling_iterator parent();
        sibling_iterator begin();
        sibling_iterator begin(const std::string& name);
        sibling_iterator end();

        sibling_iterator find(const std::string& name, std::size_t nth = 0);

        content_iterator content_begin();
        content_iterator content_end();
        comment_iterator comment_begin();
        comment_iterator comment_end();
        attribute_iterator attribute_begin();
        attribute_iterator attribute_end();
        attribute_iterator find_attribute(const std::string& name);
        XMLDom::sibling_iterator& add_attribute(const Attribute& attribute);
        XMLDom::sibling_iterator& add_attribute(const std::string& name,
                                        const std::string& value);
        template <typename T>
        XMLDom::sibling_iterator& add_attribute(const std::string& name, const T& value)
        {
            return add_attribute(name, toString(value));
        }

        template <typename T>
        XMLDom::sibling_iterator& add_attribute(const std::string& name, const T& value,
                                        int precision)
        {
            return add_attribute(name, toString(value,precision));
        }

        void remove_attribute(attribute_iterator it);

        XMLDom::sibling_iterator& add_comment(const std::string& comment);
        XMLDom::sibling_iterator& add_content(const std::string& content);

        XMLDom::sibling_iterator& add_cdata_content(const std::string& cdata_content);

        XMLDom::sibling_iterator add_child(const std::string& name, const NameSpace& ns = NameSpace());
        XMLDom::sibling_iterator add_child(const XMLDom::const_sibling_iterator& node);
        XMLDom::sibling_iterator insert_before(const XMLDom::const_sibling_iterator& node);
        XMLDom::sibling_iterator insert_before(const std::string& name, const NameSpace& ns = NameSpace());
        XMLDom::sibling_iterator insert_after(const XMLDom::const_sibling_iterator& node);
        XMLDom::sibling_iterator insert_after(const std::string& name, const NameSpace& ns = NameSpace());
        XMLDom::sibling_iterator replace(const XMLDom::const_sibling_iterator& node);
        XMLDom::sibling_iterator replace(const std::string& name, const NameSpace& ns = NameSpace());
        XMLDom::sibling_iterator& insert_comment_before(const XMLDom::const_comment_iterator& comment);
        XMLDom::sibling_iterator& insert_comment_before(const std::string& comment);
        XMLDom::sibling_iterator& insert_comment_after(const XMLDom::const_comment_iterator& comment);
        XMLDom::sibling_iterator& insert_comment_after(const std::string& comment);
        XMLDom::sibling_iterator& insert_content_before(const XMLDom::const_content_iterator& content);
        XMLDom::sibling_iterator& insert_content_before(const std::string& content);
        XMLDom::sibling_iterator& insert_content_after(const XMLDom::const_content_iterator& content);
        XMLDom::sibling_iterator& insert_content_after(const std::string& content);
        XMLDom::sibling_iterator replace_by_comment(const XMLDom::const_comment_iterator& node);
        XMLDom::sibling_iterator replace_by_comment(const std::string& comment);
        XMLDom::sibling_iterator replace_by_content(const XMLDom::const_content_iterator& node);
        XMLDom::sibling_iterator replace_by_content(const std::string& content);
        XMLDom::sibling_iterator remove();
    };


    typedef sibling_iterator iterator;
    typedef const_sibling_iterator const_iterator;

public:

    XMLDom(const std::string& rootNodeName = "root");

    ~XMLDom();

    XMLDom(XMLDom&& other) noexcept;

    XMLDom& operator=(XMLDom&& other) noexcept;


public:

    void clear();

    XMLDom clone();

public:

    void loadFromString(const std::string& buffer);

    void loadFromFile(const Path& filename,
                      bool resolve = true);

    void saveToFile(const Path& filename,
                    const std::string& encoding = "UTF-8",
                    bool resolve = true) const;

    void saveToFile(const Path& filename,
                    bool resolve) const;

    std::string saveToString(const std::string& encoding = "UTF-8") const;


public:

    const_sibling_iterator croot() const;

    const_sibling_iterator root() const { return croot(); }

    sibling_iterator root();


    std::string uri() const;
    void setUri(const std::string& uri);

    std::string encoding() const;

private:
    void loadFromPath(const Path& filename);

    void saveToPath(const Path& filename,
                    const std::string& encoding) const;

    _xmlDoc* mXMLDocument;
};


}

#endif