3 Copyright (C
) 2003 Elwood C
. Downey
5 This library is free software
; you can redistribute it
and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation
; either
8 version
2.1 of the License
, or (at your option
) any later version
.
10 This library is distributed in the hope that it will be useful
,
11 but WITHOUT ANY WARRANTY
; without even the implied warranty of
12 MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE
. See the GNU
13 Lesser General Public License
for more details
.
15 You should have received a copy of the GNU Lesser General Public
16 License along with
this library
; if not, write to the Free Software
17 Foundation
, Inc
., 59 Temple Place
, Suite
330, Boston
, MA
02111-1307 USA
22 \brief A little DOM-style library to handle parsing and processing an XML file.
24 It only handles elements, attributes and pcdata content. <! ... > and <? ... > are silently ignored. pcdata is collected into one string, sans leading whitespace first line. \n
26 The following is an example of a cannonical usage for the lilxml library. Initialize a lil xml context and read an XML file in a root element.
32 LilXML *lp = newLilXML();
37 while ((c = fgetc(stdin)) != EOF) {
38 root = readXMLEle (lp, c, errmsg);
42 error ("Error: %s\n", errmsg);
45 // print the tag and pcdata content of each child element within the root
47 for (ep = nextXMLEle (root, 1); ep != NULL; ep = nextXMLEle (root, 0))
48 printf ("%s: %s\n", tagXMLEle(ep), pcdataXMLEle(ep));
51 // finished with root element and with lil xml context
67 /* opaque handle types */
68 typedef struct _xml_att XMLAtt
;
69 typedef struct _xml_ele XMLEle
;
70 typedef struct _LilXML LilXML
;
73 * \defgroup lilxmlFunctions Functions to parse, process, and search XML.
77 /* creation and destruction functions */
79 /** \brief Create a new lilxml parser.
80 \return a pointer to the lilxml parser on sucess. NULL on failure.
82 extern LilXML
*newLilXML(void);
84 /** \brief Delete a lilxml parser.
85 \param lp a pointer to a lilxml parser to be deleted.
87 extern void delLilXML (LilXML
*lp
);
89 /** \brief Delete an XML element.
90 \return a pointer to the XML Element to be deleted.
92 extern void delXMLEle (XMLEle
*e
);
94 /** \brief Process an XML one char at a time.
95 \param lp a pointer to a lilxml parser.
96 \param c one character to process.
97 \param errmsg a buffer to store error messages if an error in parsing is encounterd.
98 \return When the function parses a complete valid XML element, it will return a pointer to the XML element. A NULL is returned when parsing the element is still in progress, or if a parsing error occurs. Check errmsg for errors if NULL is returned.
100 extern XMLEle
*readXMLEle (LilXML
*lp
, int c
, char errmsg
[]);
102 /* search functions */
103 /** \brief Find an XML attribute within an XML element.
104 \param e a pointer to the XML element to search.
105 \param name the attribute name to search for.
106 \return A pointer to the XML attribute if found or NULL on failure.
108 extern XMLAtt
*findXMLAtt (XMLEle
*e
, const char *name
);
110 /** \brief Find an XML element within an XML element.
111 \param e a pointer to the XML element to search.
112 \param tag the element tag to search for.
113 \return A pointer to the XML element if found or NULL on failure.
115 extern XMLEle
*findXMLEle (XMLEle
*e
, const char *tag
);
117 /* iteration functions */
118 /** \brief Iterate an XML element for a list of nesetd XML elements.
119 \param ep a pointer to the XML element to iterate.
120 \param first the index of the starting XML element. Pass 1 to start iteration from the beginning of the XML element. Pass 0 to get the next element thereater.
121 \return On success, a pointer to the next XML element is returned. NULL when there are no more elements.
123 extern XMLEle
*nextXMLEle (XMLEle
*ep
, int first
);
125 /** \brief Iterate an XML element for a list of XML attributes.
126 \param ep a pointer to the XML element to iterate.
127 \param first the index of the starting XML attribute. Pass 1 to start iteration from the beginning of the XML element. Pass 0 to get the next attribute thereater.
128 \return On success, a pointer to the next XML attribute is returned. NULL when there are no more attributes.
130 extern XMLAtt
*nextXMLAtt (XMLEle
*ep
, int first
);
133 /** \brief Return the parent of an XML element.
134 \return a pointer to the XML element parent.
136 extern XMLEle
*parentXMLEle (XMLEle
*ep
);
138 /** \brief Return the parent of an XML attribute.
139 \return a pointer to the XML element parent.
141 extern XMLEle
*parentXMLAtt (XMLAtt
*ap
);
143 /* access functions */
144 /** \brief Return the tag of an XML element.
145 \param ep a pointer to an XML element.
146 \return the tag string.
148 extern char *tagXMLEle (XMLEle
*ep
);
150 /** \brief Return the pcdata of an XML element.
151 \param ep a pointer to an XML element.
152 \return the pcdata string on success.
154 extern char *pcdataXMLEle (XMLEle
*ep
);
156 /** \brief Return the name of an XML attribute.
157 \param ap a pointer to an XML attribute.
158 \return the name string of the attribute.
160 extern char *nameXMLAtt (XMLAtt
*ap
);
162 /** \brief Return the value of an XML attribute.
163 \param ap a pointer to an XML attribute.
164 \return the value string of the attribute.
166 extern char *valuXMLAtt (XMLAtt
*ap
);
168 /** \brief Return the number of characters in pcdata in an XML element.
169 \param ep a pointer to an XML element.
170 \return the length of the pcdata string.
172 extern int pcdatalenXMLEle (XMLEle
*ep
);
174 /** \brief Return the number of nested XML elements in a parent XML element.
175 \param ep a pointer to an XML element.
176 \return the number of nested XML elements.
178 extern int nXMLEle (XMLEle
*ep
);
180 /** \brief Return the number of XML attributes in a parent XML element.
181 \param ep a pointer to an XML element.
182 \return the number of XML attributes within the XML element.
184 extern int nXMLAtt (XMLEle
*ep
);
186 /* convenience functions */
187 /** \brief Find an XML element's attribute value.
188 \param ep a pointer to an XML element.
189 \param name the name of the XML attribute to retrieve its value.
190 \return the value string of an XML element on success. NULL on failure.
192 extern const char *findXMLAttValu (XMLEle
*ep
, char *name
);
194 /** \brief Handy wrapper to read one xml file.
195 \param fp pointer to FILE to read.
196 \param lp pointer to lilxml parser.
197 \param errmsg a buffer to store error messages on failure.
198 \return root element else NULL with report in errmsg[].
200 extern XMLEle
*readXMLFile (FILE *fp
, LilXML
*lp
, char errmsg
[]);
202 /** \brief Print an XML element.
203 \param fp a pointer to FILE where the print output is directed.
204 \param e the XML element to print.
205 \param level the printing level, set to 0 to print the whole element.
207 extern void prXMLEle (FILE *fp
, XMLEle
*e
, int level
);
217 initialize a lil xml context and read an XML file in a root element
219 LilXML *lp = newLilXML();
224 while ((c = fgetc(stdin)) != EOF) {
225 root = readXMLEle (lp, c, errmsg);
229 error ("Error: %s\n", errmsg);
232 print the tag and pcdata content of each child element within the root
234 for (ep = nextXMLEle (root, 1); ep != NULL; ep = nextXMLEle (root, 0))
235 printf ("%s: %s\n", tagXMLEle(ep), pcdataXMLEle(ep));
238 finished with root element and with lil xml context
244 /* For RCS Only -- Do Not Edit
245 * @(#) $RCSfile$ $Date$ $Revision$ $Name: $
248 #endif /* LILXML_H */