simgear/xml/easyxml.hxx

   1 /**
   2  * \file easyxml.hxx
   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.
   6  */
   7
   8 #ifndef __EASYXML_HXX
   9 #define __EASYXML_HXX
  10
  11 #ifdef HAVE_CONFIG_H
  12 #  include <config.h>
  13 #endif
  14
  15 #include <simgear/compiler.h>
  16
  17 #include STL_IOSTREAM
  18 #include STL_STRING
  19 #include <vector>
  20
  21 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
  22 SG_USING_STD(istream);
  23 #endif
  24 SG_USING_STD(string);
  25 SG_USING_STD(vector);
  26
  27
  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 class XMLAttributes
  39 {
  40 public:
  41
  42   /**
  43    * Constructor.
  44    */
  45   XMLAttributes ();
  46
  47
  48   /**
  49    * Destructor.
  50    */
  51   virtual ~ XMLAttributes ();
  52
  53
  54   /**
  55    * Get the number of attributes present.
  56    *
  57    * @return The number of attributes in the list (may be 0).
  58    */
  59   virtual int size () const = 0;
  60
  61
  62   /**
  63    * Get the name of an attribute by index.
  64    *
  65    * The index must be less than the size of the list and greater
  66    * than or equal to zero.
  67    *
  68    * @param i The index of the attribute (zero-based).
  69    * @see #size
  70    */
  71   virtual const char * getName (int i) const = 0;
  72
  73
  74   /**
  75    * Get the string value of an attribute by index.
  76    *
  77    * The index must be less than the size of the list and greater
  78    * than or equal to zero.
  79    *
  80    * @param i The index of the attribute (zero-based).
  81    * @see #size
  82    */
  83   virtual const char * getValue (int i) const = 0;
  84
  85
  86   /**
  87    * Look up the index of an attribute by name.
  88    *
  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.
  92    *
  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.
  96    */
  97   virtual int findAttribute (const char * name) const;
  98
  99
 100   /**
 101    * Test whether an attribute is present.
 102    *
 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.
 106    */
 107   virtual bool hasAttribute (const char * name) const;
 108
 109
 110   /**
 111    * Look up the value of an attribute by name.
 112    *
 113    * This method provides a convenient short-cut to invoking
 114    * {@link #findAttribute} and {@link #getValue(const char *)}.
 115    *
 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.
 119    */
 120   virtual const char * getValue (const char * name) const;
 121 };
 122
 123
 124 /**
 125  * Default mutable attributes implementation.
 126  *
 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.
 132  *
 133  * @see XMLAttributes
 134  */
 135 class XMLAttributesDefault : public XMLAttributes
 136 {
 137 public:
 138
 139   /**
 140    * Default constructor.
 141    */
 142   XMLAttributesDefault ();
 143
 144
 145   /**
 146    * Copy constructor.
 147    *
 148    * This constructor is especially useful for taking a static
 149    * snapshot of an attribute list for later use.
 150    *
 151    * @param atts The attribute list to copy.
 152    */
 153   XMLAttributesDefault (const XMLAttributes & atts);
 154
 155
 156   /**
 157    * Destructor.
 158    */
 159   virtual ~XMLAttributesDefault ();
 160
 161
 162   /**
 163    * Count the attributes in the list.
 164    */
 165   virtual int size () const;
 166
 167
 168   /**
 169    * Get the name of an attribute by index.
 170    */
 171   virtual const char * getName (int i) const;
 172
 173
 174   /**
 175    * Get the value of an attribute by index.
 176    */
 177   virtual const char * getValue (int i) const;
 178
 179
 180   /**
 181    * Add an attribute to an attribute list.
 182    *
 183    * The name is required to be unique in the list; the value is not.
 184    *
 185    * @param name The name of the attribute to add.
 186    * @param value The value of the attribute to add.
 187    */
 188   virtual void addAttribute (const char * name, const char * value);
 189
 190
 191   /**
 192    * Set an attribute name by index.
 193    *
 194    * This method will not extend the list; the attribute must
 195    * already exist.
 196    *
 197    * @param i The index of the attribute (zero-based).
 198    * @param name The new name.
 199    */
 200   virtual void setName (int i, const char * name);
 201
 202
 203   /**
 204    * Set an attribute value by index.
 205    *
 206    * This method will not extend the list; the attribute must
 207    * already exist.
 208    *
 209    * @param i The index of the attribute (zero-based).
 210    * @param value The new value.
 211    */
 212   virtual void setValue (int i, const char * value);
 213
 214
 215   /**
 216    * Set an attribute value by name.
 217    *
 218    * This method will not extend the list; the attribute must
 219    * already exist.
 220    *
 221    * @param name The name of the attribute that will have the new
 222    * value.
 223    * @param value The new value.
 224    */
 225   virtual void setValue (const char * name, const char * value);
 226
 227 private:
 228   vector<string> _atts;
 229 };
 230
 231
 232 /**
 233  * Visitor class for an XML document.
 234  *
 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.
 242  */
 243 class XMLVisitor
 244 {
 245 public:
 246
 247   /**
 248    * Callback for the start of an XML document.
 249    *
 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,
 253    * open files, etc.
 254    *
 255    * @see #endXML
 256    */
 257   virtual void startXML () {}
 258
 259
 260   /**
 261    * Callback for the end of an XML document.
 262    *
 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
 269    * an error.
 270    *
 271    * @see #startXML
 272    * @see #error
 273    */
 274   virtual void endXML () {}
 275
 276
 277   /**
 278    * Callback for the start of an XML element.
 279    *
 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.
 290    *
 291    * @param name The name of the element that is starting (not null).
 292    * @param atts The element's attributes (not null).
 293    * @see #endElement
 294    */
 295   virtual void startElement (const char * name, const XMLAttributes &atts) {}
 296
 297
 298   /**
 299    * Callback for the end of an XML element.
 300    *
 301    * The XML parser will invoke this method at the end of every XML element.
 302    *
 303    * @param name The name of the element that is ending (not null).
 304    * @see #startElement
 305    */
 306   virtual void endElement (const char * name) {}
 307
 308
 309   /**
 310    * Callback for a chunk of character data.
 311    *
 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.
 318    *
 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
 321    * be zero).
 322    */
 323   virtual void data (const char * s, int length) {}
 324
 325
 326   /**
 327    * Callback for an XML processing instruction.
 328    *
 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.
 336    *
 337    * @param target The processing instruction target (not null).
 338    * @param data The processing instruction data (not null).
 339    */
 340   virtual void pi (const char * target, const char * data) {}
 341
 342
 343   /**
 344    * Callback for an XML parsing warning.
 345    *
 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.
 349    *
 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
 353    * the warning.
 354    */
 355   virtual void warning (const char * message, int line, int column) {}
 356
 357
 358   /**
 359    * Callback for a fatal XML parsing error.
 360    *
 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
 367    * document.
 368    *
 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
 372    * the error.
 373    */
 374   virtual void error (const char * message, int line, int column) = 0;
 375 };
 376
 377
 378 /**
 379  * @relates XMLVisitor
 380  * Read an XML document.
 381  *
 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.
 388  *
 389  * @param input The byte input stream containing the XML document.
 390  * @param visitor An object that contains callbacks for XML parsing
 391  * events.
 392  * @return true if the parse succeeded, false if there was a fatal
 393  * error.
 394  * @see XMLVisitor
 395  */
 396 extern bool readXML (istream &input, XMLVisitor &visitor);
 397
 398
 399 #endif // __EASYXML_HXX
 400