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>
13 #include <simgear/misc/exception.hxx>
19 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
20 SG_USING_STD(istream);
27 * Interface for XML attributes.
29 * This interface is used to provide a list of attributes to the
30 * application. The interface is a pure abstract class so that
31 * different implementations can be substituted for the sake of
34 * @see XMLAttributesDefault
49 virtual ~ XMLAttributes ();
53 * Get the number of attributes present.
55 * @return The number of attributes in the list (may be 0).
57 virtual int size () const = 0;
61 * Get the name of an attribute by index.
63 * The index must be less than the size of the list and greater
64 * than or equal to zero.
66 * @param i The index of the attribute (zero-based).
69 virtual const char * getName (int i) const = 0;
73 * Get the string value of an attribute by index.
75 * The index must be less than the size of the list and greater
76 * than or equal to zero.
78 * @param i The index of the attribute (zero-based).
81 virtual const char * getValue (int i) const = 0;
85 * Look up the index of an attribute by name.
87 * Attribute names must be unique. This method will return
88 * an index that can be used with the {@link #getValue(const char *)}
89 * method if the attribute is found.
91 * @param name The name of the attribute.
92 * @return The index of the attribute with the name specified,
93 * or -1 if no such attribute is present in the list.
95 virtual int findAttribute (const char * name) const;
99 * Test whether an attribute is present.
101 * @param name The name of the attribute.
102 * @return true if an attribute with the specified name is present
103 * in the attribute list, false otherwise.
105 virtual bool hasAttribute (const char * name) const;
109 * Look up the value of an attribute by name.
111 * This method provides a convenient short-cut to invoking
112 * {@link #findAttribute} and {@link #getValue(const char *)}.
114 * @param name The name of the attribute to look up.
115 * @return The attribute's value as a string, or 0 if no
116 * attribute was found with the name specified.
118 virtual const char * getValue (const char * name) const;
123 * Default mutable attributes implementation.
125 * This class provides a default implementation of the {@link
126 * XMLAttributes} interface. The implementation is mutable, so
127 * that it is possible to modify the attribute list when necessary.
128 * This class is particularly useful for taking a snapshot of
129 * an attribute list during parsing.
133 class XMLAttributesDefault : public XMLAttributes
138 * Default constructor.
140 XMLAttributesDefault ();
146 * This constructor is especially useful for taking a static
147 * snapshot of an attribute list for later use.
149 * @param atts The attribute list to copy.
151 XMLAttributesDefault (const XMLAttributes & atts);
157 virtual ~XMLAttributesDefault ();
161 * Count the attributes in the list.
163 virtual int size () const;
167 * Get the name of an attribute by index.
169 virtual const char * getName (int i) const;
173 * Get the value of an attribute by index.
175 virtual const char * getValue (int i) const;
179 * Add an attribute to an attribute list.
181 * The name is required to be unique in the list; the value is not.
183 * @param name The name of the attribute to add.
184 * @param value The value of the attribute to add.
186 virtual void addAttribute (const char * name, const char * value);
190 * Set an attribute name by index.
192 * This method will not extend the list; the attribute must
195 * @param i The index of the attribute (zero-based).
196 * @param name The new name.
198 virtual void setName (int i, const char * name);
202 * Set an attribute value by index.
204 * This method will not extend the list; the attribute must
207 * @param i The index of the attribute (zero-based).
208 * @param value The new value.
210 virtual void setValue (int i, const char * value);
214 * Set an attribute value by name.
216 * This method will not extend the list; the attribute must
219 * @param name The name of the attribute that will have the new
221 * @param value The new value.
223 virtual void setValue (const char * name, const char * value);
226 vector<string> _atts;
231 * Visitor class for an XML document.
233 * This interface uses the Visitor pattern. The XML parser walks
234 * through the XML document and invokes the appropriate method in
235 * this visitor for each piece of markup it finds. By default,
236 * the methods do nothing; the application must subclass the visitor
237 * and override the methods for the events it's interested in.
238 * All applications are required to provide an implementation
239 * for the {@link #error} callback.
246 * Virtual destructor.
248 virtual ~XMLVisitor () {}
252 * Callback for the start of an XML document.
254 * The XML parser will invoke this method once, at the beginning of
255 * the XML document, before any other methods are invoked. The
256 * application can use this callback to set up data structures,
261 virtual void startXML () {}
265 * Callback for the end of an XML document.
267 * The XML parser will invoke this method once, at the end of the
268 * XML document, after all other methods are invoked, and only
269 * if there have been no parsing errors. The application can use
270 * this callback to close or write files, finalize data structures,
271 * and so on, but the application will need to be prepared to
272 * clean up any resources without this callback in the event of
278 virtual void endXML () {}
282 * Callback for the start of an XML element.
284 * The XML parser will invoke this method at the beginning of every
285 * XML element. Start and end element calls will be balanced
286 * and properly nested: every element has both a start and end
287 * callback (even if it was specified with an XML empty element tag),
288 * there is exactly one root element, and every element must end
289 * before its parent does. Elements may not overlap.
290 * Note that the attribute list provided is volatile; it's contents
291 * are not guaranteed to persist after the end of the callback.
292 * If the application needs to keep a copy of the attribute list,
293 * it can make the copy with the {@link XMLAttributesDefault} class.
295 * @param name The name of the element that is starting (not null).
296 * @param atts The element's attributes (not null).
299 virtual void startElement (const char * name, const XMLAttributes &atts) {}
303 * Callback for the end of an XML element.
305 * The XML parser will invoke this method at the end of every XML element.
307 * @param name The name of the element that is ending (not null).
310 virtual void endElement (const char * name) {}
314 * Callback for a chunk of character data.
316 * The XML parser will invoke this method once for every chunk of
317 * character data in the XML document, including whitespace
318 * separating elements (as required by the XML recommendation).
319 * Note that character data may be chunked arbitrarily: the
320 * character data content of an element may be returned in one
321 * large chunk or several consecutive smaller chunks.
323 * @param s A pointer to the beginning of the character data (not null).
324 * @param length The number of characters in the chunk (may
327 virtual void data (const char * s, int length) {}
331 * Callback for an XML processing instruction.
333 * The XML parser will invoke this method once for every processing
334 * instruction in the XML document. Note that the XML declaration
335 * and the Text declaration are NOT PROCESSING INSTRUCTIONS and
336 * will not be reported through this callback. Processing
337 * instructions are not all that useful, but the XML recommendation
338 * requires that they be reported. Most applications can safely
339 * ignore this callback and use the empty default implementation.
341 * @param target The processing instruction target (not null).
342 * @param data The processing instruction data (not null).
344 virtual void pi (const char * target, const char * data) {}
348 * Callback for an XML parsing warning.
350 * The XML parser will use this callback to report any non-fatal warnings
351 * during parsing. It is the responsibility of the application to
352 * deal with the warning in some appropriate way.
354 * @param message The warning message from the parser.
355 * @param line The number of the line that generated the warning.
356 * @param column The character position in the line that generated
359 virtual void warning (const char * message, int line, int column) {}
364 * @relates XMLVisitor
365 * Read an XML document.
367 * This function reads an XML document from the input stream provided,
368 * and invokes the callback methods in the visitor object to pass the
369 * parsing events back to the application. When this function
370 * returns, the parser will have reported all of the data in the XML
371 * document to the application through the visitor callback methods,
372 * and XML processing will be complete.
374 * @param input The byte input stream containing the XML document.
375 * @param visitor An object that contains callbacks for XML parsing
377 * @param path A string describing the original path of the resource.
378 * @exception Throws sg_io_exception or sg_xml_exception if there
379 * is a problem reading the file.
382 extern void readXML (istream &input, XMLVisitor &visitor,
383 const string &path="");
387 * @relates XMLVisitor
388 * Read an XML document.
390 * This function reads an XML document from the input stream provided,
391 * and invokes the callback methods in the visitor object to pass the
392 * parsing events back to the application. When this function
393 * returns, the parser will have reported all of the data in the XML
394 * document to the application through the visitor callback methods,
395 * and XML processing will be complete.
397 * @param path The file name of the XML resource.
398 * @param visitor An object that contains callbacks for XML parsing
400 * @exception Throws sg_io_exception or sg_xml_exception if there
401 * is a problem reading the file.
404 extern void readXML (const string &path, XMLVisitor &visitor);
407 #endif // __EASYXML_HXX