libxml++/parsers/parser.h

   1 /* parser.h
   2  * libxml++ and this file are copyright (C) 2000 by Ari Johnson, and
   3  * are covered by the GNU Lesser General Public License, which should be
   4  * included with libxml++ as the file COPYING.
   5  */
   6
   7 #ifndef __LIBXMLPP_PARSER_H
   8 #define __LIBXMLPP_PARSER_H
   9
  10 #ifdef _MSC_VER //Ignore warnings about the Visual C++ Bug, where we can not do anything
  11 #pragma warning (disable : 4786)
  12 #endif
  13
  14 #include <libxml++/nodes/element.h>
  15 #include <libxml++/exceptions/validity_error.h>
  16 #include <libxml++/exceptions/internal_error.h>
  17
  18 #include <istream>
  19 #include <cstdarg> //For va_list.
  20
  21 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  22 extern "C" {
  23   struct _xmlParserCtxt;
  24 }
  25 #endif //DOXYGEN_SHOULD_SKIP_THIS
  26
  27 namespace xmlpp {
  28
  29 /** XML parser.
  30  *
  31  */
  32 class Parser : NonCopyable
  33 {
  34 public:
  35   Parser();
  36   virtual ~Parser();
  37
  38   typedef unsigned int size_type;
  39
  40   /** By default, the parser will not validate the XML file.
  41    * @param val Whether the document should be validated.
  42    */
  43   virtual void set_validate(bool val = true);
  44
  45   /** See set_validate().
  46    * @returns Whether the parser will validate the XML file.
  47    */
  48   virtual bool get_validate() const;
  49
  50   /** Set whether the parser will automatically substitute entity references with the text of the entities' definitions.
  51    * For instance, this affects the text returned by ContentNode::get_content().
  52    * By default, the parser will not substitute entities, so that you do not lose the entity reference information.
  53    * @param val Whether entities will be substitued.
  54    */
  55   virtual void set_substitute_entities(bool val = true);
  56
  57   /** See set_substitute_entities().
  58    * @returns Whether entities will be substituted during parsing.
  59    */
  60   virtual bool get_substitute_entities() const;
  61
  62   /** Set whether the parser will collect and throw error and warning messages.
  63    * If messages are collected, they are included in an exception thrown at the
  64    * end of parsing. If the messages are not collected, they are written on
  65    * stderr. The messages written on stderr are slightly different, and may
  66    * be preferred in a program started from the command-line.
  67    *
  68    * The default, if set_throw_messages() is not called, is to collect and throw
  69    * only messages from validation. Other messages are written to stderr.
  70    * This is for backward compatibility, and may change in the future.
  71    *
  72    * @newin{2,36}
  73    *
  74    * @param val Whether messages will be collected and thrown in an exception.
  75    */
  76   void set_throw_messages(bool val = true);
  77
  78   /** See set_throw_messages().
  79    *
  80    * @newin{2,36}
  81    *
  82    * @returns Whether messages will be collected and thrown in an exception.
  83    *          The default with only validation messages thrown is returned as false.
  84    */
  85   bool get_throw_messages() const;
  86
  87   /** Set whether default attribute values from the DTD shall be included in the node tree.
  88    * If set, attributes not assigned a value in the XML file, but with a default value
  89    * in the DTD file, will be included in the node tree that the parser creates.
  90    * These attributes will be represented by AttributeNode instances (not AttributeDeclaration
  91    * instances), just like attributes which are assigned a value in the XML file.
  92    *
  93    * @newin{2,38}
  94    *
  95    * @param val Whether attributes with default values will be included in the node tree.
  96    */
  97   void set_include_default_attributes(bool val = true);
  98
  99   /** See set_include_default_attributes().
 100    *
 101    * @newin{2,38}
 102    *
 103    * @returns Whether attributes with default values will be included in the node tree.
 104    */
 105   bool get_include_default_attributes();
 106
 107   /** Set and/or clear parser option flags.
 108    * See the libxml2 documentation, enum xmlParserOption, for a list of parser options.
 109    * This method overrides other methods that set parser options, such as set_validate(),
 110    * set_substitute_entities() and set_include_default_attributes(). Use set_parser_options()
 111    * only if no other method can set the parser options you want.
 112    *
 113    * @newin{2,38}
 114    *
 115    * @param set_options Set bits correspond to flags that shall be set during parsing.
 116    * @param clear_options Set bits correspond to flags that shall be cleared during parsing.
 117    *        Bits that are set in neither @a set_options nor @a clear_options are not affected.
 118    */
 119   void set_parser_options(int set_options = 0, int clear_options = 0);
 120
 121   /** See set_parser_options().
 122    *
 123    * @newin{2,38}
 124    *
 125    * @param [out] set_options Set bits correspond to flags that shall be set during parsing.
 126    * @param [out] clear_options Set bits correspond to flags that shall be cleared during parsing.
 127    *        Bits that are set in neither @a set_options nor @a clear_options are not affected.
 128    */
 129   void get_parser_options(int& set_options, int& clear_options);
 130
 131   /** Parse an XML document from a file.
 132    * @throw exception
 133    * @param filename The path to the file.
 134    */
 135   virtual void parse_file(const Glib::ustring& filename) = 0;
 136
 137   //TODO: In a future ABI-break, add a virtual void parse_memory_raw(const unsigned char* contents, size_type bytes_count);
 138
 139   /** Parse an XML document from a string.
 140    * @throw exception
 141    * @param contents The XML document as a string.
 142    */
 143   virtual void parse_memory(const Glib::ustring& contents) = 0;
 144
 145   /** Parse an XML document from a stream.
 146    * @throw exception
 147    * @param in The stream.
 148    */
 149   virtual void parse_stream(std::istream& in) = 0;
 150
 151   //TODO: Add stop_parser()/stop_parsing(), wrapping xmlStopParser()?
 152
 153 protected:
 154   virtual void initialize_context();
 155   virtual void release_underlying();
 156
 157   //TODO: In a future ABI-break, add these virtual functions.
 158   //virtual void on_parser_error(const Glib::ustring& message);
 159   //virtual void on_parser_warning(const Glib::ustring& message);
 160   virtual void on_validity_error(const Glib::ustring& message);
 161   virtual void on_validity_warning(const Glib::ustring& message);
 162
 163   virtual void handleException(const exception& e);
 164   virtual void check_for_exception();
 165   //TODO: In a future API/ABI-break, change the name of this function to
 166   // something more appropriate, such as check_for_error_and_warning_messages.
 167   virtual void check_for_validity_messages();
 168
 169   static void callback_parser_error(void* ctx, const char* msg, ...);
 170   static void callback_parser_warning(void* ctx, const char* msg, ...);
 171   static void callback_validity_error(void* ctx, const char* msg, ...);
 172   static void callback_validity_warning(void* ctx, const char* msg, ...);
 173
 174   enum MsgType
 175   {
 176     MsgParserError,
 177     MsgParserWarning,
 178     MsgValidityError,
 179     MsgValidityWarning
 180   };
 181
 182   static void callback_error_or_warning(MsgType msg_type, void* ctx,
 183                                         const char* msg, va_list var_args);
 184
 185   _xmlParserCtxt* context_;
 186   exception* exception_;
 187   //TODO: In a future ABI-break, add these members.
 188   //bool throw_messages_;
 189   //Glib::ustring parser_error_;
 190   //Glib::ustring parser_warning_;
 191   Glib::ustring validate_error_;
 192   Glib::ustring validate_warning_; //Built gradually - used in an exception at the end of parsing.
 193
 194   bool validate_;
 195   bool substitute_entities_;
 196   //TODO: In a future ABI-break, add these members.
 197   //bool include_default_attributes_;
 198   //int set_options_;
 199   //int clear_options_;
 200 };
 201
 202 /** Equivalent to Parser::parse_stream().
 203  *
 204  * @newin{2,38}
 205  */
 206 inline std::istream& operator>>(std::istream& in, Parser& parser)
 207 {
 208   parser.parse_stream(in);
 209   return in;
 210 }
 211
 212 } // namespace xmlpp
 213
 214 #endif //__LIBXMLPP_PARSER_H
 215