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.
11 #include <simgear/compiler.h>
12 #include <simgear/structure/exception.hxx>
24 * Interface for XML attributes.
26 * This interface is used to provide a list of attributes to the
27 * application. The interface is a pure abstract class so that
28 * different implementations can be substituted for the sake of
31 * @see XMLAttributesDefault
46 virtual ~ XMLAttributes ();
50 * Get the number of attributes present.
52 * @return The number of attributes in the list (may be 0).
54 virtual int size () const = 0;
58 * Get the name of an attribute by index.
60 * The index must be less than the size of the list and greater
61 * than or equal to zero.
63 * @param i The index of the attribute (zero-based).
66 virtual const char * getName (int i) const = 0;
70 * Get the string value of an attribute by index.
72 * The index must be less than the size of the list and greater
73 * than or equal to zero.
75 * @param i The index of the attribute (zero-based).
78 virtual const char * getValue (int i) const = 0;
82 * Look up the index of an attribute by name.
84 * Attribute names must be unique. This method will return
85 * an index that can be used with the {@link #getValue(const char *)}
86 * method if the attribute is found.
88 * @param name The name of the attribute.
89 * @return The index of the attribute with the name specified,
90 * or -1 if no such attribute is present in the list.
92 virtual int findAttribute (const char * name) const;
96 * Test whether an attribute is present.
98 * @param name The name of the attribute.
99 * @return true if an attribute with the specified name is present
100 * in the attribute list, false otherwise.
102 virtual bool hasAttribute (const char * name) const;
106 * Look up the value of an attribute by name.
108 * This method provides a convenient short-cut to invoking
109 * {@link #findAttribute} and {@link #getValue(const char *)}.
111 * @param name The name of the attribute to look up.
112 * @return The attribute's value as a string, or 0 if no
113 * attribute was found with the name specified.
115 virtual const char * getValue (const char * name) const;
120 * Default mutable attributes implementation.
122 * This class provides a default implementation of the {@link
123 * XMLAttributes} interface. The implementation is mutable, so
124 * that it is possible to modify the attribute list when necessary.
125 * This class is particularly useful for taking a snapshot of
126 * an attribute list during parsing.
130 class XMLAttributesDefault : public XMLAttributes
135 * Default constructor.
137 XMLAttributesDefault ();
143 * This constructor is especially useful for taking a static
144 * snapshot of an attribute list for later use.
146 * @param atts The attribute list to copy.
148 XMLAttributesDefault (const XMLAttributes & atts);
154 virtual ~XMLAttributesDefault ();
158 * Count the attributes in the list.
160 virtual int size () const;
164 * Get the name of an attribute by index.
166 virtual const char * getName (int i) const;
170 * Get the value of an attribute by index.
172 virtual const char * getValue (int i) const;
176 * Add an attribute to an attribute list.
178 * The name is required to be unique in the list; the value is not.
180 * @param name The name of the attribute to add.
181 * @param value The value of the attribute to add.
183 virtual void addAttribute (const char * name, const char * value);
187 * Set an attribute name by index.
189 * This method will not extend the list; the attribute must
192 * @param i The index of the attribute (zero-based).
193 * @param name The new name.
195 virtual void setName (int i, const char * name);
199 * Set an attribute value by index.
201 * This method will not extend the list; the attribute must
204 * @param i The index of the attribute (zero-based).
205 * @param value The new value.
207 virtual void setValue (int i, const char * value);
211 * Set an attribute value by name.
213 * This method will not extend the list; the attribute must
216 * @param name The name of the attribute that will have the new
218 * @param value The new value.
220 virtual void setValue (const char * name, const char * value);
223 vector<string> _atts;
226 ////////////////////////////////////////////////////////////////////////
227 // Attribute list wrapper for Expat.
228 ////////////////////////////////////////////////////////////////////////
230 class ExpatAtts : public XMLAttributes
233 ExpatAtts (const char ** atts) : _atts(atts) {}
235 virtual int size () const;
236 virtual const char * getName (int i) const;
237 virtual const char * getValue (int i) const;
239 virtual const char * getValue (const char * name) const;
246 * Visitor class for an XML document.
248 * This interface uses the Visitor pattern. The XML parser walks
249 * through the XML document and invokes the appropriate method in
250 * this visitor for each piece of markup it finds. By default,
251 * the methods do nothing; the application must subclass the visitor
252 * and override the methods for the events it's interested in.
253 * All applications are required to provide an implementation
254 * for the {@link #error} callback.
261 * Virtual destructor.
263 virtual ~XMLVisitor () {}
267 * Callback for the start of an XML document.
269 * The XML parser will invoke this method once, at the beginning of
270 * the XML document, before any other methods are invoked. The
271 * application can use this callback to set up data structures,
276 virtual void startXML () {}
280 * Callback for the end of an XML document.
282 * The XML parser will invoke this method once, at the end of the
283 * XML document, after all other methods are invoked, and only
284 * if there have been no parsing errors. The application can use
285 * this callback to close or write files, finalize data structures,
286 * and so on, but the application will need to be prepared to
287 * clean up any resources without this callback in the event of
293 virtual void endXML () {}
297 * Callback for the start of an XML element.
299 * The XML parser will invoke this method at the beginning of every
300 * XML element. Start and end element calls will be balanced
301 * and properly nested: every element has both a start and end
302 * callback (even if it was specified with an XML empty element tag),
303 * there is exactly one root element, and every element must end
304 * before its parent does. Elements may not overlap.
305 * Note that the attribute list provided is volatile; it's contents
306 * are not guaranteed to persist after the end of the callback.
307 * If the application needs to keep a copy of the attribute list,
308 * it can make the copy with the {@link XMLAttributesDefault} class.
310 * @param name The name of the element that is starting (not null).
311 * @param atts The element's attributes (not null).
314 virtual void startElement (const char * name, const XMLAttributes &atts) {}
318 * Callback for the end of an XML element.
320 * The XML parser will invoke this method at the end of every XML element.
322 * @param name The name of the element that is ending (not null).
325 virtual void endElement (const char * name) {}
329 * Callback for a chunk of character data.
331 * The XML parser will invoke this method once for every chunk of
332 * character data in the XML document, including whitespace
333 * separating elements (as required by the XML recommendation).
334 * Note that character data may be chunked arbitrarily: the
335 * character data content of an element may be returned in one
336 * large chunk or several consecutive smaller chunks.
338 * @param s A pointer to the beginning of the character data (not null).
339 * @param length The number of characters in the chunk (may
342 virtual void data (const char * s, int length) {}
346 * Callback for an XML processing instruction.
348 * The XML parser will invoke this method once for every processing
349 * instruction in the XML document. Note that the XML declaration
350 * and the Text declaration are NOT PROCESSING INSTRUCTIONS and
351 * will not be reported through this callback. Processing
352 * instructions are not all that useful, but the XML recommendation
353 * requires that they be reported. Most applications can safely
354 * ignore this callback and use the empty default implementation.
356 * @param target The processing instruction target (not null).
357 * @param data The processing instruction data (not null).
359 virtual void pi (const char * target, const char * data) {}
363 * Callback for an XML parsing warning.
365 * The XML parser will use this callback to report any non-fatal warnings
366 * during parsing. It is the responsibility of the application to
367 * deal with the warning in some appropriate way.
369 * @param message The warning message from the parser.
370 * @param line The number of the line that generated the warning.
371 * @param column The character position in the line that generated
374 virtual void warning (const char * message, int line, int column) {}
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 * @param path A string describing the original path of the resource.
393 * @exception Throws sg_io_exception or sg_xml_exception if there
394 * is a problem reading the file.
397 extern void readXML (istream &input, XMLVisitor &visitor,
398 const string &path="");
402 * @relates XMLVisitor
403 * Read an XML document.
405 * This function reads an XML document from the input stream provided,
406 * and invokes the callback methods in the visitor object to pass the
407 * parsing events back to the application. When this function
408 * returns, the parser will have reported all of the data in the XML
409 * document to the application through the visitor callback methods,
410 * and XML processing will be complete.
412 * @param path The file name of the XML resource.
413 * @param visitor An object that contains callbacks for XML parsing
415 * @exception Throws sg_io_exception or sg_xml_exception if there
416 * is a problem reading the file.
419 extern void readXML (const string &path, XMLVisitor &visitor);
423 * @relates XMLVisitor
424 * Read an XML document.
426 * This function reads an XML document from the buffer provided,
427 * and invokes the callback methods in the visitor object to pass the
428 * parsing events back to the application. When this function
429 * returns, the parser will have reported all of the data in the XML
430 * document to the application through the visitor callback methods,
431 * and XML processing will be complete.
433 * @param buf The xml data buffer.
434 * @param size The size of the data buffer in bytes
435 * @param visitor An object that contains callbacks for XML parsing
437 * @exception Throws sg_io_exception or sg_xml_exception if there
438 * is a problem reading the file.
441 extern void readXML (const char *buf, const int size, XMLVisitor &visitor);
444 #endif // __EASYXML_HXX