1 // ANNA - Anna is Not Nothingness Anymore //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo //
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 //
9 #ifndef anna_xml_XPath_hpp
10 #define anna_xml_XPath_hpp
12 #include <anna/core/RuntimeException.hpp>
13 #include <anna/core/mt/Mutex.hpp>
14 #include <anna/core/util/Recycler.hpp>
16 #include <anna/xml/Node.hpp>
17 #include <anna/xml/Parser.hpp>
21 struct _xmlXPathContext;
28 XPath es un lenguaje para encontrar información dentro de un documento XML.
30 \see http://www.w3schools.com/xpath/default.asp
32 class XPath : Parser {
35 * Modo en que recupera la información de los nodos seleccionados por la expressión XPath.
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.*/
48 \param name Nombre lógico de esta instancia.
50 XPath(const char* name);
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.
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
63 void apply(const Document& document, const char* expression, const int mode = Mode::Simple) throw(RuntimeException);
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.
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.
76 * \return \em true si algún nodo del documento que cumpla la expressión o \em false en otro caso.
78 bool match(const Document& document, const char* expression, const int mode = Mode::Simple) throw(RuntimeException);
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.
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.
90 * \warning Si no hay ningún nodo que cumpla la expresión devolverá una excepción.
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);
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.
99 bool isEmpty() const throw() { return a_root->a_children.size() == 0; }
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.
105 int size() const throw() { return a_root->a_children.size(); }
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.
111 Node::const_child_iterator node_begin() const throw() { return a_root->child_begin(); }
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.
117 Node::const_child_iterator node_end() const throw() { return a_root->child_end(); }
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.
123 static const Node* node(Node::const_child_iterator& ii) throw() { return xml::Node::node(ii); }
126 // Modo pasado al callback del apply
129 // Resultado retornado por el callback del match
132 typedef void(XPath::*Initialize)(_xmlXPathContext*, const Document&);
133 typedef void (XPath::*Callback)(const _xmlNodeSet*);
135 struct ConfigSkeleton;
136 friend struct ConfigSkeleton;
138 struct ConfigSkeleton {
139 Initialize initialize;
142 ConfigSkeleton(Callback _callback) : initialize(NULL), callback(_callback) {;}
147 void text(Node* node, _xmlNode* xmlNode) throw(RuntimeException);
149 void skeleton(const Document&, const char* expression, ConfigSkeleton&) throw(RuntimeException);
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*);