Branch data Line data Source code
1 : : /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 : : Header: easyxml.hxx
3 : : Author: David Megginson
4 : : Date started: 2000
5 : :
6 : : License: David Megginson has placed easyXML into the public domain.
7 : :
8 : : %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
9 : : SENTRY
10 : : %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
11 : :
12 : : #ifndef __EASYXML_HXX
13 : : #define __EASYXML_HXX
14 : :
15 : : /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16 : : HEADERS
17 : : %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
18 : :
19 : : #include "../compiler.h"
20 : :
21 : : #include STL_IOSTREAM
22 : : #include STL_STRING
23 : : #include <vector>
24 : :
25 : : SG_USING_STD(istream);
26 : : SG_USING_STD(string);
27 : : SG_USING_STD(vector);
28 : :
29 : : /** Interface for XML attributes.
30 : : *
31 : : * This interface is used to provide a list of attributes to the
32 : : * application. The interface is a pure abstract class so that
33 : : * different implementations can be substituted for the sake of
34 : : * efficiency.
35 : : *
36 : : * @see XMLAttributesDefault
37 : : */
38 : :
39 : : class XMLAttributes
40 : : {
41 : : public:
42 : :
43 : : /// Constructor.
44 : : XMLAttributes ();
45 : :
46 : : /// Destructor.
47 : : virtual ~ XMLAttributes ();
48 : :
49 : : /** Get the number of attributes present.
50 : : * @return The number of attributes in the list (may be 0).
51 : : */
52 : : virtual int size () const = 0;
53 : :
54 : : /** Get the name of an attribute by index.
55 : : * The index must be less than the size of the list and greater
56 : : * than or equal to zero.
57 : : * @param i The index of the attribute (zero-based).
58 : : * @see #size
59 : : */
60 : : virtual const char * getName (int i) const = 0;
61 : :
62 : : /** Get the string value of an attribute by index.
63 : : *
64 : : * The index must be less than the size of the list and greater
65 : : * than or equal to zero.
66 : : *
67 : : * @param i The index of the attribute (zero-based).
68 : : * @see #size
69 : : */
70 : : virtual const char * getValue (int i) const = 0;
71 : :
72 : : /** Look up the index of an attribute by name.
73 : : *
74 : : * Attribute names must be unique. This method will return
75 : : * an index that can be used with the <tt>getValue(const char *name)</tt>
76 : : * method if the attribute is found.
77 : : *
78 : : * @param name The name of the attribute.
79 : : * @return The index of the attribute with the name specified,
80 : : * or -1 if no such attribute is present in the list.
81 : : */
82 : : virtual int findAttribute (const char * name) const;
83 : :
84 : : /** Test whether an attribute is present.
85 : : *
86 : : * @param name The name of the attribute.
87 : : * @return true if an attribute with the specified name is present
88 : : * in the attribute list, false otherwise.
89 : : */
90 : : virtual bool hasAttribute (const char * name) const;
91 : :
92 : : /** Look up the value of an attribute by name.
93 : : *
94 : : * This method provides a convenient short-cut to invoking
95 : : * {@link #findAttribute} and <tt>getValue(const char *name)</tt>.
96 : : *
97 : : * @param name The name of the attribute to look up.
98 : : * @return The attribute's value as a string, or 0 if no
99 : : * attribute was found with the name specified.
100 : : */
101 : : virtual const char * getValue (const char * name) const;
102 : : };
103 : :
104 : :
105 : : /** Default mutable attributes implementation.
106 : : *
107 : : * This class provides a default implementation of the {@link
108 : : * XMLAttributes} interface. The implementation is mutable, so
109 : : * that it is possible to modify the attribute list when necessary.
110 : : * This class is particularly useful for taking a snapshot of
111 : : * an attribute list during parsing.
112 : : *
113 : : * @see XMLAttributes
114 : : */
115 : :
116 : : class XMLAttributesDefault : public XMLAttributes
117 : : {
118 : : public:
119 : :
120 : : /// Default constructor.
121 : : XMLAttributesDefault ();
122 : :
123 : : /** Copy constructor.
124 : : *
125 : : * This constructor is especially useful for taking a static
126 : : * snapshot of an attribute list for later use.
127 : : *
128 : : * @param atts The attribute list to copy.
129 : : */
130 : : XMLAttributesDefault (const XMLAttributes & atts);
131 : :
132 : : /// Destructor.
133 : : virtual ~XMLAttributesDefault ();
134 : :
135 : : /// Count the attributes in the list.
136 : : virtual int size () const;
137 : :
138 : : /// Get the name of an attribute by index.
139 : : virtual const char * getName (int i) const;
140 : :
141 : : /// Get the value of an attribute by index.
142 : : virtual const char * getValue (int i) const;
143 : :
144 : : /** Add an attribute to an attribute list.
145 : : *
146 : : * The name is required to be unique in the list; the value is not.
147 : : *
148 : : * @param name The name of the attribute to add.
149 : : * @param value The value of the attribute to add.
150 : : */
151 : : virtual void addAttribute (const char * name, const char * value);
152 : :
153 : : /** Set an attribute name by index.
154 : : *
155 : : * This method will not extend the list; the attribute must
156 : : * already exist.
157 : : *
158 : : * @param i The index of the attribute (zero-based).
159 : : * @param name The new name.
160 : : */
161 : : virtual void setName (int i, const char * name);
162 : :
163 : : /** Set an attribute value by index.
164 : : *
165 : : * This method will not extend the list; the attribute must
166 : : * already exist.
167 : : *
168 : : * @param i The index of the attribute (zero-based).
169 : : * @param value The new value.
170 : : */
171 : : virtual void setValue (int i, const char * value);
172 : :
173 : : /** Set an attribute value by name.
174 : : *
175 : : * This method will not extend the list; the attribute must
176 : : * already exist.
177 : : *
178 : : * @param name The name of the attribute that will have the new
179 : : * value.
180 : : * @param value The new value.
181 : : */
182 : : virtual void setValue (const char * name, const char * value);
183 : :
184 : : private:
185 : : vector<string> _atts;
186 : : };
187 : :
188 : :
189 : : /** Visitor class for an XML document.
190 : : *
191 : : * This interface uses the Visitor pattern. The XML parser walks
192 : : * through the XML document and invokes the appropriate method in
193 : : * this visitor for each piece of markup it finds. By default,
194 : : * the methods do nothing; the application must subclass the visitor
195 : : * and override the methods for the events it's interested in.
196 : : * All applications are required to provide an implementation
197 : : * for the error callback.
198 : : */
199 : :
200 : : class XMLVisitor
201 : 20 : {
202 : : public:
203 : :
204 : : /// Virtual destructor.
205 [ - + ][ # # ]: 20 : virtual ~XMLVisitor () {}
[ # # ]
206 : :
207 : : /** Callback for the start of an XML document.
208 : : *
209 : : * The XML parser will invoke this method once, at the beginning of
210 : : * the XML document, before any other methods are invoked. The
211 : : * application can use this callback to set up data structures,
212 : : * open files, etc.
213 : : *
214 : : * @see #endXML
215 : : */
216 : 0 : virtual void startXML () {}
217 : :
218 : : /** Callback for the end of an XML document.
219 : : *
220 : : * The XML parser will invoke this method once, at the end of the
221 : : * XML document, after all other methods are invoked, and only
222 : : * if there have been no parsing errors. The application can use
223 : : * this callback to close or write files, finalize data structures,
224 : : * and so on, but the application will need to be prepared to
225 : : * clean up any resources without this callback in the event of
226 : : * an error.
227 : : *
228 : : * @see #startXML
229 : : */
230 : 0 : virtual void endXML () {}
231 : :
232 : : /** Callback for the start of an XML element.
233 : : *
234 : : * The XML parser will invoke this method at the beginning of every
235 : : * XML element. Start and end element calls will be balanced
236 : : * and properly nested: every element has both a start and end
237 : : * callback (even if it was specified with an XML empty element tag),
238 : : * there is exactly one root element, and every element must end
239 : : * before its parent does. Elements may not overlap.
240 : : * Note that the attribute list provided is volatile; it's contents
241 : : * are not guaranteed to persist after the end of the callback.
242 : : * If the application needs to keep a copy of the attribute list,
243 : : * it can make the copy with the {@link XMLAttributesDefault} class.
244 : : *
245 : : * @param name The name of the element that is starting (not null).
246 : : * @param atts The element's attributes (not null).
247 : : * @see #endElement
248 : : */
249 : 0 : virtual void startElement (const char * name, const XMLAttributes &atts) {}
250 : :
251 : : /** Callback for the end of an XML element.
252 : : *
253 : : * The XML parser will invoke this method at the end of every XML element.
254 : : *
255 : : * @param name The name of the element that is ending (not null).
256 : : * @see #startElement
257 : : */
258 : 0 : virtual void endElement (const char * name) {}
259 : :
260 : : /** Callback for a chunk of character data.
261 : : *
262 : : * The XML parser will invoke this method once for every chunk of
263 : : * character data in the XML document, including whitespace
264 : : * separating elements (as required by the XML recommendation).
265 : : * Note that character data may be chunked arbitrarily: the
266 : : * character data content of an element may be returned in one
267 : : * large chunk or several consecutive smaller chunks.
268 : : *
269 : : * @param s A pointer to the beginning of the character data (not null).
270 : : * @param length The number of characters in the chunk (may
271 : : * be zero).
272 : : */
273 : 0 : virtual void data (const char * s, int length) {}
274 : :
275 : : /** Callback for an XML processing instruction.
276 : : *
277 : : * The XML parser will invoke this method once for every processing
278 : : * instruction in the XML document. Note that the XML declaration
279 : : * and the Text declaration are NOT PROCESSING INSTRUCTIONS and
280 : : * will not be reported through this callback. Processing
281 : : * instructions are not all that useful, but the XML recommendation
282 : : * requires that they be reported. Most applications can safely
283 : : * ignore this callback and use the empty default implementation.
284 : : *
285 : : * @param target The processing instruction target (not null).
286 : : * @param data The processing instruction data (not null).
287 : : */
288 : 0 : virtual void pi (const char * target, const char * data) {}
289 : :
290 : : /** Callback for an XML parsing warning.
291 : : *
292 : : * The XML parser will use this callback to report any non-fatal warnings
293 : : * during parsing. It is the responsibility of the application to
294 : : * deal with the warning in some appropriate way.
295 : : *
296 : : * @param message The warning message from the parser.
297 : : * @param line The number of the line that generated the warning.
298 : : * @param column The character position in the line that generated
299 : : * the warning.
300 : : */
301 : 0 : virtual void warning (const char * message, int line, int column) {}
302 : : };
303 : :
304 : : /** @relates XMLVisitor
305 : : * Read an XML document.
306 : : *
307 : : * This function reads an XML document from the input stream provided,
308 : : * and invokes the callback methods in the visitor object to pass the
309 : : * parsing events back to the application. When this function
310 : : * returns, the parser will have reported all of the data in the XML
311 : : * document to the application through the visitor callback methods,
312 : : * and XML processing will be complete.
313 : : *
314 : : * @param input The byte input stream containing the XML document.
315 : : * @param visitor An object that contains callbacks for XML parsing
316 : : * events.
317 : : * @param path A string describing the original path of the resource.
318 : : * @exception Throws sg_io_exception or sg_xml_exception if there
319 : : * is a problem reading the file.
320 : : * @see XMLVisitor
321 : : */
322 : :
323 : : extern void readXML (istream &input, XMLVisitor &visitor, const string &path="");
324 : :
325 : : /** @relates XMLVisitor
326 : : * Read an XML document.
327 : : *
328 : : * This function reads an XML document from the input stream provided,
329 : : * and invokes the callback methods in the visitor object to pass the
330 : : * parsing events back to the application. When this function
331 : : * returns, the parser will have reported all of the data in the XML
332 : : * document to the application through the visitor callback methods,
333 : : * and XML processing will be complete.
334 : : *
335 : : * @param path The file name of the XML resource.
336 : : * @param visitor An object that contains callbacks for XML parsing
337 : : * events.
338 : : * @exception Throws sg_io_exception or sg_xml_exception if there
339 : : * is a problem reading the file.
340 : : * @see XMLVisitor
341 : : */
342 : : extern void readXML (const string &path, XMLVisitor &visitor);
343 : :
344 : : #endif // __EASYXML_HXX
|
