libxml++/parsers/textreader.h

   1 /* textreader.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_XMLREADER_H
   8 #define __LIBXMLPP_XMLREADER_H
   9
  10 #include <libxml++/noncopyable.h>
  11 #include <libxml++/nodes/node.h>
  12
  13 #include <glibmm/ustring.h>
  14
  15 #include <memory>
  16
  17 extern "C"
  18 {
  19   struct _xmlTextReader;
  20 }
  21
  22 namespace xmlpp
  23 {
  24
  25 /** A TextReader-style XML parser.
  26  * A reader that provides fast, non-cached, forward-only access to XML data,
  27  * in the style of .Net's <a href="http://msdn.microsoft.com/en-us/library/system.xml.xmltextreader.aspx">XmlTextReader</a> class.
  28  */
  29 class TextReader: public NonCopyable
  30 {
  31   public:
  32     enum xmlNodeType {
  33       Attribute = 2,
  34       CDATA = 4,
  35       Comment = 8,
  36       Document = 9,
  37       DocumentFragment = 11,
  38       DocumentType = 10,
  39       Element = 1,
  40       EndElement = 15,
  41       EndEntity = 16,
  42       Entity = 6,
  43       EntityReference = 5,
  44       None = 0,
  45       Notation = 12,
  46       ProcessingInstruction = 7,
  47       SignificantWhitespace = 14,
  48       Text = 3,
  49       Whitespace = 13,
  50       XmlDeclaration = 17
  51     };
  52
  53     enum xmlReadState
  54     {
  55       Closed = 4,
  56       EndOfFile = 3,
  57       Error = 2,
  58       Initial = 0,
  59       Interactive = 1,
  60       Reading = 5
  61     };
  62
  63     enum ParserProperties
  64     {
  65       LoadDtd = 1,
  66       DefaultAttrs = 2,
  67       Validate = 3,
  68       SubstEntities = 4
  69     };
  70
  71   typedef unsigned int size_type;
  72
  73   public:
  74     /**
  75      * Wraps a TextReader object from an underlying libxml object. The TextReader
  76      * takes ownership of cobj.
  77      * @param cobj The underlying libxml xmlTextReader object.
  78      */
  79     TextReader(struct _xmlTextReader* cobj);
  80
  81     /**
  82      * Creates a new TextReader object to parse a file or URI.
  83      * @param URI The URI to read.
  84      * @throws xmlpp::internal_error If an xmlTextReader object cannot be created.
  85      */
  86     TextReader(const Glib::ustring& URI);
  87
  88     /**
  89      * Creates a new TextReader object which parses in memory data.
  90      * @param data The data to parse.
  91      * @param size The number of bytes in data.
  92      * @param uri The base URI to use for the document.
  93      * @throws xmlpp::internal_error If an xmlTextReader object cannot be created.
  94      */
  95     TextReader(const unsigned char* data, size_type size, const Glib::ustring& uri = Glib::ustring());
  96
  97     ~TextReader() override;
  98
  99     /** Moves the position of the current instance to the next node in the stream, exposing its properties.
 100      * @return true if the node was read successfully, false if there are no more nodes to read.
 101      * @throws xmlpp::parse_error
 102      * @throws xmlpp::validity_error
 103      */
 104     bool read();
 105
 106     /** Reads the contents of the current node, including child nodes and markup.
 107      * @return A Glib::ustring containing the XML content, or an empty Glib::ustring if the current node is neither an element nor attribute, or has no child nodes.
 108      * @throws xmlpp::parse_error
 109      * @throws xmlpp::validity_error
 110      */
 111     Glib::ustring read_inner_xml();
 112
 113     /** Reads the current node and its contents, including child nodes and markup.
 114      * @return A Glib::ustring containing the XML content, or an empty Glib::ustring if the current node is neither an element nor attribute.
 115      * @throws xmlpp::parse_error
 116      * @throws xmlpp::validity_error
 117      */
 118     Glib::ustring read_outer_xml();
 119
 120     /** Reads the contents of an element or a text node as a string.
 121      * @return A Glib::ustring containing the contents of the Element or Text node, or an empty Glib::ustring if the reader is positioned on any other type of node.
 122      * @throws xmlpp::parse_error
 123      * @throws xmlpp::validity_error
 124      */
 125     Glib::ustring read_string();
 126
 127     /** Parses an attribute value into one or more Text and EntityReference nodes.
 128      * @return A bool where true indicates the attribute value was parsed, and false indicates the reader was not positioned on an attribute node or all the attribute values have been read.
 129      * @throws xmlpp::parse_error
 130      * @throws xmlpp::validity_error
 131      */
 132     bool read_attribute_value();
 133
 134     /** Gets the number of attributes on the current node.
 135      * @return The number of attributes on the current node, or zero if the current node
 136      *         does not support attributes, or -1 in case of error.
 137      * @throws xmlpp::parse_error
 138      * @throws xmlpp::validity_error
 139      */
 140     int get_attribute_count() const;
 141
 142     /** Gets the base Uniform Resource Identifier (URI) of the current node.
 143      * @return The base URI of the current node or an empty Glib::ustring if not available.
 144      */
 145     Glib::ustring get_base_uri() const;
 146
 147     /** Gets the depth of the current node in the XML document.
 148      * @return The depth of the current node in the XML document, or -1 in case of error.
 149      */
 150     int get_depth() const;
 151
 152     /** Gets a value indicating whether the current node has any attributes.
 153      * @return true if the current has attributes, false otherwise.
 154      */
 155     bool has_attributes() const;
 156
 157     /** Whether the node can have a text value.
 158      * @return true if the current node can have an associated text value, false otherwise.
 159      */
 160     bool has_value() const;
 161
 162     /** Whether an Attribute node was generated from the default value defined in the DTD or schema.
 163      * @return true if defaulted, false otherwise.
 164      */
 165     bool is_default() const;
 166
 167     /** Check if the current node is empty
 168      * @return true if empty, false otherwise.
 169      */
 170     bool is_empty_element() const;
 171
 172     Glib::ustring get_local_name() const;
 173     Glib::ustring get_name() const;
 174     Glib::ustring get_namespace_uri() const;
 175
 176     /** Get the node type of the current node.
 177      * @returns The xmlpp::xmlNodeType of the current node, or -1 in case of error.
 178      */
 179     xmlNodeType get_node_type() const;
 180
 181     /** Get the namespace prefix associated with the current node.
 182      * @returns The namespace prefix, or an empty string if not available.
 183      */
 184     Glib::ustring get_prefix() const;
 185
 186     /** Get the quotation mark character used to enclose the value of an attribute.
 187      * @returns Returns " or ' and -1 in case of error.
 188      */
 189     char get_quote_char() const;
 190
 191     Glib::ustring get_value() const;
 192     Glib::ustring get_xml_lang() const;
 193
 194     xmlReadState get_read_state() const;
 195
 196     void close();
 197
 198     Glib::ustring get_attribute(int number) const;
 199     Glib::ustring get_attribute(const Glib::ustring& name) const;
 200     Glib::ustring get_attribute(const Glib::ustring& local_name, const Glib::ustring& ns_uri) const;
 201
 202     // TODO InputBuffer GetRemainder;
 203
 204     Glib::ustring lookup_namespace(const Glib::ustring& prefix) const;
 205
 206     bool move_to_attribute(int number);
 207     bool move_to_attribute(const Glib::ustring& name);
 208     bool move_to_attribute(const Glib::ustring& local_name, const Glib::ustring& ns_uri);
 209     bool move_to_first_attribute();
 210     bool move_to_next_attribute();
 211     bool move_to_element();
 212
 213     bool get_normalization() const;
 214     void set_normalization(bool value);
 215
 216     bool get_parser_property(ParserProperties property) const;
 217     void set_parser_property(ParserProperties property, bool value);
 218
 219     /** Get a pointer to the current node.
 220      * @warning This is dangerous because the underlying node may be destroyed on the next read.
 221      * The C++ wrapper is not deleted. Using this method causes memory leaks,
 222      * unless you call xmlpp::Node::free_wrappers(), which is not intended to be
 223      * called by the application.
 224      * @returns A pointer to the current node, or <tt>nullptr</tt> in case of error.
 225      */
 226     Node* get_current_node();
 227
 228     /** Get a pointer to the current node.
 229      * @warning See the non-const get_current_node().
 230      * @returns A pointer to the current node, or <tt>nullptr</tt> in case of error.
 231      */
 232     const Node* get_current_node() const;
 233
 234 //    Document* CurrentDocument();
 235
 236     /** Expand the current node.
 237      * Reads the contents of the current node and the full subtree. It then makes
 238      * the subtree available until the next call to read() or next().
 239      * @warning The C++ wrappers are not deleted. Using this method causes memory leaks,
 240      * unless you call xmlpp::Node::free_wrappers(), which is not intended to be
 241      * called by the application.
 242      * @returns A pointer to the current node, or <tt>nullptr</tt> in case of error.
 243      * @throws xmlpp::parse_error
 244      * @throws xmlpp::validity_error
 245      */
 246     Node* expand();
 247
 248     bool next();
 249     bool is_valid() const;
 250
 251   private:
 252     class PropertyReader;
 253     friend class PropertyReader;
 254
 255     void setup_exceptions();
 256     static void on_libxml_error(void * arg, const char *msg, int severity,
 257                               void * locator);
 258     void check_for_exceptions() const;
 259
 260     std::unique_ptr<PropertyReader> propertyreader;
 261     _xmlTextReader* impl_;
 262     int severity_;
 263     Glib::ustring error_;
 264 };
 265
 266 }
 267
 268 #endif