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  * Interface for XML attributes.
  28  *
  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
  32  * efficiency.
  33  *
  34  * @see XMLAttributesDefault
  35  */
  36 class XMLAttributes
  37 {
  38 public:
  39
  40   /**
  41    * Constructor.
  42    */
  43   XMLAttributes ();
  44
  45
  46   /**
  47    * Destructor.
  48    */
  49   virtual ~ XMLAttributes ();
  50
  51
  52   /**
  53    * Get the number of attributes present.
  54    *
  55    * @return The number of attributes in the list (may be 0).
  56    */
  57   virtual int size () const = 0;
  58
  59
  60   /**
  61    * Get the name of an attribute by index.
  62    *
  63    * The index must be less than the size of the list and greater
  64    * than or equal to zero.
  65    *
  66    * @param i The index of the attribute (zero-based).
  67    * @see #size
  68    */
  69   virtual const char * getName (int i) const = 0;
  70
  71
  72   /**
  73    * Get the string value of an attribute by index.
  74    *
  75    * The index must be less than the size of the list and greater
  76    * than or equal to zero.
  77    *
  78    * @param i The index of the attribute (zero-based).
  79    * @see #size
  80    */
  81   virtual const char * getValue (int i) const = 0;
  82
  83
  84   /**
  85    * Look up the index of an attribute by name.
  86    *
  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.
  90    *
  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.
  94    */
  95   virtual int findAttribute (const char * name) const;
  96
  97
  98   /**
  99    * Test whether an attribute is present.
 100    *
 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.
 104    */
 105   virtual bool hasAttribute (const char * name) const;
 106
 107
 108   /**
 109    * Look up the value of an attribute by name.
 110    *
 111    * This method provides a convenient short-cut to invoking
 112    * {@link #findAttribute} and {@link #getValue(const char *)}.
 113    *
 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.
 117    */
 118   virtual const char * getValue (const char * name) const;
 119 };
 120
 121
 122 /**
 123  * Default mutable attributes implementation.
 124  *
 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.
 130  *
 131  * @see XMLAttributes
 132  */
 133 class XMLAttributesDefault : public XMLAttributes
 134 {
 135 public:
 136
 137   /**
 138    * Default constructor.
 139    */
 140   XMLAttributesDefault ();
 141
 142
 143   /**
 144    * Copy constructor.
 145    *
 146    * This constructor is especially useful for taking a static
 147    * snapshot of an attribute list for later use.
 148    *
 149    * @param atts The attribute list to copy.
 150    */
 151   XMLAttributesDefault (const XMLAttributes & atts);
 152
 153
 154   /**
 155    * Destructor.
 156    */
 157   virtual ~XMLAttributesDefault ();
 158
 159
 160   /**
 161    * Count the attributes in the list.
 162    */
 163   virtual int size () const;
 164
 165
 166   /**
 167    * Get the name of an attribute by index.
 168    */
 169   virtual const char * getName (int i) const;
 170
 171
 172   /**
 173    * Get the value of an attribute by index.
 174    */
 175   virtual const char * getValue (int i) const;
 176
 177
 178   /**
 179    * Add an attribute to an attribute list.
 180    *
 181    * The name is required to be unique in the list; the value is not.
 182    *
 183    * @param name The name of the attribute to add.
 184    * @param value The value of the attribute to add.
 185    */
 186   virtual void addAttribute (const char * name, const char * value);
 187
 188
 189   /**
 190    * Set an attribute name by index.
 191    *
 192    * This method will not extend the list; the attribute must
 193    * already exist.
 194    *
 195    * @param i The index of the attribute (zero-based).
 196    * @param name The new name.
 197    */
 198   virtual void setName (int i, const char * name);
 199
 200
 201   /**
 202    * Set an attribute value by index.
 203    *
 204    * This method will not extend the list; the attribute must
 205    * already exist.
 206    *
 207    * @param i The index of the attribute (zero-based).
 208    * @param value The new value.
 209    */
 210   virtual void setValue (int i, const char * value);
 211
 212
 213   /**
 214    * Set an attribute value by name.
 215    *
 216    * This method will not extend the list; the attribute must
 217    * already exist.
 218    *
 219    * @param name The name of the attribute that will have the new
 220    * value.
 221    * @param value The new value.
 222    */
 223   virtual void setValue (const char * name, const char * value);
 224
 225 private:
 226   vector<string> _atts;
 227 };
 228
 229
 230 /**
 231  * Visitor class for an XML document.
 232  *
 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.
 240  */
 241 class XMLVisitor
 242 {
 243 public:
 244
 245   /**
 246    * Virtual destructor.
 247    */
 248   virtual ~XMLVisitor () {}
 249
 250
 251   /**
 252    * Callback for the start of an XML document.
 253    *
 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,
 257    * open files, etc.
 258    *
 259    * @see #endXML
 260    */
 261   virtual void startXML () {}
 262
 263
 264   /**
 265    * Callback for the end of an XML document.
 266    *
 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
 273    * an error.
 274    *
 275    * @see #startXML
 276    * @see #error
 277    */
 278   virtual void endXML () {}
 279
 280
 281   /**
 282    * Callback for the start of an XML element.
 283    *
 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.
 294    *
 295    * @param name The name of the element that is starting (not null).
 296    * @param atts The element's attributes (not null).
 297    * @see #endElement
 298    */
 299   virtual void startElement (const char * name, const XMLAttributes &atts) {}
 300
 301
 302   /**
 303    * Callback for the end of an XML element.
 304    *
 305    * The XML parser will invoke this method at the end of every XML element.
 306    *
 307    * @param name The name of the element that is ending (not null).
 308    * @see #startElement
 309    */
 310   virtual void endElement (const char * name) {}
 311
 312
 313   /**
 314    * Callback for a chunk of character data.
 315    *
 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.
 322    *
 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
 325    * be zero).
 326    */
 327   virtual void data (const char * s, int length) {}
 328
 329
 330   /**
 331    * Callback for an XML processing instruction.
 332    *
 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.
 340    *
 341    * @param target The processing instruction target (not null).
 342    * @param data The processing instruction data (not null).
 343    */
 344   virtual void pi (const char * target, const char * data) {}
 345
 346
 347   /**
 348    * Callback for an XML parsing warning.
 349    *
 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.
 353    *
 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
 357    * the warning.
 358    */
 359   virtual void warning (const char * message, int line, int column) {}
 360 };
 361
 362
 363 /**
 364  * @relates XMLVisitor
 365  * Read an XML document.
 366  *
 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.
 373  *
 374  * @param input The byte input stream containing the XML document.
 375  * @param visitor An object that contains callbacks for XML parsing
 376  * events.
 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.
 380  * @see XMLVisitor
 381  */
 382 extern void readXML (istream &input, XMLVisitor &visitor,
 383                      const string &path="");
 384
 385
 386 /**
 387  * @relates XMLVisitor
 388  * Read an XML document.
 389  *
 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.
 396  *
 397  * @param path The file name of the XML resource.
 398  * @param visitor An object that contains callbacks for XML parsing
 399  * events.
 400  * @exception Throws sg_io_exception or sg_xml_exception if there
 401  * is a problem reading the file.
 402  * @see XMLVisitor
 403  */
 404 extern void readXML (const string &path, XMLVisitor &visitor);
 405
 406
 407 #endif // __EASYXML_HXX
 408