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 #include <simgear/compiler.h>
  12
  13 #include <simgear/misc/exception.hxx>
  14
  15 #include STL_IOSTREAM
  16 #include STL_STRING
  17 #include <vector>
  18
  19 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
  20 SG_USING_STD(istream);
  21 #endif
  22 SG_USING_STD(string);
  23 SG_USING_STD(vector);
  24
  25
  26 /**
  27  * Exception for an low-level XML parsing error.
  28  */
  29 class sg_xml_exception : public sg_io_exception
  30 {
  31 public:
  32   sg_xml_exception ();
  33   sg_xml_exception (const string &message);
  34   sg_xml_exception (const string &message, const sg_location &location);
  35   virtual ~sg_xml_exception ();
  36 };
  37
  38
  39 /**
  40  * Interface for XML attributes.
  41  *
  42  * This interface is used to provide a list of attributes to the
  43  * application.  The interface is a pure abstract class so that
  44  * different implementations can be substituted for the sake of
  45  * efficiency.
  46  *
  47  * @see XMLAttributesDefault
  48  */
  49 class XMLAttributes
  50 {
  51 public:
  52
  53   /**
  54    * Constructor.
  55    */
  56   XMLAttributes ();
  57
  58
  59   /**
  60    * Destructor.
  61    */
  62   virtual ~ XMLAttributes ();
  63
  64
  65   /**
  66    * Get the number of attributes present.
  67    *
  68    * @return The number of attributes in the list (may be 0).
  69    */
  70   virtual int size () const = 0;
  71
  72
  73   /**
  74    * Get the name of an attribute by index.
  75    *
  76    * The index must be less than the size of the list and greater
  77    * than or equal to zero.
  78    *
  79    * @param i The index of the attribute (zero-based).
  80    * @see #size
  81    */
  82   virtual const char * getName (int i) const = 0;
  83
  84
  85   /**
  86    * Get the string value of an attribute by index.
  87    *
  88    * The index must be less than the size of the list and greater
  89    * than or equal to zero.
  90    *
  91    * @param i The index of the attribute (zero-based).
  92    * @see #size
  93    */
  94   virtual const char * getValue (int i) const = 0;
  95
  96
  97   /**
  98    * Look up the index of an attribute by name.
  99    *
 100    * Attribute names must be unique.  This method will return
 101    * an index that can be used with the {@link #getValue(const char *)}
 102    * method if the attribute is found.
 103    *
 104    * @param name The name of the attribute.
 105    * @return The index of the attribute with the name specified,
 106    * or -1 if no such attribute is present in the list.
 107    */
 108   virtual int findAttribute (const char * name) const;
 109
 110
 111   /**
 112    * Test whether an attribute is present.
 113    *
 114    * @param name The name of the attribute.
 115    * @return true if an attribute with the specified name is present
 116    * in the attribute list, false otherwise.
 117    */
 118   virtual bool hasAttribute (const char * name) const;
 119
 120
 121   /**
 122    * Look up the value of an attribute by name.
 123    *
 124    * This method provides a convenient short-cut to invoking
 125    * {@link #findAttribute} and {@link #getValue(const char *)}.
 126    *
 127    * @param name The name of the attribute to look up.
 128    * @return The attribute's value as a string, or 0 if no
 129    * attribute was found with the name specified.
 130    */
 131   virtual const char * getValue (const char * name) const;
 132 };
 133
 134
 135 /**
 136  * Default mutable attributes implementation.
 137  *
 138  * This class provides a default implementation of the {@link
 139  * XMLAttributes} interface.  The implementation is mutable, so
 140  * that it is possible to modify the attribute list when necessary.
 141  * This class is particularly useful for taking a snapshot of
 142  * an attribute list during parsing.
 143  *
 144  * @see XMLAttributes
 145  */
 146 class XMLAttributesDefault : public XMLAttributes
 147 {
 148 public:
 149
 150   /**
 151    * Default constructor.
 152    */
 153   XMLAttributesDefault ();
 154
 155
 156   /**
 157    * Copy constructor.
 158    *
 159    * This constructor is especially useful for taking a static
 160    * snapshot of an attribute list for later use.
 161    *
 162    * @param atts The attribute list to copy.
 163    */
 164   XMLAttributesDefault (const XMLAttributes & atts);
 165
 166
 167   /**
 168    * Destructor.
 169    */
 170   virtual ~XMLAttributesDefault ();
 171
 172
 173   /**
 174    * Count the attributes in the list.
 175    */
 176   virtual int size () const;
 177
 178
 179   /**
 180    * Get the name of an attribute by index.
 181    */
 182   virtual const char * getName (int i) const;
 183
 184
 185   /**
 186    * Get the value of an attribute by index.
 187    */
 188   virtual const char * getValue (int i) const;
 189
 190
 191   /**
 192    * Add an attribute to an attribute list.
 193    *
 194    * The name is required to be unique in the list; the value is not.
 195    *
 196    * @param name The name of the attribute to add.
 197    * @param value The value of the attribute to add.
 198    */
 199   virtual void addAttribute (const char * name, const char * value);
 200
 201
 202   /**
 203    * Set an attribute name by index.
 204    *
 205    * This method will not extend the list; the attribute must
 206    * already exist.
 207    *
 208    * @param i The index of the attribute (zero-based).
 209    * @param name The new name.
 210    */
 211   virtual void setName (int i, const char * name);
 212
 213
 214   /**
 215    * Set an attribute value by index.
 216    *
 217    * This method will not extend the list; the attribute must
 218    * already exist.
 219    *
 220    * @param i The index of the attribute (zero-based).
 221    * @param value The new value.
 222    */
 223   virtual void setValue (int i, const char * value);
 224
 225
 226   /**
 227    * Set an attribute value by name.
 228    *
 229    * This method will not extend the list; the attribute must
 230    * already exist.
 231    *
 232    * @param name The name of the attribute that will have the new
 233    * value.
 234    * @param value The new value.
 235    */
 236   virtual void setValue (const char * name, const char * value);
 237
 238 private:
 239   vector<string> _atts;
 240 };
 241
 242
 243 /**
 244  * Visitor class for an XML document.
 245  *
 246  * This interface uses the Visitor pattern.  The XML parser walks
 247  * through the XML document and invokes the appropriate method in
 248  * this visitor for each piece of markup it finds.  By default,
 249  * the methods do nothing; the application must subclass the visitor
 250  * and override the methods for the events it's interested in.
 251  * All applications are required to provide an implementation
 252  * for the {@link #error} callback.
 253  */
 254 class XMLVisitor
 255 {
 256 public:
 257
 258   /**
 259    * Virtual destructor.
 260    */
 261   virtual ~XMLVisitor () {}
 262
 263
 264   /**
 265    * Callback for the start of an XML document.
 266    *
 267    * The XML parser will invoke this method once, at the beginning of
 268    * the XML document, before any other methods are invoked.  The
 269    * application can use this callback to set up data structures,
 270    * open files, etc.
 271    *
 272    * @see #endXML
 273    */
 274   virtual void startXML () {}
 275
 276
 277   /**
 278    * Callback for the end of an XML document.
 279    *
 280    * The XML parser will invoke this method once, at the end of the
 281    * XML document, after all other methods are invoked, and only
 282    * if there have been no parsing errors.  The application can use
 283    * this callback to close or write files, finalize data structures,
 284    * and so on, but the application will need to be prepared to
 285    * clean up any resources without this callback in the event of
 286    * an error.
 287    *
 288    * @see #startXML
 289    * @see #error
 290    */
 291   virtual void endXML () {}
 292
 293
 294   /**
 295    * Callback for the start of an XML element.
 296    *
 297    * The XML parser will invoke this method at the beginning of every
 298    * XML element.  Start and end element calls will be balanced
 299    * and properly nested: every element has both a start and end
 300    * callback (even if it was specified with an XML empty element tag),
 301    * there is exactly one root element, and every element must end
 302    * before its parent does.  Elements may not overlap.
 303    * Note that the attribute list provided is volatile; it's contents
 304    * are not guaranteed to persist after the end of the callback.
 305    * If the application needs to keep a copy of the attribute list,
 306    * it can make the copy with the {@link XMLAttributesDefault} class.
 307    *
 308    * @param name The name of the element that is starting (not null).
 309    * @param atts The element's attributes (not null).
 310    * @see #endElement
 311    */
 312   virtual void startElement (const char * name, const XMLAttributes &atts) {}
 313
 314
 315   /**
 316    * Callback for the end of an XML element.
 317    *
 318    * The XML parser will invoke this method at the end of every XML element.
 319    *
 320    * @param name The name of the element that is ending (not null).
 321    * @see #startElement
 322    */
 323   virtual void endElement (const char * name) {}
 324
 325
 326   /**
 327    * Callback for a chunk of character data.
 328    *
 329    * The XML parser will invoke this method once for every chunk of
 330    * character data in the XML document, including whitespace
 331    * separating elements (as required by the XML recommendation).
 332    * Note that character data may be chunked arbitrarily: the
 333    * character data content of an element may be returned in one
 334    * large chunk or several consecutive smaller chunks.
 335    *
 336    * @param s A pointer to the beginning of the character data (not null).
 337    * @param length The number of characters in the chunk (may
 338    * be zero).
 339    */
 340   virtual void data (const char * s, int length) {}
 341
 342
 343   /**
 344    * Callback for an XML processing instruction.
 345    *
 346    * The XML parser will invoke this method once for every processing
 347    * instruction in the XML document.  Note that the XML declaration
 348    * and the Text declaration are NOT PROCESSING INSTRUCTIONS and
 349    * will not be reported through this callback.  Processing
 350    * instructions are not all that useful, but the XML recommendation
 351    * requires that they be reported.  Most applications can safely
 352    * ignore this callback and use the empty default implementation.
 353    *
 354    * @param target The processing instruction target (not null).
 355    * @param data The processing instruction data (not null).
 356    */
 357   virtual void pi (const char * target, const char * data) {}
 358
 359
 360   /**
 361    * Callback for an XML parsing warning.
 362    *
 363    * The XML parser will use this callback to report any non-fatal warnings
 364    * during parsing.  It is the responsibility of the application to
 365    * deal with the warning in some appropriate way.
 366    *
 367    * @param message The warning message from the parser.
 368    * @param line The number of the line that generated the warning.
 369    * @param column The character position in the line that generated
 370    * the warning.
 371    */
 372   virtual void warning (const char * message, int line, int column) {}
 373 };
 374
 375
 376 /**
 377  * @relates XMLVisitor
 378  * Read an XML document.
 379  *
 380  * This function reads an XML document from the input stream provided,
 381  * and invokes the callback methods in the visitor object to pass the
 382  * parsing events back to the application.  When this function
 383  * returns, the parser will have reported all of the data in the XML
 384  * document to the application through the visitor callback methods,
 385  * and XML processing will be complete.
 386  *
 387  * @param input The byte input stream containing the XML document.
 388  * @param visitor An object that contains callbacks for XML parsing
 389  * events.
 390  * @param path A string describing the original path of the resource.
 391  * @exception Throws sg_io_exception or sg_xml_exception if there
 392  * is a problem reading the file.
 393  * @see XMLVisitor
 394  */
 395 extern void readXML (istream &input, XMLVisitor &visitor,
 396                      const string &path="");
 397
 398
 399 /**
 400  * @relates XMLVisitor
 401  * Read an XML document.
 402  *
 403  * This function reads an XML document from the input stream provided,
 404  * and invokes the callback methods in the visitor object to pass the
 405  * parsing events back to the application.  When this function
 406  * returns, the parser will have reported all of the data in the XML
 407  * document to the application through the visitor callback methods,
 408  * and XML processing will be complete.
 409  *
 410  * @param path The file name of the XML resource.
 411  * @param visitor An object that contains callbacks for XML parsing
 412  * events.
 413  * @exception Throws sg_io_exception or sg_xml_exception if there
 414  * is a problem reading the file.
 415  * @see XMLVisitor
 416  */
 417 extern void readXML (const string &path, XMLVisitor &visitor);
 418
 419
 420 #endif // __EASYXML_HXX
 421