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 <string>
  19 #include <istream>
  20 #include <cstdarg> // va_list
  21 #include <memory> // std::unique_ptr
  22
  23 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  24 extern "C" {
  25   struct _xmlParserCtxt;
  26 }
  27 #endif //DOXYGEN_SHOULD_SKIP_THIS
  28
  29 namespace xmlpp {
  30
  31 /** XML parser.
  32  *
  33  * Abstract base class for DOM parser and SAX parser.
  34  */
  35 class Parser : public NonCopyable
  36 {
  37 public:
  38   Parser();
  39   ~Parser() override;
  40
  41   typedef unsigned int size_type;
  42
  43   /** By default, the parser will not validate the XML file.
  44    * @param val Whether the document should be validated.
  45    */
  46   void set_validate(bool val = true);
  47
  48   /** See set_validate().
  49    * @returns Whether the parser will validate the XML file.
  50    */
  51   bool get_validate() const;
  52
  53   /** Set whether the parser will automatically substitute entity references with the text of the entities' definitions.
  54    * For instance, this affects the text returned by ContentNode::get_content().
  55    * By default, the parser will not substitute entities, so that you do not lose the entity reference information.
  56    * @param val Whether entities will be substitued.
  57    */
  58   void set_substitute_entities(bool val = true);
  59
  60   /** See set_substitute_entities().
  61    * @returns Whether entities will be substituted during parsing.
  62    */
  63   bool get_substitute_entities() const;
  64
  65   /** Set whether the parser will collect and throw error and warning messages.
  66    *
  67    * If messages are collected, they are included in an exception thrown at the
  68    * end of parsing.
  69    *
  70    * - DOM parser
  71    *
  72    *   If the messages are not collected, they are written on stderr.
  73    *   The messages written on stderr are slightly different, and may be
  74    *   preferred in a program started from the command-line. The default, if
  75    *   set_throw_messages() is not called, is to collect and throw messages.
  76    *
  77    * - SAX parser
  78    *
  79    *   If the messages are not collected, the error handling on_*() methods in
  80    *   the user's SAX parser subclass are called. This is the default, if
  81    *   set_throw_messages() is not called.
  82    *
  83    * @newin{2,36}
  84    *
  85    * @param val Whether messages will be collected and thrown in an exception.
  86    */
  87   void set_throw_messages(bool val = true);
  88
  89   /** See set_throw_messages().
  90    *
  91    * @newin{2,36}
  92    *
  93    * @returns Whether messages will be collected and thrown in an exception.
  94    */
  95   bool get_throw_messages() const;
  96
  97   /** Set whether default attribute values from the DTD shall be included in the node tree.
  98    * If set, attributes not assigned a value in the XML file, but with a default value
  99    * in the DTD file, will be included in the node tree that the parser creates.
 100    * These attributes will be represented by AttributeNode instances (not AttributeDeclaration
 101    * instances), just like attributes which are assigned a value in the XML file.
 102    *
 103    * @newin{2,38}
 104    *
 105    * @param val Whether attributes with default values will be included in the node tree.
 106    */
 107   void set_include_default_attributes(bool val = true);
 108
 109   /** See set_include_default_attributes().
 110    *
 111    * @newin{2,38}
 112    *
 113    * @returns Whether attributes with default values will be included in the node tree.
 114    */
 115   bool get_include_default_attributes();
 116
 117   /** Set and/or clear parser option flags.
 118    * See the libxml2 documentation, enum xmlParserOption, for a list of parser options.
 119    * This method overrides other methods that set parser options, such as set_validate(),
 120    * set_substitute_entities() and set_include_default_attributes(). Use set_parser_options()
 121    * only if no other method can set the parser options you want.
 122    *
 123    * @newin{2,38}
 124    *
 125    * @param set_options Set bits correspond to flags that shall be set during parsing.
 126    * @param 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 set_parser_options(int set_options = 0, int clear_options = 0);
 130
 131   /** See set_parser_options().
 132    *
 133    * @newin{2,38}
 134    *
 135    * @param [out] set_options Set bits correspond to flags that shall be set during parsing.
 136    * @param [out] clear_options Set bits correspond to flags that shall be cleared during parsing.
 137    *        Bits that are set in neither @a set_options nor @a clear_options are not affected.
 138    */
 139   void get_parser_options(int& set_options, int& clear_options);
 140
 141   /** Parse an XML document from a file.
 142    * @throw exception
 143    * @param filename The path to the file.
 144    */
 145   virtual void parse_file(const std::string& filename) = 0;
 146
 147   /** Parse an XML document from raw memory.
 148    * @throw exception
 149    * @param contents The XML document as an array of bytes.
 150    * @param bytes_count The number of bytes in the @a contents array.
 151    */
 152   virtual void parse_memory_raw(const unsigned char* contents, size_type bytes_count) = 0;
 153
 154   /** Parse an XML document from a string.
 155    * @throw exception
 156    * @param contents The XML document as a string.
 157    */
 158   virtual void parse_memory(const Glib::ustring& contents) = 0;
 159
 160   /** Parse an XML document from a stream.
 161    * @throw exception
 162    * @param in The stream.
 163    */
 164   virtual void parse_stream(std::istream& in) = 0;
 165
 166   //TODO: Add stop_parser()/stop_parsing(), wrapping xmlStopParser()?
 167
 168 protected:
 169   virtual void initialize_context();
 170   virtual void release_underlying();
 171
 172   virtual void on_parser_error(const Glib::ustring& message);
 173   virtual void on_parser_warning(const Glib::ustring& message);
 174   virtual void on_validity_error(const Glib::ustring& message);
 175   virtual void on_validity_warning(const Glib::ustring& message);
 176
 177   /// To be called in an exception handler.
 178   virtual void handle_exception();
 179   virtual void check_for_exception();
 180
 181   virtual void check_for_error_and_warning_messages();
 182
 183   static void callback_parser_error(void* ctx, const char* msg, ...);
 184   static void callback_parser_warning(void* ctx, const char* msg, ...);
 185   static void callback_validity_error(void* ctx, const char* msg, ...);
 186   static void callback_validity_warning(void* ctx, const char* msg, ...);
 187
 188   enum MsgType
 189   {
 190     MsgParserError,
 191     MsgParserWarning,
 192     MsgValidityError,
 193     MsgValidityWarning
 194   };
 195
 196   static void callback_error_or_warning(MsgType msg_type, void* ctx,
 197                                         const char* msg, va_list var_args);
 198
 199   _xmlParserCtxt* context_;
 200   std::unique_ptr<exception> exception_;
 201
 202 private:
 203   struct Impl;
 204   std::unique_ptr<Impl> pimpl_;
 205 };
 206
 207 /** Equivalent to Parser::parse_stream().
 208  *
 209  * @newin{2,38}
 210  */
 211 inline std::istream& operator>>(std::istream& in, Parser& parser)
 212 {
 213   parser.parse_stream(in);
 214   return in;
 215 }
 216
 217 } // namespace xmlpp
 218
 219 #endif //__LIBXMLPP_PARSER_H
 220