Line data Source code
1 : /**********************************************************************
2 : * $Id$
3 : *
4 : * Project: CPL - Common Portability Library
5 : * Purpose: Declarations for MiniXML Handler.
6 : * Author: Frank Warmerdam, warmerdam@pobox.com
7 : *
8 : **********************************************************************
9 : * Copyright (c) 2001, Frank Warmerdam
10 : *
11 : * Permission is hereby granted, free of charge, to any person obtaining a
12 : * copy of this software and associated documentation files (the "Software"),
13 : * to deal in the Software without restriction, including without limitation
14 : * the rights to use, copy, modify, merge, publish, distribute, sublicense,
15 : * and/or sell copies of the Software, and to permit persons to whom the
16 : * Software is furnished to do so, subject to the following conditions:
17 : *
18 : * The above copyright notice and this permission notice shall be included
19 : * in all copies or substantial portions of the Software.
20 : *
21 : * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22 : * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 : * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
24 : * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 : * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26 : * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27 : * DEALINGS IN THE SOFTWARE.
28 : ****************************************************************************/
29 :
30 : #ifndef CPL_MINIXML_H_INCLUDED
31 : #define CPL_MINIXML_H_INCLUDED
32 :
33 : #include "cpl_port.h"
34 :
35 : /**
36 : * \file cpl_minixml.h
37 : *
38 : * Definitions for CPL mini XML Parser/Serializer.
39 : */
40 :
41 : CPL_C_START
42 :
43 : /** XML node type */
44 : typedef enum
45 : {
46 : /*! Node is an element */ CXT_Element = 0,
47 : /*! Node is a raw text value */ CXT_Text = 1,
48 : /*! Node is attribute */ CXT_Attribute = 2,
49 : /*! Node is an XML comment. */ CXT_Comment = 3,
50 : /*! Node is a special literal */ CXT_Literal = 4
51 : } CPLXMLNodeType;
52 :
53 : /*! @cond Doxygen_Suppress */
54 : typedef struct CPLXMLNode CPLXMLNode;
55 :
56 : /*! @endcond */
57 :
58 : /**
59 : * Document node structure.
60 : *
61 : * This C structure is used to hold a single text fragment representing a
62 : * component of the document when parsed. It should be allocated with the
63 : * appropriate CPL function, and freed with CPLDestroyXMLNode(). The structure
64 : * contents should not normally be altered by application code, but may be
65 : * freely examined by application code.
66 : *
67 : * Using the psChild and psNext pointers, a hierarchical tree structure
68 : * for a document can be represented as a tree of CPLXMLNode structures.
69 : */
70 : struct CPLXMLNode
71 : {
72 : /**
73 : * \brief Node type
74 : *
75 : * One of CXT_Element, CXT_Text, CXT_Attribute, CXT_Comment,
76 : * or CXT_Literal.
77 : */
78 : CPLXMLNodeType eType;
79 :
80 : /**
81 : * \brief Node value
82 : *
83 : * For CXT_Element this is the name of the element, without the angle
84 : * brackets. Note there is a single CXT_Element even when the document
85 : * contains a start and end element tag. The node represents the pair.
86 : * All text or other elements between the start and end tag will appear
87 : * as children nodes of this CXT_Element node.
88 : *
89 : * For CXT_Attribute the pszValue is the attribute name. The value of
90 : * the attribute will be a CXT_Text child.
91 : *
92 : * For CXT_Text this is the text itself (value of an attribute, or a
93 : * text fragment between an element start and end tags.
94 : *
95 : * For CXT_Literal it is all the literal text. Currently this is just
96 : * used for !DOCTYPE lines, and the value would be the entire line.
97 : *
98 : * For CXT_Comment the value is all the literal text within the comment,
99 : * but not including the comment start/end indicators ("<--" and "-->").
100 : */
101 : char *pszValue;
102 :
103 : /**
104 : * \brief Next sibling.
105 : *
106 : * Pointer to next sibling, that is the next node appearing after this
107 : * one that has the same parent as this node. NULL if this node is the
108 : * last child of the parent element.
109 : */
110 : struct CPLXMLNode *psNext;
111 :
112 : /**
113 : * \brief Child node.
114 : *
115 : * Pointer to first child node, if any. Only CXT_Element and CXT_Attribute
116 : * nodes should have children. For CXT_Attribute it should be a single
117 : * CXT_Text value node, while CXT_Element can have any kind of child.
118 : * The full list of children for a node are identified by walking the
119 : * psNext's starting with the psChild node.
120 : */
121 :
122 : struct CPLXMLNode *psChild;
123 : };
124 :
125 : CPLXMLNode CPL_DLL *CPLParseXMLString(const char *);
126 : void CPL_DLL CPLDestroyXMLNode(CPLXMLNode *);
127 : CPLXMLNode CPL_DLL *CPLGetXMLNode(CPLXMLNode *poRoot, const char *pszPath);
128 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
129 : /*! @cond Doxygen_Suppress */
130 : extern "C++"
131 : {
132 1431202 : inline const CPLXMLNode *CPLGetXMLNode(const CPLXMLNode *poRoot,
133 : const char *pszPath)
134 : {
135 : return const_cast<const CPLXMLNode *>(
136 1431202 : CPLGetXMLNode(const_cast<CPLXMLNode *>(poRoot), pszPath));
137 : }
138 : }
139 : /*! @endcond */
140 : #endif
141 : CPLXMLNode CPL_DLL *CPLSearchXMLNode(CPLXMLNode *poRoot, const char *pszTarget);
142 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
143 : /*! @cond Doxygen_Suppress */
144 : extern "C++"
145 : {
146 : inline const CPLXMLNode *CPLSearchXMLNode(const CPLXMLNode *poRoot,
147 : const char *pszTarget)
148 : {
149 : return const_cast<const CPLXMLNode *>(
150 : CPLSearchXMLNode(const_cast<CPLXMLNode *>(poRoot), pszTarget));
151 : }
152 : }
153 : /*! @endcond */
154 : #endif
155 : const char CPL_DLL *CPLGetXMLValue(const CPLXMLNode *poRoot,
156 : const char *pszPath, const char *pszDefault);
157 : CPLXMLNode CPL_DLL *CPLCreateXMLNode(CPLXMLNode *poParent, CPLXMLNodeType eType,
158 : const char *pszText);
159 : char CPL_DLL *CPLSerializeXMLTree(const CPLXMLNode *psNode);
160 : void CPL_DLL CPLAddXMLChild(CPLXMLNode *psParent, CPLXMLNode *psChild);
161 : int CPL_DLL CPLRemoveXMLChild(CPLXMLNode *psParent, CPLXMLNode *psChild);
162 : void CPL_DLL CPLAddXMLSibling(CPLXMLNode *psOlderSibling,
163 : CPLXMLNode *psNewSibling);
164 : CPLXMLNode CPL_DLL *CPLCreateXMLElementAndValue(CPLXMLNode *psParent,
165 : const char *pszName,
166 : const char *pszValue);
167 : void CPL_DLL CPLAddXMLAttributeAndValue(CPLXMLNode *psParent,
168 : const char *pszName,
169 : const char *pszValue);
170 : CPLXMLNode CPL_DLL *CPLCloneXMLTree(const CPLXMLNode *psTree);
171 : int CPL_DLL CPLSetXMLValue(CPLXMLNode *psRoot, const char *pszPath,
172 : const char *pszValue);
173 : void CPL_DLL CPLStripXMLNamespace(CPLXMLNode *psRoot, const char *pszNameSpace,
174 : int bRecurse);
175 : void CPL_DLL CPLCleanXMLElementName(char *);
176 :
177 : CPLXMLNode CPL_DLL *CPLParseXMLFile(const char *pszFilename);
178 : int CPL_DLL CPLSerializeXMLTreeToFile(const CPLXMLNode *psTree,
179 : const char *pszFilename);
180 :
181 : size_t CPL_DLL CPLXMLNodeGetRAMUsageEstimate(const CPLXMLNode *psNode);
182 :
183 : CPL_C_END
184 :
185 : #if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
186 :
187 : extern "C++"
188 : {
189 : #ifndef DOXYGEN_SKIP
190 : #include <memory>
191 : #endif
192 :
193 : /*! @cond Doxygen_Suppress */
194 : struct CPL_DLL CPLXMLTreeCloserDeleter
195 : {
196 10170 : void operator()(CPLXMLNode *psNode) const
197 : {
198 10170 : CPLDestroyXMLNode(psNode);
199 10170 : }
200 : };
201 :
202 : /*! @endcond */
203 :
204 : /** Manage a tree of XML nodes so that all nodes are freed when the instance
205 : * goes out of scope. Only the top level node should be in a
206 : * CPLXMLTreeCloser.
207 : */
208 : class CPL_DLL CPLXMLTreeCloser
209 : : public std::unique_ptr<CPLXMLNode, CPLXMLTreeCloserDeleter>
210 : {
211 : public:
212 : /** Constructor */
213 12232 : explicit CPLXMLTreeCloser(CPLXMLNode *data)
214 12232 : : std::unique_ptr<CPLXMLNode, CPLXMLTreeCloserDeleter>(data)
215 : {
216 12232 : }
217 :
218 : /** Returns a pointer to the document (root) element
219 : * @return the node pointer */
220 : CPLXMLNode *getDocumentElement();
221 : };
222 :
223 : } // extern "C++"
224 :
225 : #endif /* __cplusplus */
226 :
227 : #endif /* CPL_MINIXML_H_INCLUDED */
|
