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 es un lenguaje para encontrar información dentro de un documento XML.
  29
  30    \see http://www.w3schools.com/xpath/default.asp
  31 */
  32 class XPath : Parser {
  33 public:
  34   /**
  35    * Modo en que recupera la información de los nodos seleccionados por la expressión XPath.
  36    * \see XPath.
  37    */
  38   struct Mode {
  39     enum _v {
  40       Simple = 0x01, /**< Sólo devuelve el primer nivel de nodos que cumplen con la expressión XPath. */
  41       Full = 0x02,  /**< Devuelve el árbol dependiente de los nodos que cumplen con la expressión XPath */
  42       Namespace = 0x04 /**< Activa el uso de namespaces en el doc XML recibido.*/
  43     };
  44   };
  45
  46   /**
  47      Constructor.
  48      \param name Nombre lógico de esta instancia.
  49   */
  50   XPath(const char* name);
  51
  52   /**
  53      Aplica la expresión XPath sobre el documento recibido como parámetro. Los nodos
  54      del documento XML seleccionados por XPath se recogeran con los métodos
  55      #node_begin, #node_end y #node.
  56
  57      \param document Documento XML sobre el que aplicar la expresión.
  58      \param expression Expresión XPath a aplicar sobre el documento XML.
  59      \param mode Una combinación de XPath::Mode::_v.
  60      \warning La instancia del documento debe estar correctamente inicializada.
  61      \see Document::initialize
  62   */
  63   void apply(const Document& document, const char* expression, const int mode = Mode::Simple) throw(RuntimeException);
  64
  65   /**
  66    * Aplica la expresión XPath sobre el documento recibido como parámetro y devuelve
  67    * \em true si hay algún nodo que cumpla la expresión o \em false en otro caso.
  68    * Es mucho más rápido que el método #apply, porque no dispondremos de los nodos que
  69    * cumplen la condición.
  70    *
  71    * \param document Documento XML al que aplicar la sentencia.
  72    * \param expression Expresión XPath a aplicar.
  73    * \param mode Modo de interpretación de los resultados. \em Si valor XPath::Mode::Namespace analizará el
  74    * documento XML para obtener los namespaces a usar.
  75    *
  76    * \return \em true si algún nodo del documento que cumpla la expressión o \em false en otro caso.
  77    */
  78   bool match(const Document& document, const char* expression, const int mode = Mode::Simple) throw(RuntimeException);
  79
  80   /**
  81      Aplica la expresión XPath sobre el documento recibido como parámetro y devuelve el primer
  82      nodo que cumple con la expresión.
  83    *
  84    * \param document Documento XML al que aplicar la sentencia.
  85    * \param expression Expresión XPath a aplicar.
  86    * \param mode Modo de interpretación de los resultados. \em Si valor XPath::Mode::Namespace analizará el
  87    * documento XML para obtener los namespaces a usar.
  88    * \param emode Modo de actuar en caso de que no haya ningún nodo que cumpla la expresión.
  89    *
  90    * \warning Si no hay ningún nodo que cumpla la expresión devolverá una excepción.
  91    */
  92   const Node* find(const Document& document, const char* expression, const int mode = Mode::Full, const Exception::Mode::_v emode = Exception::Mode::Throw)
  93   throw(RuntimeException);
  94
  95   /**
  96    * Devuelve \em true si existen nodos que cumplieron la condición de #apply o \em false en otro caso.
  97    * \return  \em true si existen nodos que cumplieron la condición de #apply o \em false en otro caso.
  98    */
  99   bool isEmpty() const throw() { return a_root->a_children.size() == 0; }
 100
 101   /**
 102    * Devuelve el número de nodos que han sido seleccionados al invocar al método #apply.
 103    * \return El número de nodos que han sido seleccionados al invocar al método #apply.
 104    */
 105   int size() const throw() { return a_root->a_children.size(); }
 106
 107   /**
 108    * Devuelve el primer nodo del documento que cumple la expresión indicada al invocar al método #apply.
 109    * \return El primer nodo del documento que cumple la expresión indicada al invocar al método #apply.
 110    */
 111   Node::const_child_iterator node_begin() const throw() { return a_root->child_begin(); }
 112
 113   /**
 114    * Devuelve el final de la lista de nodos que cumplen la expresión indicada al invocar al método #apply.
 115    * \return El final de la lista de nodos que cumplen la expresión indicada al invocar al método #apply.
 116    */
 117   Node::const_child_iterator node_end() const throw() { return a_root->child_end(); }
 118
 119   /**
 120    * Devuelve la instancia del nodo apuntado por el iterador recibido como parámetro.
 121    * \return la instancia del nodo apuntado por el iterador recibido como parámetro.
 122    */
 123   static const Node* node(Node::const_child_iterator& ii) throw() { return xml::Node::node(ii); }
 124
 125 private:
 126   // Modo pasado al callback del apply
 127   int a_mode;
 128
 129   // Resultado retornado por el callback del match
 130   bool a_result;
 131
 132   typedef void(XPath::*Initialize)(_xmlXPathContext*, const Document&);
 133   typedef void (XPath::*Callback)(const _xmlNodeSet*);
 134
 135   struct ConfigSkeleton;
 136   friend struct ConfigSkeleton;
 137
 138   struct ConfigSkeleton {
 139     Initialize initialize;
 140     Callback callback;
 141
 142     ConfigSkeleton(Callback _callback) : initialize(NULL), callback(_callback) {;}
 143   };
 144
 145   XPath(const XPath&);
 146
 147   void text(Node* node, _xmlNode* xmlNode) throw(RuntimeException);
 148
 149   void skeleton(const Document&, const char* expression, ConfigSkeleton&) throw(RuntimeException);
 150
 151   void initializeNamespaces(_xmlXPathContext*, const Document&) throw(RuntimeException);
 152   void forwardNamespaces(_xmlXPathContext*, _xmlNode*) throw(RuntimeException);
 153   void callbackApply(const _xmlNodeSet*);
 154   void callbackMatch(const _xmlNodeSet*);
 155 };
 156
 157 }
 158 }
 159
 160 #endif