include/anna/xml/XPath.hpp

   1 // ANNA - Anna is Not Nothingness Anymore                                                         //
   2 //                                                                                                //
   3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
   4 //                                                                                                //
   5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
   6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
   7
   8
   9 #ifndef anna_xml_XPath_hpp
  10 #define anna_xml_XPath_hpp
  11
  12 #include <anna/core/RuntimeException.hpp>
  13 #include <anna/core/mt/Mutex.hpp>
  14 #include <anna/core/util/Recycler.hpp>
  15
  16 #include <anna/xml/Node.hpp>
  17 #include <anna/xml/Parser.hpp>
  18
  19 struct _xmlNode;
  20 struct _xmlNodeSet;
  21 struct  _xmlXPathContext;
  22
  23 namespace anna {
  24
  25 namespace xml {
  26
  27 /**
  28    XPath is a language to navigate an XML document.
  29
  30    \see https://www.w3schools.com/xml/xpath_intro.asp
  31    \see http://www.whoishostingthis.com/resources/xpath
  32 */
  33 class XPath : Parser {
  34 public:
  35   /**
  36    * Modo en que recupera la información de los nodos seleccionados por la expressión XPath.
  37    * \see XPath.
  38    */
  39   struct Mode {
  40     enum _v {
  41       Simple = 0x01, /**< Sólo devuelve el primer nivel de nodos que cumplen con la expressión XPath. */
  42       Full = 0x02,  /**< Devuelve el árbol dependiente de los nodos que cumplen con la expressión XPath */
  43       Namespace = 0x04 /**< Activa el uso de namespaces en el doc XML recibido.*/
  44     };
  45   };
  46
  47   /**
  48      Constructor.
  49      \param name Nombre lógico de esta instancia.
  50   */
  51   XPath(const char* name);
  52
  53   /**
  54      Aplica la expresión XPath sobre el documento recibido como parámetro. Los nodos
  55      del documento XML seleccionados por XPath se recogeran con los métodos
  56      #node_begin, #node_end y #node.
  57
  58      \param document Documento XML sobre el que aplicar la expresión.
  59      \param expression Expresión XPath a aplicar sobre el documento XML.
  60      \param mode Una combinación de XPath::Mode::_v.
  61      \warning La instancia del documento debe estar correctamente inicializada.
  62      \see Document::initialize
  63   */
  64   void apply(const Document& document, const char* expression, const int mode = Mode::Simple) noexcept(false);
  65
  66   /**
  67    * Aplica la expresión XPath sobre el documento recibido como parámetro y devuelve
  68    * \em true si hay algún nodo que cumpla la expresión o \em false en otro caso.
  69    * Es mucho más rápido que el método #apply, porque no dispondremos de los nodos que
  70    * cumplen la condición.
  71    *
  72    * \param document Documento XML al que aplicar la sentencia.
  73    * \param expression Expresión XPath a aplicar.
  74    * \param mode Modo de interpretación de los resultados. \em Si valor XPath::Mode::Namespace analizará el
  75    * documento XML para obtener los namespaces a usar.
  76    *
  77    * \return \em true si algún nodo del documento que cumpla la expressión o \em false en otro caso.
  78    */
  79   bool match(const Document& document, const char* expression, const int mode = Mode::Simple) noexcept(false);
  80
  81   /**
  82      Aplica la expresión XPath sobre el documento recibido como parámetro y devuelve el primer
  83      nodo que cumple con la expresión.
  84    *
  85    * \param document Documento XML al que aplicar la sentencia.
  86    * \param expression Expresión XPath a aplicar.
  87    * \param mode Modo de interpretación de los resultados. \em Si valor XPath::Mode::Namespace analizará el
  88    * documento XML para obtener los namespaces a usar.
  89    * \param emode Modo de actuar en caso de que no haya ningún nodo que cumpla la expresión.
  90    *
  91    * \warning Si no hay ningún nodo que cumpla la expresión devolverá una excepción.
  92    */
  93   const Node* find(const Document& document, const char* expression, const int mode = Mode::Full, const Exception::Mode::_v emode = Exception::Mode::Throw)
  94   noexcept(false);
  95
  96   /**
  97    * Devuelve \em true si existen nodos que cumplieron la condición de #apply o \em false en otro caso.
  98    * \return  \em true si existen nodos que cumplieron la condición de #apply o \em false en otro caso.
  99    */
 100   bool isEmpty() const { return a_root->a_children.size() == 0; }
 101
 102   /**
 103    * Devuelve el número de nodos que han sido seleccionados al invocar al método #apply.
 104    * \return El número de nodos que han sido seleccionados al invocar al método #apply.
 105    */
 106   int size() const { return a_root->a_children.size(); }
 107
 108   /**
 109    * Devuelve el primer nodo del documento que cumple la expresión indicada al invocar al método #apply.
 110    * \return El primer nodo del documento que cumple la expresión indicada al invocar al método #apply.
 111    */
 112   Node::const_child_iterator node_begin() const { return a_root->child_begin(); }
 113
 114   /**
 115    * Devuelve el final de la lista de nodos que cumplen la expresión indicada al invocar al método #apply.
 116    * \return El final de la lista de nodos que cumplen la expresión indicada al invocar al método #apply.
 117    */
 118   Node::const_child_iterator node_end() const { return a_root->child_end(); }
 119
 120   /**
 121    * Devuelve la instancia del nodo apuntado por el iterador recibido como parámetro.
 122    * \return la instancia del nodo apuntado por el iterador recibido como parámetro.
 123    */
 124   static const Node* node(Node::const_child_iterator& ii) { return xml::Node::node(ii); }
 125
 126 private:
 127   // Modo pasado al callback del apply
 128   int a_mode;
 129
 130   // Resultado retornado por el callback del match
 131   bool a_result;
 132
 133   typedef void(XPath::*Initialize)(_xmlXPathContext*, const Document&);
 134   typedef void (XPath::*Callback)(const _xmlNodeSet*);
 135
 136   struct ConfigSkeleton;
 137   friend struct ConfigSkeleton;
 138
 139   struct ConfigSkeleton {
 140     Initialize initialize;
 141     Callback callback;
 142
 143     ConfigSkeleton(Callback _callback) : initialize(NULL), callback(_callback) {;}
 144   };
 145
 146   XPath(const XPath&);
 147
 148   void text(Node* node, _xmlNode* xmlNode) noexcept(false);
 149
 150   void skeleton(const Document&, const char* expression, ConfigSkeleton&) noexcept(false);
 151
 152   void initializeNamespaces(_xmlXPathContext*, const Document&) noexcept(false);
 153   void forwardNamespaces(_xmlXPathContext*, _xmlNode*) noexcept(false);
 154   void callbackApply(const _xmlNodeSet*);
 155   void callbackMatch(const _xmlNodeSet*);
 156 };
 157
 158 }
 159 }
 160
 161 #endif