/**********************************************************************

 *

 * Project:  CPL - Common Portability Library

 * Purpose:  Declarations for MiniXML Handler.

 * Author:   Frank Warmerdam, warmerdam@pobox.com

 *

 **********************************************************************

 * Copyright (c) 2001, Frank Warmerdam

 *

 * SPDX-License-Identifier: MIT

 ****************************************************************************/

#ifndef CPL_MINIXML_H_INCLUDED

#define CPL_MINIXML_H_INCLUDED

#include "cpl_port.h"

/**

 * \file cpl_minixml.h

 *

 * Definitions for CPL mini XML Parser/Serializer.

 */

CPL_C_START

/** XML node type */

typedef enum

{

    /*! Node is an element */ CXT_Element = 0,

    /*! Node is a raw text value */ CXT_Text = 1,

    /*! Node is attribute */ CXT_Attribute = 2,

    /*! Node is an XML comment. */ CXT_Comment = 3,

    /*! Node is a special literal */ CXT_Literal = 4

} CPLXMLNodeType;

/*! @cond Doxygen_Suppress */

typedef struct CPLXMLNode CPLXMLNode;

/*! @endcond */

/**

 * Document node structure.

 *

 * This C structure is used to hold a single text fragment representing a

 * component of the document when parsed.   It should be allocated with the

 * appropriate CPL function, and freed with CPLDestroyXMLNode().  The structure

 * contents should not normally be altered by application code, but may be

 * freely examined by application code.

 *

 * Using the psChild and psNext pointers, a hierarchical tree structure

 * for a document can be represented as a tree of CPLXMLNode structures.

 */

struct CPLXMLNode

{

    /**

     * \brief Node type

     *

     * One of CXT_Element, CXT_Text, CXT_Attribute, CXT_Comment,

     * or CXT_Literal.

     */

    CPLXMLNodeType eType;

    /**

     * \brief Node value

     *

     * For CXT_Element this is the name of the element, without the angle

     * brackets.  Note there is a single CXT_Element even when the document

     * contains a start and end element tag.  The node represents the pair.

     * All text or other elements between the start and end tag will appear

     * as children nodes of this CXT_Element node.

     *

     * For CXT_Attribute the pszValue is the attribute name.  The value of

     * the attribute will be a CXT_Text child.

     *

     * For CXT_Text this is the text itself (value of an attribute, or a

     * text fragment between an element start and end tags.

     *

     * For CXT_Literal it is all the literal text.  Currently this is just

     * used for !DOCTYPE lines, and the value would be the entire line.

     *

     * For CXT_Comment the value is all the literal text within the comment,

     * but not including the comment start/end indicators ("<--" and "-->").

     */

    char *pszValue;

    /**

     * \brief Next sibling.

     *

     * Pointer to next sibling, that is the next node appearing after this

     * one that has the same parent as this node.  NULL if this node is the

     * last child of the parent element.

     */

    struct CPLXMLNode *psNext;

    /**

     * \brief Child node.

     *

     * Pointer to first child node, if any.  Only CXT_Element and CXT_Attribute

     * nodes should have children.  For CXT_Attribute it should be a single

     * CXT_Text value node, while CXT_Element can have any kind of child.

     * The full list of children for a node are identified by walking the

     * psNext's starting with the psChild node.

     */

    struct CPLXMLNode *psChild;

};

CPLXMLNode CPL_DLL *CPLParseXMLString(const char *);

void CPL_DLL CPLDestroyXMLNode(CPLXMLNode *);

CPLXMLNode CPL_DLL *CPLGetXMLNode(CPLXMLNode *poRoot, const char *pszPath);

#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)

/*! @cond Doxygen_Suppress */

extern "C++"

{

    inline const CPLXMLNode *CPLGetXMLNode(const CPLXMLNode *poRoot,

                                           const char *pszPath)

    {

        return const_cast<const CPLXMLNode *>(

            CPLGetXMLNode(const_cast<CPLXMLNode *>(poRoot), pszPath));

    }

}

/*! @endcond */

#endif

CPLXMLNode CPL_DLL *CPLSearchXMLNode(CPLXMLNode *poRoot, const char *pszTarget);

#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)

/*! @cond Doxygen_Suppress */

extern "C++"

{

    inline const CPLXMLNode *CPLSearchXMLNode(const CPLXMLNode *poRoot,

                                              const char *pszTarget)

    {

        return const_cast<const CPLXMLNode *>(

            CPLSearchXMLNode(const_cast<CPLXMLNode *>(poRoot), pszTarget));

    }

}

/*! @endcond */

#endif

const char CPL_DLL *CPLGetXMLValue(const CPLXMLNode *poRoot,

                                   const char *pszPath, const char *pszDefault);

CPLXMLNode CPL_DLL *CPLCreateXMLNode(CPLXMLNode *poParent, CPLXMLNodeType eType,

                                     const char *pszText);

char CPL_DLL *CPLSerializeXMLTree(const CPLXMLNode *psNode);

void CPL_DLL CPLAddXMLChild(CPLXMLNode *psParent, CPLXMLNode *psChild);

int CPL_DLL CPLRemoveXMLChild(CPLXMLNode *psParent, CPLXMLNode *psChild);

void CPL_DLL CPLAddXMLSibling(CPLXMLNode *psOlderSibling,

                              CPLXMLNode *psNewSibling);

CPLXMLNode CPL_DLL *CPLCreateXMLElementAndValue(CPLXMLNode *psParent,

                                                const char *pszName,

                                                const char *pszValue);

void CPL_DLL CPLAddXMLAttributeAndValue(CPLXMLNode *psParent,

                                        const char *pszName,

                                        const char *pszValue);

CPLXMLNode CPL_DLL *CPLCloneXMLTree(const CPLXMLNode *psTree);

int CPL_DLL CPLSetXMLValue(CPLXMLNode *psRoot, const char *pszPath,

                           const char *pszValue);

void CPL_DLL CPLStripXMLNamespace(CPLXMLNode *psRoot, const char *pszNameSpace,

                                  int bRecurse);

void CPL_DLL CPLCleanXMLElementName(char *);

CPLXMLNode CPL_DLL *CPLParseXMLFile(const char *pszFilename);

int CPL_DLL CPLSerializeXMLTreeToFile(const CPLXMLNode *psTree,

                                      const char *pszFilename);

size_t CPL_DLL CPLXMLNodeGetRAMUsageEstimate(const CPLXMLNode *psNode);

CPL_C_END

#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)

extern "C++"

{

#ifndef DOXYGEN_SKIP

#include <memory>

#endif

    /*! @cond Doxygen_Suppress */

    struct CPL_DLL CPLXMLTreeCloserDeleter

    {

        void operator()(CPLXMLNode *psNode) const

        {

            CPLDestroyXMLNode(psNode);

        }

    };

    /*! @endcond */

    /** Manage a tree of XML nodes so that all nodes are freed when the instance

     * goes out of scope.  Only the top level node should be in a

     * CPLXMLTreeCloser.

     */

    class CPL_DLL CPLXMLTreeCloser

        : public std::unique_ptr<CPLXMLNode, CPLXMLTreeCloserDeleter>

    {

      public:

        /** Constructor */

        explicit CPLXMLTreeCloser(CPLXMLNode *data)

            : std::unique_ptr<CPLXMLNode, CPLXMLTreeCloserDeleter>(data)

        {

        }

        /** Returns a pointer to the document (root) element

         * @return the node pointer */

        CPLXMLNode *getDocumentElement();

    };

}  // extern "C++"

#endif /* __cplusplus */

#endif /* CPL_MINIXML_H_INCLUDED */