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>
18 typedef struct XML_ParserStruct* XML_Parser;
21 * Interface for XML attributes.
23 * This interface is used to provide a list of attributes to the
24 * application. The interface is a pure abstract class so that
25 * different implementations can be substituted for the sake of
28 * @see XMLAttributesDefault
43 virtual ~ XMLAttributes ();
47 * Get the number of attributes present.
49 * @return The number of attributes in the list (may be 0).
51 virtual int size () const = 0;
55 * Get the name of an attribute by index.
57 * The index must be less than the size of the list and greater
58 * than or equal to zero.
60 * @param i The index of the attribute (zero-based).
63 virtual const char * getName (int i) const = 0;
67 * Get the string value of an attribute by index.
69 * The index must be less than the size of the list and greater
70 * than or equal to zero.
72 * @param i The index of the attribute (zero-based).
75 virtual const char * getValue (int i) const = 0;
79 * Look up the index of an attribute by name.
81 * Attribute names must be unique. This method will return
82 * an index that can be used with the {@link #getValue(const char *)}
83 * method if the attribute is found.
85 * @param name The name of the attribute.
86 * @return The index of the attribute with the name specified,
87 * or -1 if no such attribute is present in the list.
89 virtual int findAttribute (const char * name) const;
93 * Test whether an attribute is present.
95 * @param name The name of the attribute.
96 * @return true if an attribute with the specified name is present
97 * in the attribute list, false otherwise.
99 virtual bool hasAttribute (const char * name) const;
103 * Look up the value of an attribute by name.
105 * This method provides a convenient short-cut to invoking
106 * {@link #findAttribute} and {@link #getValue(const char *)}.
108 * @param name The name of the attribute to look up.
109 * @return The attribute's value as a string, or 0 if no
110 * attribute was found with the name specified.
112 virtual const char * getValue (const char * name) const;
117 * Default mutable attributes implementation.
119 * This class provides a default implementation of the {@link
120 * XMLAttributes} interface. The implementation is mutable, so
121 * that it is possible to modify the attribute list when necessary.
122 * This class is particularly useful for taking a snapshot of
123 * an attribute list during parsing.
127 class XMLAttributesDefault : public XMLAttributes
132 * Default constructor.
134 XMLAttributesDefault ();
140 * This constructor is especially useful for taking a static
141 * snapshot of an attribute list for later use.
143 * @param atts The attribute list to copy.
145 XMLAttributesDefault (const XMLAttributes & atts);
151 virtual ~XMLAttributesDefault ();
155 * Count the attributes in the list.
157 virtual int size () const;
161 * Get the name of an attribute by index.
163 virtual const char * getName (int i) const;
167 * Get the value of an attribute by index.
169 virtual const char * getValue (int i) const;
173 * Add an attribute to an attribute list.
175 * The name is required to be unique in the list; the value is not.
177 * @param name The name of the attribute to add.
178 * @param value The value of the attribute to add.
180 virtual void addAttribute (const char * name, const char * value);
184 * Set an attribute name by index.
186 * This method will not extend the list; the attribute must
189 * @param i The index of the attribute (zero-based).
190 * @param name The new name.
192 virtual void setName (int i, const char * name);
196 * Set an attribute value by index.
198 * This method will not extend the list; the attribute must
201 * @param i The index of the attribute (zero-based).
202 * @param value The new value.
204 virtual void setValue (int i, const char * value);
208 * Set an attribute value by name.
210 * This method will not extend the list; the attribute must
213 * @param name The name of the attribute that will have the new
215 * @param value The new value.
217 virtual void setValue (const char * name, const char * value);
220 std::vector<std::string> _atts;
223 ////////////////////////////////////////////////////////////////////////
224 // Attribute list wrapper for Expat.
225 ////////////////////////////////////////////////////////////////////////
227 class ExpatAtts : public XMLAttributes
230 ExpatAtts (const char ** atts) : _atts(atts) {}
232 virtual int size () const;
233 virtual const char * getName (int i) const;
234 virtual const char * getValue (int i) const;
236 virtual const char * getValue (const char * name) const;
243 * Visitor class for an XML document.
245 * This interface uses the Visitor pattern. The XML parser walks
246 * through the XML document and invokes the appropriate method in
247 * this visitor for each piece of markup it finds. By default,
248 * the methods do nothing; the application must subclass the visitor
249 * and override the methods for the events it's interested in.
250 * All applications are required to provide an implementation
251 * for the {@link #error} callback.
257 XMLVisitor() : parser(0), line(-1), column(-1) {}
260 * Virtual destructor.
262 virtual ~XMLVisitor () {}
266 * Callback for the start of an XML document.
268 * The XML parser will invoke this method once, at the beginning of
269 * the XML document, before any other methods are invoked. The
270 * application can use this callback to set up data structures,
275 virtual void startXML () {}
279 * Callback for the end of an XML document.
281 * The XML parser will invoke this method once, at the end of the
282 * XML document, after all other methods are invoked, and only
283 * if there have been no parsing errors. The application can use
284 * this callback to close or write files, finalize data structures,
285 * and so on, but the application will need to be prepared to
286 * clean up any resources without this callback in the event of
292 virtual void endXML () {}
296 * Callback for the start of an XML element.
298 * The XML parser will invoke this method at the beginning of every
299 * XML element. Start and end element calls will be balanced
300 * and properly nested: every element has both a start and end
301 * callback (even if it was specified with an XML empty element tag),
302 * there is exactly one root element, and every element must end
303 * before its parent does. Elements may not overlap.
304 * Note that the attribute list provided is volatile; it's contents
305 * are not guaranteed to persist after the end of the callback.
306 * If the application needs to keep a copy of the attribute list,
307 * it can make the copy with the {@link XMLAttributesDefault} class.
309 * @param name The name of the element that is starting (not null).
310 * @param atts The element's attributes (not null).
313 virtual void startElement (const char * name, const XMLAttributes &atts) {}
317 * Callback for the end of an XML element.
319 * The XML parser will invoke this method at the end of every XML element.
321 * @param name The name of the element that is ending (not null).
324 virtual void endElement (const char * name) {}
328 * Callback for a chunk of character data.
330 * The XML parser will invoke this method once for every chunk of
331 * character data in the XML document, including whitespace
332 * separating elements (as required by the XML recommendation).
333 * Note that character data may be chunked arbitrarily: the
334 * character data content of an element may be returned in one
335 * large chunk or several consecutive smaller chunks.
337 * @param s A pointer to the beginning of the character data (not null).
338 * @param length The number of characters in the chunk (may
341 virtual void data (const char * s, int length) {}
345 * Callback for an XML processing instruction.
347 * The XML parser will invoke this method once for every processing
348 * instruction in the XML document. Note that the XML declaration
349 * and the Text declaration are NOT PROCESSING INSTRUCTIONS and
350 * will not be reported through this callback. Processing
351 * instructions are not all that useful, but the XML recommendation
352 * requires that they be reported. Most applications can safely
353 * ignore this callback and use the empty default implementation.
355 * @param target The processing instruction target (not null).
356 * @param data The processing instruction data (not null).
358 virtual void pi (const char * target, const char * data) {}
362 * Callback for an XML parsing warning.
364 * The XML parser will use this callback to report any non-fatal warnings
365 * during parsing. It is the responsibility of the application to
366 * deal with the warning in some appropriate way.
368 * @param message The warning message from the parser.
369 * @param line The number of the line that generated the warning.
370 * @param column The character position in the line that generated
373 virtual void warning (const char * message, int line, int column) {}
375 /** Set the path to the file that is parsed.
377 * This method will be called to store the path to the parsed file. Note that
378 * the XML parser makes no use of this copy of the path. The intent is
379 * to be capable of refering to the path to the parsed file if needed.
381 * @param _path The path to the parsed file.
384 void setPath(const std::string& _path) { path = _path; }
386 /** Get the path to the parsed file.
388 * This method will be called if the application needs to access the path to
389 * the parsed file. This information is typically needed if an error is found
390 * so the file where it occurred can be retrieved to help the user locate the
393 * @return the path to the parsed file.
396 const std::string& getPath(void) const { return path; }
398 /** Save the current position in the parsed file.
400 * This method will be called to save the position at which the file is
401 * currently parsed. Note that the XML parser makes no use of that
402 * information. The intent is to be capable of refering to the position in
403 * the parsed file if needed.
408 void savePosition(void);
410 /** Get the saved column number in the parsed file.
412 * This method will be called if the application needs to get the column
413 * number that has been saved during the last call to savePosition(). This
414 * information is typically needed if an error is found so the position at
415 * which it occurred can be retrieved to help the user locate the error.
417 * @return the save column number.
420 int getColumn(void) const { return column; }
422 /** Get the saved line number in the parsed file.
424 * This method will be called if the application needs to get the line
425 * number that has been saved during the last call to savePosition(). This
426 * information is typically needed if an error is found so the position at
427 * which it occurred can be retrieved to help the user locate the error.
429 * @return the save line number.
432 int getLine(void) const { return line; }
434 /** Set the XML parser.
436 * This method will be called so the #XMLVisitor instance can internally use
437 * the XML parser for its housekeeping. The intent is that #XMLVisitor will
438 * only call the reporting functions of the XML parser and will not interfer
439 * with the XML parser current state. Doing otherwise will result in an
440 * unpredictable behavior of the XML parser.
442 * @param _parser the XML parser
444 void setParser(XML_Parser _parser) { parser = _parser; }
453 * @relates XMLVisitor
454 * Read an XML document.
456 * This function reads an XML document from the input stream provided,
457 * and invokes the callback methods in the visitor object to pass the
458 * parsing events back to the application. When this function
459 * returns, the parser will have reported all of the data in the XML
460 * document to the application through the visitor callback methods,
461 * and XML processing will be complete.
463 * @param input The byte input stream containing the XML document.
464 * @param visitor An object that contains callbacks for XML parsing
466 * @param path A string describing the original path of the resource.
467 * @exception Throws sg_io_exception or sg_xml_exception if there
468 * is a problem reading the file.
471 extern void readXML (std::istream &input, XMLVisitor &visitor,
472 const std::string &path="");
476 * @relates XMLVisitor
477 * Read an XML document.
479 * This function reads an XML document from the input stream provided,
480 * and invokes the callback methods in the visitor object to pass the
481 * parsing events back to the application. When this function
482 * returns, the parser will have reported all of the data in the XML
483 * document to the application through the visitor callback methods,
484 * and XML processing will be complete.
486 * @param path The file name of the XML resource.
487 * @param visitor An object that contains callbacks for XML parsing
489 * @exception Throws sg_io_exception or sg_xml_exception if there
490 * is a problem reading the file.
493 extern void readXML (const std::string &path, XMLVisitor &visitor);
497 * @relates XMLVisitor
498 * Read an XML document.
500 * This function reads an XML document from the buffer provided,
501 * and invokes the callback methods in the visitor object to pass the
502 * parsing events back to the application. When this function
503 * returns, the parser will have reported all of the data in the XML
504 * document to the application through the visitor callback methods,
505 * and XML processing will be complete.
507 * @param buf The xml data buffer.
508 * @param size The size of the data buffer in bytes
509 * @param visitor An object that contains callbacks for XML parsing
511 * @exception Throws sg_io_exception or sg_xml_exception if there
512 * is a problem reading the file.
515 extern void readXML (const char *buf, const int size, XMLVisitor &visitor);
518 #endif // __EASYXML_HXX