libxml++/nodes/node.h

   1 /* node.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_NODES_NODE_H
   8 #define __LIBXMLPP_NODES_NODE_H
   9
  10 #include <libxml++/noncopyable.h>
  11 #include <libxml++/exceptions/exception.h>
  12 #include <glibmm/ustring.h>
  13 #include <list>
  14 #include <map>
  15 #include <vector>
  16
  17 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  18 extern "C" {
  19   struct _xmlNode;
  20 }
  21 #endif //DOXYGEN_SHOULD_SKIP_THIS
  22
  23 namespace xmlpp
  24 {
  25
  26 class Element;
  27
  28 // xmlpp::XPathResultType is similar to xmlXPathObjectType in libxml2.
  29 /** An XPath expression is evaluated to yield a result, which
  30  * has one of the following four basic types:
  31  *   - node-set
  32  *   - boolean
  33  *   - number
  34  *   - string
  35  */
  36 enum XPathResultType
  37 {
  38     XPATH_RESULT_UNDEFINED = 0,
  39     XPATH_RESULT_NODESET = 1,
  40     XPATH_RESULT_BOOLEAN = 2,
  41     XPATH_RESULT_NUMBER = 3,
  42     XPATH_RESULT_STRING = 4
  43 };
  44
  45 /** Represents XML Nodes.
  46  *
  47  * You should never new and delete Nodes. The Parser will create and
  48  * manage them for you. Furthermore, Document and Element have methods for
  49  * adding Nodes to a Document.
  50  */
  51 class Node : public NonCopyable
  52 {
  53 public:
  54   typedef std::list<Node*> NodeList;
  55   typedef std::list<const Node*> const_NodeList;
  56
  57   typedef std::vector<Node*> NodeSet;
  58   typedef std::vector<const Node*> const_NodeSet;
  59
  60   /** @throws xmlpp::internal_error If @a node is <tt>nullptr</tt>.
  61    */
  62   explicit Node(_xmlNode* node);
  63
  64   /** Destructor.
  65    * Does not destroy the underlying xmlNode. The xmlNode is owned by a xmlDoc
  66    * document. If you want to also destroy the xmlNode, use remove_node().
  67    */
  68   ~Node() override;
  69
  70   /** Get the name of this node.
  71    * @returns The node's name.
  72    */
  73   Glib::ustring get_name() const;
  74
  75   /** Set the name of this node.
  76    * @param name The new name for the node.
  77    */
  78   void set_name(const Glib::ustring& name);
  79
  80   /** Set the namespace prefix used by the node.
  81    * If no such namespace prefix has been declared then this method will throw an exception.
  82    * @param ns_prefix The namespace prefix.
  83    * @throws xmlpp::exception
  84    */
  85   void set_namespace(const Glib::ustring& ns_prefix);
  86
  87   /** Get the namespace prefix of this node.
  88    * @returns The node's namespace prefix. Can be an empty string.
  89    */
  90   Glib::ustring get_namespace_prefix() const;
  91
  92   /** Get the namespace URI of this node.
  93    * @returns The node's namespace URI. Can be an empty string.
  94    */
  95   Glib::ustring get_namespace_uri() const;
  96
  97   /** Discover at what line number this node occurs in the XML file.
  98    * @returns The line number.
  99    */
 100   int get_line() const;
 101
 102   /** Get the parent element for this node.
 103    * @returns The parent node, or <tt>nullptr</tt> if the node has no parent element.
 104    */
 105   const Element* get_parent() const;
 106
 107   /** Get the parent element for this node.
 108    * @returns The parent node, or <tt>nullptr</tt> if the node has no parent element.
 109    */
 110   Element* get_parent();
 111
 112   /** Get the next sibling for this node.
 113    * @returns The next sibling, or <tt>nullptr</tt> if the node has no next sibling.
 114    */
 115   const Node* get_next_sibling() const;
 116
 117   /** Get the next sibling for this node.
 118    * @returns The next sibling, or <tt>nullptr</tt> if the node has no next sibling.
 119    */
 120   Node* get_next_sibling();
 121
 122   /** Get the previous sibling for this node .
 123    * @returns The previous sibling, or <tt>nullptr</tt> if the node has no previous sibling.
 124    */
 125   const Node* get_previous_sibling() const;
 126
 127   /** Get the previous sibling for this node.
 128    * @returns The previous sibling, or <tt>nullptr</tt> if the node has no previous sibling.
 129    */
 130   Node* get_previous_sibling();
 131
 132   /** Get the first child of this node.
 133    * You may optionally get the first child node which has a certain name.
 134    * @param name The name of the requested child node, or an empty string.
 135    * @returns The first child, or <tt>nullptr</tt> if no child node (with the specified name) exists.
 136    *
 137    * @newin{2,36}
 138    */
 139   const Node* get_first_child(const Glib::ustring& name = Glib::ustring()) const;
 140
 141   /** Get the first child of this node.
 142    * You may optionally get the first child node which has a certain name.
 143    * @param name The name of the requested child node, or an empty string.
 144    * @returns The first child, or <tt>nullptr</tt> if no child node (with the specified name) exists.
 145    *
 146    * @newin{2,36}
 147    */
 148   Node* get_first_child(const Glib::ustring& name = Glib::ustring());
 149
 150   /** Obtain the list of child nodes. You may optionally obtain a list of only the child nodes which have a certain name.
 151    * @param name The names of the child nodes to get. If you do not specify a name, then the list will contain all nodes, regardless of their names.
 152    * @returns The list of child nodes.
 153    */
 154   NodeList get_children(const Glib::ustring& name = Glib::ustring());
 155
 156   /** Obtain the list of child nodes. You may optionally obtain a list of only the child nodes which have a certain name.
 157    * @param name The names of the child nodes to get. If you do not specify a name, then the list will contain all nodes, regardless of their names.
 158    * @returns The list of child nodes.
 159    */
 160   const_NodeList get_children(const Glib::ustring& name = Glib::ustring()) const;
 161
 162   /** Remove a node and its children.
 163    *
 164    * The node is disconnected from its parent. The underlying libxml xmlNode
 165    * instances are also removed.
 166    *
 167    * @newin{3,0} Replaces remove_child()
 168    *
 169    * @param node The node to remove. This Node and all its descendants will be
 170    *             deleted and therefore unusable after calling this method.
 171    */
 172   static void remove_node(Node* node);
 173
 174   /** Import node(s) from another document under this node, without affecting the source node.
 175    *
 176    * If the imported node is an attribute node, and this node has an attribute with
 177    * the same name as the imported attribute, the existing attribute is destroyed
 178    * before the imported attribute is added. Any pointer to a destroyed attribute
 179    * node becomes invalid.
 180    *
 181    * @param node The node to copy and insert under the current node.
 182    * @param recursive Whether to import the child nodes also. Defaults to true.
 183    * @returns Usually the newly created node, but adjacent text nodes are merged,
 184    *          and the old text node with merged contents is returned.
 185    * @throws xmlpp::exception
 186    */
 187   Node* import_node(const Node* node, bool recursive = true);
 188
 189
 190   /** Get the XPath of this node.
 191    * @result The XPath of the node.
 192    */
 193   Glib::ustring get_path() const;
 194
 195   /** Find nodes from an XPath expression.
 196    * @param xpath The XPath of the nodes.
 197    * @returns The resulting NodeSet.
 198    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 199    * @throws xmlpp::internal_error If the result type is not nodeset.
 200    */
 201   NodeSet find(const Glib::ustring& xpath);
 202
 203   /** Find nodes from an XPath expression.
 204    * @param xpath The XPath of the nodes.
 205    * @returns The resulting const_NodeSet.
 206    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 207    * @throws xmlpp::internal_error If the result type is not nodeset.
 208    */
 209   const_NodeSet find(const Glib::ustring& xpath) const;
 210
 211   /** A map of namespace prefixes to namespace URIs.
 212    */
 213   typedef std::map<Glib::ustring, Glib::ustring> PrefixNsMap;
 214
 215   /** Find nodes from an XPath expression.
 216    * @param xpath The XPath of the nodes.
 217    * @param namespaces A map of namespace prefixes to namespace URIs to be used while finding.
 218    * @returns The resulting NodeSet.
 219    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 220    * @throws xmlpp::internal_error If the result type is not nodeset.
 221    */
 222   NodeSet find(const Glib::ustring& xpath, const PrefixNsMap& namespaces);
 223
 224   /** Find nodes from an XPath expression.
 225    * @param xpath The XPath of the nodes.
 226    * @param namespaces A map of namespace prefixes to namespace URIs to be used while finding.
 227    * @returns The resulting const_NodeSet.
 228    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 229    * @throws xmlpp::internal_error If the result type is not nodeset.
 230    */
 231   const_NodeSet find(const Glib::ustring& xpath, const PrefixNsMap& namespaces) const;
 232
 233   /** Evaluate an XPath expression.
 234    * @param xpath The XPath expression.
 235    * @param[out] result_type Result type of the XPath expression before conversion
 236    *             to boolean. If <tt>nullptr</tt>, the result type is not returned.
 237    * @returns The value of the XPath expression. If the value is not of type boolean,
 238    *          it is converted to boolean.
 239    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 240    * @throws xmlpp::internal_error
 241    *
 242    * @newin{2,36}
 243    */
 244   bool eval_to_boolean(const Glib::ustring& xpath, XPathResultType* result_type = nullptr) const;
 245
 246
 247   /** Evaluate an XPath expression.
 248    * @param xpath The XPath expression.
 249    * @param namespaces A map of namespace prefixes to namespace URIs to be used while evaluating.
 250    * @param[out] result_type Result type of the XPath expression before conversion
 251    *             to boolean. If <tt>nullptr</tt>, the result type is not returned.
 252    * @returns The value of the XPath expression. If the value is not of type boolean,
 253    *          it is converted to boolean.
 254    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 255    * @throws xmlpp::internal_error
 256    *
 257    * @newin{2,36}
 258    */
 259   bool eval_to_boolean(const Glib::ustring& xpath, const PrefixNsMap& namespaces,
 260     XPathResultType* result_type = nullptr) const;
 261
 262   /** Evaluate an XPath expression.
 263    * @param xpath The XPath expression.
 264    * @param[out] result_type Result type of the XPath expression before conversion
 265    *             to number. If <tt>nullptr</tt>, the result type is not returned.
 266    * @returns The value of the XPath expression. If the value is not of type number,
 267    *          it is converted to number.
 268    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 269    * @throws xmlpp::internal_error
 270    *
 271    * @newin{2,36}
 272    */
 273   double eval_to_number(const Glib::ustring& xpath, XPathResultType* result_type = nullptr) const;
 274
 275   /** Evaluate an XPath expression.
 276    * @param xpath The XPath expression.
 277    * @param namespaces A map of namespace prefixes to namespace URIs to be used while evaluating.
 278    * @param[out] result_type Result type of the XPath expression before conversion
 279    *             to number. If <tt>nullptr</tt>, the result type is not returned.
 280    * @returns The value of the XPath expression. If the value is not of type number,
 281    *          it is converted to number.
 282    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 283    * @throws xmlpp::internal_error
 284    *
 285    * @newin{2,36}
 286    */
 287   double eval_to_number(const Glib::ustring& xpath, const PrefixNsMap& namespaces,
 288     XPathResultType* result_type = nullptr) const;
 289
 290   /** Evaluate an XPath expression.
 291    * @param xpath The XPath expression.
 292    * @param[out] result_type Result type of the XPath expression before conversion
 293    *             to string. If <tt>nullptr</tt>, the result type is not returned.
 294    * @returns The value of the XPath expression. If the value is not of type string,
 295    *          it is converted to string.
 296    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 297    * @throws xmlpp::internal_error
 298    *
 299    * @newin{2,36}
 300    */
 301   Glib::ustring eval_to_string(const Glib::ustring& xpath, XPathResultType* result_type = nullptr) const;
 302
 303   /** Evaluate an XPath expression.
 304    * @param xpath The XPath expression.
 305    * @param namespaces A map of namespace prefixes to namespace URIs to be used while evaluating.
 306    * @param[out] result_type Result type of the XPath expression before conversion
 307    *             to string. If <tt>nullptr</tt>, the result type is not returned.
 308    * @returns The value of the XPath expression. If the value is not of type string,
 309    *          it is converted to string.
 310    * @throws xmlpp::exception If the XPath expression cannot be evaluated.
 311    * @throws xmlpp::internal_error
 312    *
 313    * @newin{2,36}
 314    */
 315   Glib::ustring eval_to_string(const Glib::ustring& xpath, const PrefixNsMap& namespaces,
 316     XPathResultType* result_type = nullptr) const;
 317
 318   ///Access the underlying libxml implementation.
 319   _xmlNode* cobj();
 320
 321   ///Access the underlying libxml implementation.
 322   const _xmlNode* cobj() const;
 323
 324   /** Construct the correct C++ instance for a given libxml C struct instance.
 325    *
 326    * This is only for use by the libxml++ implementation.
 327    *
 328    * @param node A pointer to an xmlNode or a "derived" struct, such as xmlDoc, xmlAttr, etc.
 329    */
 330   static void create_wrapper(_xmlNode* node);
 331
 332   /** Delete the C++ instance for a given libxml C struct instance, and also
 333    * recursively destroy the C++ instances for any children.
 334    *
 335    * This is only for use by the libxml++ implementation.
 336    * @param node A pointer to an xmlNode or a "derived" struct, such as xmlDoc, xmlAttr, etc.
 337    */
 338   static void free_wrappers(_xmlNode* node);
 339
 340 private:
 341   _xmlNode* impl_;
 342 };
 343
 344 } // namespace xmlpp
 345
 346 #endif //__LIBXMLPP_NODES_NODE_H