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 is a language to navigate an XML document.
30 \see https://www.w3schools.com/xml/xpath_intro.asp
31 \see http://www.whoishostingthis.com/resources/xpath
33 class XPath : Parser {
36 * Modo en que recupera la información de los nodos seleccionados por la expressión XPath.
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.*/
49 \param name Nombre lógico de esta instancia.
51 XPath(const char* name);
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.
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
64 void apply(const Document& document, const char* expression, const int mode = Mode::Simple) noexcept(false);
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.
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.
77 * \return \em true si algún nodo del documento que cumpla la expressión o \em false en otro caso.
79 bool match(const Document& document, const char* expression, const int mode = Mode::Simple) noexcept(false);
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.
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.
91 * \warning Si no hay ningún nodo que cumpla la expresión devolverá una excepción.
93 const Node* find(const Document& document, const char* expression, const int mode = Mode::Full, const Exception::Mode::_v emode = Exception::Mode::Throw)
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.
100 bool isEmpty() const { return a_root->a_children.size() == 0; }
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.
106 int size() const { return a_root->a_children.size(); }
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.
112 Node::const_child_iterator node_begin() const { return a_root->child_begin(); }
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.
118 Node::const_child_iterator node_end() const { return a_root->child_end(); }
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.
124 static const Node* node(Node::const_child_iterator& ii) { return xml::Node::node(ii); }
127 // Modo pasado al callback del apply
130 // Resultado retornado por el callback del match
133 typedef void(XPath::*Initialize)(_xmlXPathContext*, const Document&);
134 typedef void (XPath::*Callback)(const _xmlNodeSet*);
136 struct ConfigSkeleton;
137 friend struct ConfigSkeleton;
139 struct ConfigSkeleton {
140 Initialize initialize;
143 ConfigSkeleton(Callback _callback) : initialize(NULL), callback(_callback) {;}
148 void text(Node* node, _xmlNode* xmlNode) noexcept(false);
150 void skeleton(const Document&, const char* expression, ConfigSkeleton&) noexcept(false);
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*);