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 #include <simgear/structure/exception.hxx>
  13
  14 #include <iostream>
  15 #include <string>
  16 #include <vector>
  17
  18 using std::istream;
  19 using std::string;
  20 using std::vector;
  21
  22
  23 /**
  24  * Interface for XML attributes.
  25  *
  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
  29  * efficiency.
  30  *
  31  * @see XMLAttributesDefault
  32  */
  33 class XMLAttributes
  34 {
  35 public:
  36
  37   /**
  38    * Constructor.
  39    */
  40   XMLAttributes ();
  41
  42
  43   /**
  44    * Destructor.
  45    */
  46   virtual ~ XMLAttributes ();
  47
  48
  49   /**
  50    * Get the number of attributes present.
  51    *
  52    * @return The number of attributes in the list (may be 0).
  53    */
  54   virtual int size () const = 0;
  55
  56
  57   /**
  58    * Get the name of an attribute by index.
  59    *
  60    * The index must be less than the size of the list and greater
  61    * than or equal to zero.
  62    *
  63    * @param i The index of the attribute (zero-based).
  64    * @see #size
  65    */
  66   virtual const char * getName (int i) const = 0;
  67
  68
  69   /**
  70    * Get the string value of an attribute by index.
  71    *
  72    * The index must be less than the size of the list and greater
  73    * than or equal to zero.
  74    *
  75    * @param i The index of the attribute (zero-based).
  76    * @see #size
  77    */
  78   virtual const char * getValue (int i) const = 0;
  79
  80
  81   /**
  82    * Look up the index of an attribute by name.
  83    *
  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.
  87    *
  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.
  91    */
  92   virtual int findAttribute (const char * name) const;
  93
  94
  95   /**
  96    * Test whether an attribute is present.
  97    *
  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.
 101    */
 102   virtual bool hasAttribute (const char * name) const;
 103
 104
 105   /**
 106    * Look up the value of an attribute by name.
 107    *
 108    * This method provides a convenient short-cut to invoking
 109    * {@link #findAttribute} and {@link #getValue(const char *)}.
 110    *
 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.
 114    */
 115   virtual const char * getValue (const char * name) const;
 116 };
 117
 118
 119 /**
 120  * Default mutable attributes implementation.
 121  *
 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.
 127  *
 128  * @see XMLAttributes
 129  */
 130 class XMLAttributesDefault : public XMLAttributes
 131 {
 132 public:
 133
 134   /**
 135    * Default constructor.
 136    */
 137   XMLAttributesDefault ();
 138
 139
 140   /**
 141    * Copy constructor.
 142    *
 143    * This constructor is especially useful for taking a static
 144    * snapshot of an attribute list for later use.
 145    *
 146    * @param atts The attribute list to copy.
 147    */
 148   XMLAttributesDefault (const XMLAttributes & atts);
 149
 150
 151   /**
 152    * Destructor.
 153    */
 154   virtual ~XMLAttributesDefault ();
 155
 156
 157   /**
 158    * Count the attributes in the list.
 159    */
 160   virtual int size () const;
 161
 162
 163   /**
 164    * Get the name of an attribute by index.
 165    */
 166   virtual const char * getName (int i) const;
 167
 168
 169   /**
 170    * Get the value of an attribute by index.
 171    */
 172   virtual const char * getValue (int i) const;
 173
 174
 175   /**
 176    * Add an attribute to an attribute list.
 177    *
 178    * The name is required to be unique in the list; the value is not.
 179    *
 180    * @param name The name of the attribute to add.
 181    * @param value The value of the attribute to add.
 182    */
 183   virtual void addAttribute (const char * name, const char * value);
 184
 185
 186   /**
 187    * Set an attribute name by index.
 188    *
 189    * This method will not extend the list; the attribute must
 190    * already exist.
 191    *
 192    * @param i The index of the attribute (zero-based).
 193    * @param name The new name.
 194    */
 195   virtual void setName (int i, const char * name);
 196
 197
 198   /**
 199    * Set an attribute value by index.
 200    *
 201    * This method will not extend the list; the attribute must
 202    * already exist.
 203    *
 204    * @param i The index of the attribute (zero-based).
 205    * @param value The new value.
 206    */
 207   virtual void setValue (int i, const char * value);
 208
 209
 210   /**
 211    * Set an attribute value by name.
 212    *
 213    * This method will not extend the list; the attribute must
 214    * already exist.
 215    *
 216    * @param name The name of the attribute that will have the new
 217    * value.
 218    * @param value The new value.
 219    */
 220   virtual void setValue (const char * name, const char * value);
 221
 222 private:
 223   vector<string> _atts;
 224 };
 225
 226 ////////////////////////////////////////////////////////////////////////
 227 // Attribute list wrapper for Expat.
 228 ////////////////////////////////////////////////////////////////////////
 229
 230 class ExpatAtts : public XMLAttributes
 231 {
 232 public:
 233   ExpatAtts (const char ** atts) : _atts(atts) {}
 234
 235   virtual int size () const;
 236   virtual const char * getName (int i) const;
 237   virtual const char * getValue (int i) const;
 238
 239   virtual const char * getValue (const char * name) const;
 240 private:
 241   const char ** _atts;
 242 };
 243
 244
 245 /**
 246  * Visitor class for an XML document.
 247  *
 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.
 255  */
 256 class XMLVisitor
 257 {
 258 public:
 259
 260   /**
 261    * Virtual destructor.
 262    */
 263   virtual ~XMLVisitor () {}
 264
 265
 266   /**
 267    * Callback for the start of an XML document.
 268    *
 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,
 272    * open files, etc.
 273    *
 274    * @see #endXML
 275    */
 276   virtual void startXML () {}
 277
 278
 279   /**
 280    * Callback for the end of an XML document.
 281    *
 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
 288    * an error.
 289    *
 290    * @see #startXML
 291    * @see #error
 292    */
 293   virtual void endXML () {}
 294
 295
 296   /**
 297    * Callback for the start of an XML element.
 298    *
 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.
 309    *
 310    * @param name The name of the element that is starting (not null).
 311    * @param atts The element's attributes (not null).
 312    * @see #endElement
 313    */
 314   virtual void startElement (const char * name, const XMLAttributes &atts) {}
 315
 316
 317   /**
 318    * Callback for the end of an XML element.
 319    *
 320    * The XML parser will invoke this method at the end of every XML element.
 321    *
 322    * @param name The name of the element that is ending (not null).
 323    * @see #startElement
 324    */
 325   virtual void endElement (const char * name) {}
 326
 327
 328   /**
 329    * Callback for a chunk of character data.
 330    *
 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.
 337    *
 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
 340    * be zero).
 341    */
 342   virtual void data (const char * s, int length) {}
 343
 344
 345   /**
 346    * Callback for an XML processing instruction.
 347    *
 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.
 355    *
 356    * @param target The processing instruction target (not null).
 357    * @param data The processing instruction data (not null).
 358    */
 359   virtual void pi (const char * target, const char * data) {}
 360
 361
 362   /**
 363    * Callback for an XML parsing warning.
 364    *
 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.
 368    *
 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
 372    * the warning.
 373    */
 374   virtual void warning (const char * message, int line, int column) {}
 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  * @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.
 395  * @see XMLVisitor
 396  */
 397 extern void readXML (istream &input, XMLVisitor &visitor,
 398                      const string &path="");
 399
 400
 401 /**
 402  * @relates XMLVisitor
 403  * Read an XML document.
 404  *
 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.
 411  *
 412  * @param path The file name of the XML resource.
 413  * @param visitor An object that contains callbacks for XML parsing
 414  * events.
 415  * @exception Throws sg_io_exception or sg_xml_exception if there
 416  * is a problem reading the file.
 417  * @see XMLVisitor
 418  */
 419 extern void readXML (const string &path, XMLVisitor &visitor);
 420
 421
 422 /**
 423  * @relates XMLVisitor
 424  * Read an XML document.
 425  *
 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.
 432  *
 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
 436  * events.
 437  * @exception Throws sg_io_exception or sg_xml_exception if there
 438  * is a problem reading the file.
 439  * @see XMLVisitor
 440  */
 441 extern void readXML (const char *buf, const int size, XMLVisitor &visitor);
 442
 443
 444 #endif // __EASYXML_HXX
 445