3 * Declarations for the SimGear XML parser.
4 * Written by David Megginson, 2000-2001
5 * This file is in the Public Domain, and comes with NO WARRANTY of any kind.
15 #include <simgear/compiler.h>
21 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
22 SG_USING_STD(istream);
29 * Interface for XML attributes.
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
36 * @see XMLAttributesDefault
51 virtual ~ XMLAttributes ();
55 * Get the number of attributes present.
57 * @return The number of attributes in the list (may be 0).
59 virtual int size () const = 0;
63 * Get the name of an attribute by index.
65 * The index must be less than the size of the list and greater
66 * than or equal to zero.
68 * @param i The index of the attribute (zero-based).
71 virtual const char * getName (int i) const = 0;
75 * Get the string value of an attribute by index.
77 * The index must be less than the size of the list and greater
78 * than or equal to zero.
80 * @param i The index of the attribute (zero-based).
83 virtual const char * getValue (int i) const = 0;
87 * Look up the index of an attribute by name.
89 * Attribute names must be unique. This method will return
90 * an index that can be used with the {@link #getValue(const char *)}
91 * method if the attribute is found.
93 * @param name The name of the attribute.
94 * @return The index of the attribute with the name specified,
95 * or -1 if no such attribute is present in the list.
97 virtual int findAttribute (const char * name) const;
101 * Test whether an attribute is present.
103 * @param name The name of the attribute.
104 * @return true if an attribute with the specified name is present
105 * in the attribute list, false otherwise.
107 virtual bool hasAttribute (const char * name) const;
111 * Look up the value of an attribute by name.
113 * This method provides a convenient short-cut to invoking
114 * {@link #findAttribute} and {@link #getValue(const char *)}.
116 * @param name The name of the attribute to look up.
117 * @return The attribute's value as a string, or 0 if no
118 * attribute was found with the name specified.
120 virtual const char * getValue (const char * name) const;
125 * Default mutable attributes implementation.
127 * This class provides a default implementation of the {@link
128 * XMLAttributes} interface. The implementation is mutable, so
129 * that it is possible to modify the attribute list when necessary.
130 * This class is particularly useful for taking a snapshot of
131 * an attribute list during parsing.
135 class XMLAttributesDefault : public XMLAttributes
140 * Default constructor.
142 XMLAttributesDefault ();
148 * This constructor is especially useful for taking a static
149 * snapshot of an attribute list for later use.
151 * @param atts The attribute list to copy.
153 XMLAttributesDefault (const XMLAttributes & atts);
159 virtual ~XMLAttributesDefault ();
163 * Count the attributes in the list.
165 virtual int size () const;
169 * Get the name of an attribute by index.
171 virtual const char * getName (int i) const;
175 * Get the value of an attribute by index.
177 virtual const char * getValue (int i) const;
181 * Add an attribute to an attribute list.
183 * The name is required to be unique in the list; the value is not.
185 * @param name The name of the attribute to add.
186 * @param value The value of the attribute to add.
188 virtual void addAttribute (const char * name, const char * value);
192 * Set an attribute name by index.
194 * This method will not extend the list; the attribute must
197 * @param i The index of the attribute (zero-based).
198 * @param name The new name.
200 virtual void setName (int i, const char * name);
204 * Set an attribute value by index.
206 * This method will not extend the list; the attribute must
209 * @param i The index of the attribute (zero-based).
210 * @param value The new value.
212 virtual void setValue (int i, const char * value);
216 * Set an attribute value by name.
218 * This method will not extend the list; the attribute must
221 * @param name The name of the attribute that will have the new
223 * @param value The new value.
225 virtual void setValue (const char * name, const char * value);
228 vector<string> _atts;
233 * Visitor class for an XML document.
235 * This interface uses the Visitor pattern. The XML parser walks
236 * through the XML document and invokes the appropriate method in
237 * this visitor for each piece of markup it finds. By default,
238 * the methods do nothing; the application must subclass the visitor
239 * and override the methods for the events it's interested in.
240 * All applications are required to provide an implementation
241 * for the {@link #error} callback.
248 * Callback for the start of an XML document.
250 * The XML parser will invoke this method once, at the beginning of
251 * the XML document, before any other methods are invoked. The
252 * application can use this callback to set up data structures,
257 virtual void startXML () {}
261 * Callback for the end of an XML document.
263 * The XML parser will invoke this method once, at the end of the
264 * XML document, after all other methods are invoked, and only
265 * if there have been no parsing errors. The application can use
266 * this callback to close or write files, finalize data structures,
267 * and so on, but the application will need to be prepared to
268 * clean up any resources without this callback in the event of
274 virtual void endXML () {}
278 * Callback for the start of an XML element.
280 * The XML parser will invoke this method at the beginning of every
281 * XML element. Start and end element calls will be balanced
282 * and properly nested: every element has both a start and end
283 * callback (even if it was specified with an XML empty element tag),
284 * there is exactly one root element, and every element must end
285 * before its parent does. Elements may not overlap.
286 * Note that the attribute list provided is volatile; it's contents
287 * are not guaranteed to persist after the end of the callback.
288 * If the application needs to keep a copy of the attribute list,
289 * it can make the copy with the {@link XMLAttributesDefault} class.
291 * @param name The name of the element that is starting (not null).
292 * @param atts The element's attributes (not null).
295 virtual void startElement (const char * name, const XMLAttributes &atts) {}
299 * Callback for the end of an XML element.
301 * The XML parser will invoke this method at the end of every XML element.
303 * @param name The name of the element that is ending (not null).
306 virtual void endElement (const char * name) {}
310 * Callback for a chunk of character data.
312 * The XML parser will invoke this method once for every chunk of
313 * character data in the XML document, including whitespace
314 * separating elements (as required by the XML recommendation).
315 * Note that character data may be chunked arbitrarily: the
316 * character data content of an element may be returned in one
317 * large chunk or several consecutive smaller chunks.
319 * @param s A pointer to the beginning of the character data (not null).
320 * @param length The number of characters in the chunk (may
323 virtual void data (const char * s, int length) {}
327 * Callback for an XML processing instruction.
329 * The XML parser will invoke this method once for every processing
330 * instruction in the XML document. Note that the XML declaration
331 * and the Text declaration are NOT PROCESSING INSTRUCTIONS and
332 * will not be reported through this callback. Processing
333 * instructions are not all that useful, but the XML recommendation
334 * requires that they be reported. Most applications can safely
335 * ignore this callback and use the empty default implementation.
337 * @param target The processing instruction target (not null).
338 * @param data The processing instruction data (not null).
340 virtual void pi (const char * target, const char * data) {}
344 * Callback for an XML parsing warning.
346 * The XML parser will use this callback to report any non-fatal warnings
347 * during parsing. It is the responsibility of the application to
348 * deal with the warning in some appropriate way.
350 * @param message The warning message from the parser.
351 * @param line The number of the line that generated the warning.
352 * @param column The character position in the line that generated
355 virtual void warning (const char * message, int line, int column) {}
359 * Callback for a fatal XML parsing error.
361 * The XML parser will use this method to report any fatal errors
362 * during parsing. Once the first error callback is received,
363 * normal processing will stop, though additional errors may be
364 * reported. The application should take any appropriate
365 * error-handling procedures when it receives this callback, and
366 * should not attempt to use any of the data found in the XML
369 * @param message The error message from the parser.
370 * @param line The number of the line that generated the error.
371 * @param column The character position in the line that generated
374 virtual void error (const char * message, int line, int column) = 0;
379 * @relates XMLVisitor
380 * Read an XML document.
382 * This function reads an XML document from the input stream provided,
383 * and invokes the callback methods in the visitor object to pass the
384 * parsing events back to the application. When this function
385 * returns, the parser will have reported all of the data in the XML
386 * document to the application through the visitor callback methods,
387 * and XML processing will be complete.
389 * @param input The byte input stream containing the XML document.
390 * @param visitor An object that contains callbacks for XML parsing
392 * @return true if the parse succeeded, false if there was a fatal
396 extern bool readXML (istream &input, XMLVisitor &visitor);
399 #endif // __EASYXML_HXX