include/anna/xml/Parser.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_Parser_hpp
  10 #define anna_xml_Parser_hpp
  11
  12 #include <anna/core/RuntimeException.hpp>
  13 #include <anna/core/mt/Mutex.hpp>
  14
  15 struct _xmlValidCtxt;
  16 struct _xmlDoc;
  17 struct _xmlNode;
  18 struct _xmlAttr;
  19
  20 namespace anna {
  21
  22 class DataBlock;
  23
  24 namespace xml {
  25
  26 class Node;
  27 class DTD;
  28 class Document;
  29 class Attribute;
  30
  31 /**
  32    Analizador de documentos XML.
  33
  34    Analiza la expresion contenida en un documento XML, opcionalmente puede validar la estructura
  35    mediante una DTD suministrada a tal efecto, y devuelve un arbol de nodos que resulta muy
  36    facil de usar.
  37
  38    Ejemplo de documento XML:
  39
  40    \code
  41
  42    <xvc HeartBeat="20000">
  43       <broadcast>
  44          <INetAddress Address="204.152.65.15" Port="2000"/>
  45          <INetAddress Address="204.152.65.47" Port="2002"/>
  46       </broadcast>
  47
  48       <ethernet Mode="raw" VirtualAddress="1.1.1.100">
  49          <Input Device="/dev/qfe" PhysicalAccessPoint="2" MAC="8:0:20:9e:ee:21"/>
  50          <Output Device="/dev/qfe" PhysicalAccessPoint="2" MAC="8:0:20:9e:ee:c9"/>
  51       </ethernet>
  52    </xvc>
  53
  54    \endcode
  55
  56    Donde los nodos (Ver \ref Node) \em broadcast y \em ethernet son hijos del nodo \em xvc. De la misma forma
  57    los nodos \em Input y \em Output son hijos de \em ethernet.
  58
  59    Cada nodo XML puede tener una serie indeterminada de atributos (Ver \ref Attribute) que completan su
  60    significado. Por ejemplo \em Device, \em PhysicalAccessPoint y \em MAC son atributos de los nodos \em Input y
  61    \em Output.
  62 */
  63 class Parser : public Mutex {
  64 public:
  65   /**
  66      Constructor.
  67   */
  68   Parser();
  69
  70   /**
  71      Destructor.
  72   */
  73   virtual ~Parser();
  74
  75   /**
  76      Devuelve el nodo raiz de la expresion XML analizada. Puede ser NULL.
  77
  78      \return El nodo raiz de la expresion XML analizada. Puede ser NULL.
  79      \warning
  80         \li El resultado de este metodo solo sera valido despues de invocar a alguno
  81      de los metodo #apply.
  82         \li El nodo devuelto  no puede ser usado despues del invocar a destructor de este Parser.
  83   */
  84   const Node* getRoot() const { return a_root; }
  85
  86   /**
  87      Analiza el documento XML recibido como parametro.
  88      \param document Documento XML que deseamos analizar.
  89      \return El nodo raiz del arbol XML correspondiente al documento analizado.
  90      \warning
  91         \li La instancia del documento debe estar correctamente inicializada.
  92         \li El nodo devuelto  no puede ser usado despues del invocar a destructor de este Parser.
  93      \see Document::initialize
  94   */
  95   const Node* apply(const Document& document) noexcept(false);
  96
  97   /**
  98      Analiza el archivo XML recibido como parametro, y verifica que cumpla las reglas
  99      establecidas por la DTD.
 100      \param document Documento XML que deseamos analizar.
 101      \param dtd DTD que debe cumplir el documento XML.
 102      \return El nodo raiz del arbol XML correspondiente al resultado del analisis.
 103
 104      \warning
 105         \li La instancia de la DTD y el documento deben estar correctamente inicializadas.
 106         \li El nodo devuelto  no puede ser usado despues del invocar a destructor de este Parser.
 107
 108      \see DTD::initialize
 109      \see Document::initialize
 110   */
 111   const Node* apply(const Document& document, const DTD& dtd) noexcept(false);
 112
 113 protected:
 114   /*
 115    * Nodo ráiz del árbol representado por el documento XML analizado.
 116    */
 117   Node* a_root;
 118
 119   /**
 120      Inicializa el contenido del nodo asociado al ultimo Parser::apply.
 121      \warning Se invoca automaticamente desde el numero de ANNA.xml
 122   */
 123   virtual void reset() ;
 124
 125   /**
 126    * Comprueba si se requieren operaciones de traducción del conjunto de caracteres.
 127    */
 128   void setupEncoding(_xmlDoc* document) ;
 129
 130   /**
 131    * Si fuera necesario traduce el texto contenido por el parámetro recibido al conjunto
 132    * de caracteres indicado por el documento XML que estamos tratando.
 133    * \param source Texto expresado en el conjunto de caracteres particular.
 134    * \return Una cadena expresada en UTF-8.
 135    */
 136   const char* decode(const unsigned char* source) ;
 137
 138   /**
 139    * \warning Exclusivamente uso interno.
 140    */
 141   void attributes(Node* node, _xmlAttr* attribute) noexcept(false);
 142
 143   /**
 144    * \warning Exclusivamente uso interno.
 145    */
 146   void children(Node* node, _xmlNode* xmlNode) noexcept(false);
 147
 148 private:
 149   _xmlValidCtxt* a_context;
 150   static char st_text [1024];
 151   static anna::RuntimeException* st_exception;
 152   bool a_encoding;
 153   DataBlock* a_buffEncode;
 154
 155   Parser(const Parser&);
 156
 157   void apply(_xmlDoc* document) noexcept(false);
 158
 159   static void errorHandler(void *ctx,  const char *msg, ...) ;
 160   static void warningHandler(void *ctx,  const char *msg, ...) ;
 161 };
 162
 163 }
 164 }
 165
 166 #endif