Changeset 2:62280b9c901d in rrlib_xml


Ignore:
Timestamp:
07.07.2010 09:39:28 (9 years ago)
Author:
Tobias Föhst <foehst@…>
Branch:
default
Phase:
public
Convert:
svn:3219ad6e-c0b7-4ac2-9554-e22e195eef7a/trunk@3
Message:

Documentation

Files:
5 edited

Legend:

Unmodified
Added
Removed
  • tXML2WrapperException.h

    r1 r2  
    2626 * \date    2010-06-26 
    2727 * 
    28  * \brief 
     28 * \brief   Contains tXML2WrapperException 
    2929 * 
    30  * \b 
     30 * \b tXML2WrapperException 
    3131 * 
    32  * A few words for tXML2WrapperException.h 
     32 * Runtime errors that come along with invalid XML input are handled 
     33 * by throwing an instance of tXML2WrapperException, which is the only 
     34 * proper way to cope with construction errors. 
     35 * tXML2WrapperException is derived from std::runtime_error and thus 
     36 * can be caught either especially for this library or in a general 
     37 * runtime_error block. 
    3338 * 
    3439 */ 
     
    4045// External includes with <> 
    4146//---------------------------------------------------------------------- 
    42 #include <exception> 
    43 #include <string> 
     47#include <stdexcept> 
    4448 
    4549//---------------------------------------------------------------------- 
     
    6670// Class declaration 
    6771//---------------------------------------------------------------------- 
    68 //! Short description of tXML2WrapperException 
    69 /*! A more detailed description of tXML2WrapperException, which 
    70  *  Tobias Foehst hasn't done yet! 
     72//! Exceptions thrown in RRLib XML2 Wrapper are of this type. 
     73/*! This exception class is a std::runtime_error and used when invalid 
     74 *  XML input is encountered that can not be handled automatically. 
     75 *  Thus, catching exceptions of this type distinguishes from other runtime 
     76 *  errors. 
    7177 * 
    7278 */ 
    73 class tXML2WrapperException : public std::exception 
     79class tXML2WrapperException : public std::runtime_error 
    7480{ 
    75   std::string message; 
    7681 
    7782//---------------------------------------------------------------------- 
     
    8085public: 
    8186 
     87  /*! The ctor of tXML2WrapperException 
     88   * 
     89   * This ctor forwards instantiation of an exception object to 
     90   * std::runtime_error with the given message as error description. 
     91   * 
     92   * \param message   A message that describes the error 
     93   */ 
    8294  tXML2WrapperException(const std::string &message) 
    83       : message(message) 
     95      : std::runtime_error(message) 
    8496  {} 
    8597 
    86   virtual ~tXML2WrapperException() throw() 
    87   {} 
    88  
    89   virtual const char *what() const throw() 
    90   { 
    91     return this->message.c_str(); 
    92   } 
    9398}; 
    9499 
  • tXMLDocument.cpp

    r1 r2  
    7171//---------------------------------------------------------------------- 
    7272tXMLDocument::tXMLDocument(const std::string &file_name, bool validate) 
    73     : document(xmlReadFile(file_name.c_str(), 0, validate ? XML_PARSE_DTDVALID : 0)) 
     73    : document(xmlReadFile(file_name.c_str(), 0, validate ? XML_PARSE_DTDVALID : 0)), 
     74    root_node(0) 
    7475{ 
    7576  assert(this->document); 
     
    8586tXMLDocument::~tXMLDocument() 
    8687{ 
     88  delete this->root_node; 
    8789  xmlFreeDoc(this->document); 
    8890} 
     91 
     92//---------------------------------------------------------------------- 
     93// class tXMLDocument GetRootNode 
     94//---------------------------------------------------------------------- 
     95const tXMLNode &tXMLDocument::GetRootNode() const 
     96{ 
     97  if (!this->root_node) 
     98  { 
     99    this->root_node = new tXMLNode(xmlDocGetRootElement(this->document)); 
     100  } 
     101  return *this->root_node; 
     102} 
  • tXMLDocument.h

    r1 r2  
    2626 * \date    2010-06-24 
    2727 * 
    28  * \brief 
     28 * \brief Contains tXMLDocument 
    2929 * 
    30  * \b 
     30 * \b tXMLDocument 
    3131 * 
    32  * A few words for tXMLDocument.h 
     32 * If an XML document is loaded for full access to its content, a DOM 
     33 * tree is generated consisting of nodes of with attributes. This class 
     34 * implements parsing and validating an XML file as well as accessing 
     35 * the DOM tree through instances of tXMLNode, featuring lazy evaluation. 
     36 * That means wrapping instances are not created before they are used. 
    3337 * 
    3438 */ 
     
    7074// Class declaration 
    7175//---------------------------------------------------------------------- 
    72 //! Short description of tXMLDocument 
    73 /*! A more detailed description of tXMLDocument, which 
    74  *  Tobias Foehst hasn't done yet! 
     76//! This class wraps creation and accessing the DOM tree of an XML document 
     77/*! If an XML document is loaded for full access to its content, a DOM 
     78 *  tree is generated consisting of nodes with attributes. This class 
     79 *  implements parsing and validating an XML file as well as accessing 
     80 *  the DOM tree through instances of tXMLNode, featuring lazy evaluation. 
     81 *  That means wrapping instances are not created before they are used. 
    7582 * 
    7683 */ 
     
    7885{ 
    7986  xmlDocPtr document; 
     87  mutable tXMLNode *root_node; 
    8088 
    8189//---------------------------------------------------------------------- 
     
    8492public: 
    8593 
     94  /*! The ctor of tXMLDocument 
     95   * 
     96   * This ctor reads and parses a file with given name into a XML DOM 
     97   * representation. 
     98   * If needed, the XML document is also validated using an included 
     99   * DTD specification. 
     100   * 
     101   * \param file_name   The name of the file to load 
     102   * \param validate    Whether the validation should be processed or not 
     103   * 
     104   * \exception tXML2WrapperException is thrown if the file was not found or could not be parsed 
     105   */ 
    86106  tXMLDocument(const std::string &file_name, bool validate = true); 
    87107 
     
    90110  ~tXMLDocument(); 
    91111 
    92   inline const tXMLNode GetRootElement() const 
    93   { 
    94     return tXMLNode(xmlDocGetRootElement(this->document)); 
    95   } 
     112  /*! Get the root node of the DOM tree stored for this document 
     113   * 
     114   * The XML document is stored as DOM tree in memory. This method 
     115   * provides node-wise access to this tree starting at its root. 
     116   * 
     117   * \returns A reference to the root node 
     118   */ 
     119  const tXMLNode &GetRootNode() const; 
    96120 
    97121}; 
  • tXMLNode.cpp

    r1 r2  
    8686tXMLNode::~tXMLNode() 
    8787{ 
    88   delete(this->name); 
     88  delete this->name; 
    8989} 
    9090 
     
    107107  return *this->children; 
    108108} 
     109 
     110//---------------------------------------------------------------------- 
     111// class tXMLNode GetName 
     112//---------------------------------------------------------------------- 
     113const std::string &tXMLNode::GetName() const 
     114{ 
     115  if (!this->name) 
     116  { 
     117    this->name = new std::string(reinterpret_cast<const char *>(this->node->name)); 
     118  } 
     119  return *this->name; 
     120} 
  • tXMLNode.h

    r1 r2  
    2626 * \date    2010-06-24 
    2727 * 
    28  * \brief 
    29  * 
    30  * \b 
    31  * 
    32  * A few words for tXMLNode.h 
     28 * \brief Contains tXMLNode 
     29 * 
     30 * \b tXMLNode 
     31 * 
     32 * If an XML document is loaded for full access to its content, a DOM 
     33 * tree is generated consisting of nodes with attributes. This class 
     34 * implements the interface between libxml2 data storage and C++ types, 
     35 * featuring lazy evaluation. That means instances are not created before 
     36 * they are used. 
    3337 * 
    3438 */ 
     
    7579// Class declaration 
    7680//---------------------------------------------------------------------- 
    77 //! Short description of tXMLNode 
    78 /*! A more detailed description of tXMLNode, which 
    79  *  Tobias Foehst hasn't done yet! 
     81//! This class wraps accessing the nodes of the DOM tree of an XML document 
     82/*! If an XML document is loaded for full access to its content, a DOM 
     83 *  tree is generated consisting of nodes with attributes. This class 
     84 *  implements the interface between libxml2 data storage and C++ types, 
     85 *  featuring lazy evaluation. That means instances are not created before 
     86 *  they are used. 
    8087 * 
    8188 */ 
    8289class tXMLNode 
    8390{ 
     91  friend class tXMLDocument; 
     92 
    8493  xmlNodePtr node; 
    8594  mutable std::string *name; 
     
    98107    return result; 
    99108  } 
     109 
    100110  template <typename TNumber> 
    101111  static const TNumber ConvertStringToNumber(const std::string &value, TNumber(&convert_function)(const char *, char **)) 
     
    111121  } 
    112122 
     123  /*! The ctor of tXMLNode 
     124   * 
     125   * This ctor is declared private and thus can only be called from other instances 
     126   * of tXMLNode or friends like tXMLDocument. 
     127   * 
     128   * \param node   The libxml2 node that is wrapped by the new object 
     129   * 
     130   * \exception tXML2WrapperException is thrown if the given libxml2 element is not a node 
     131   */ 
     132  tXMLNode(xmlNodePtr node); 
     133 
    113134//---------------------------------------------------------------------- 
    114135// Public methods 
     
    116137public: 
    117138 
    118   tXMLNode(xmlNodePtr node); 
     139  /*! The dtor of tXMLNode 
     140   */ 
    119141  ~tXMLNode(); 
    120142 
    121   inline const std::string &GetName() const 
    122   { 
    123     if (!this->name) 
    124     { 
    125       this->name = new std::string(reinterpret_cast<const char *>(this->node->name)); 
    126     } 
    127     return *this->name; 
    128   } 
    129  
     143  /*! Get the name of that node 
     144   * 
     145   * Each XML element has an unique name within its document type. This 
     146   * method provides access to the name of this node. 
     147   * 
     148   * \returns A reference to the node's name 
     149   */ 
     150  const std::string &GetName() const; 
     151 
     152  /*! Get the children of this node 
     153   * 
     154   * Within the DOM tree, each node can have a list of children. Access 
     155   * to this list is provided by this method. The internal vector the 
     156   * method returns a reference to is not created before the first call 
     157   * to this method (lazy evaluation) 
     158   * 
     159   * \returns A reference to the node's vector containing its children 
     160   */ 
    130161  const std::vector<tXMLNode> &GetChildren() const; 
    131162 
     163  /*! Get whether this node has the given attribute or not 
     164   * 
     165   * Each XML node can have several attributes. Calling this method 
     166   * before accessing an attribute using its name gives information 
     167   * about its availability and thus can be used to avoid runtime 
     168   * errors in form of instances of tXML2WrapperException. 
     169   * 
     170   * \returns Whether this node has the given attribute or not 
     171   */ 
    132172  inline const bool HasAttribute(const std::string &name) const 
    133173  { 
     
    135175  } 
    136176 
     177  /*! Get an XML attribute as std::string 
     178   * 
     179   * If the XML node wrapped by this instance has an attribute with 
     180   * the given name, its value is returned by this method as string. 
     181   * 
     182   * \exception tXML2WrapperException is thrown if the requested attribute is not available 
     183   * 
     184   * \param name   The name of the attribute 
     185   * 
     186   * \returns The attribute as std::string 
     187   */ 
    137188  inline const std::string GetStringAttribute(const std::string &name) const 
    138189  { 
     
    145196  } 
    146197 
     198  /*! Get an XML attribute as long int 
     199   * 
     200   * If the XML node wrapped by this instance has an attribute with 
     201   * the given name, its value is returned by this method as long int. 
     202   * 
     203   * \exception tXML2WrapperException is thrown if the requested attribute's value is available or not a number 
     204   * 
     205   * \param name   The name of the attribute 
     206   * \param base   The base that should be used for number interpretation 
     207   * 
     208   * \returns The attribute as long int 
     209   */ 
    147210  inline const long int GetLongIntAttribute(const std::string &name, int base = 10) const 
    148211  { 
     
    150213  } 
    151214 
     215  /*! Get an XML attribute as long long int 
     216   * 
     217   * If the XML node wrapped by this instance has an attribute with 
     218   * the given name, its value is returned by this method as long long 
     219   * int. 
     220   * 
     221   * \exception tXML2WrapperException is thrown if the requested attribute's value is available or not a number 
     222   * 
     223   * \param name   The name of the attribute 
     224   * \param base   The base that should be used for number interpretation 
     225   * 
     226   * \returns The attribute as long long int 
     227   */ 
    152228  inline const long long int GetLongLongIntAttribute(const std::string &name, int base = 10) const 
    153229  { 
     
    155231  } 
    156232 
     233  /*! Get an XML attribute as float 
     234   * 
     235   * If the XML node wrapped by this instance has an attribute with 
     236   * the given name, its value is returned by this method as float. 
     237   * 
     238   * \exception tXML2WrapperException is thrown if the requested attribute's value is available or not a number 
     239   * 
     240   * \param name   The name of the attribute 
     241   * 
     242   * \returns The attribute as float 
     243   */ 
    157244  inline const float GetFloatAttribute(const std::string &name) const 
    158245  { 
     
    160247  } 
    161248 
     249  /*! Get an XML attribute as double 
     250   * 
     251   * If the XML node wrapped by this instance has an attribute with 
     252   * the given name, its value is returned by this method as double. 
     253   * 
     254   * \exception tXML2WrapperException is thrown if the requested attribute's value is available or not a number 
     255   * 
     256   * \param name   The name of the attribute 
     257   * 
     258   * \returns The attribute as double 
     259   */ 
    162260  inline const double GetDoubleAttribute(const std::string &name) const 
    163261  { 
     
    165263  } 
    166264 
     265  /*! Get an XML attribute as long double 
     266   * 
     267   * If the XML node wrapped by this instance has an attribute with 
     268   * the given name, its value is returned by this method as long double. 
     269   * 
     270   * \exception tXML2WrapperException is thrown if the requested attribute's value is available or not a number 
     271   * 
     272   * \param name   The name of the attribute 
     273   * 
     274   * \returns The attribute as long double 
     275   */ 
    167276  inline const long double GetLongDoubleAttribute(const std::string &name) const 
    168277  { 
     
    170279  } 
    171280 
     281  /*! Get an XML attribute as enum 
     282   * 
     283   * If the XML node wrapped by this instance has an attribute with 
     284   * the given name, its value is interpreted as name of an element 
     285   * in an enumeration. Therefore, a vector with the enum's names must 
     286   * be provided. The method then returns the index of the name that 
     287   * was found in the attribute. 
     288   * 
     289   * \exception tXML2WrapperException is thrown if the requested attribute's value is available or not a member of given vector 
     290   * 
     291   * \param name         The name of the attribute 
     292   * \param enum_names   The names of the enumeration elements 
     293   * 
     294   * \returns The index of the matching element name 
     295   */ 
    172296  template <typename TEnum> 
    173297  inline const TEnum GetEnumAttribute(const std::string &name, const std::vector<std::string> &enum_names) const 
     
    182306  } 
    183307 
     308  /*! Get an XML attribute as bool 
     309   * 
     310   * If the XML node wrapped by this instance has an attribute with 
     311   * the given name, its value is returned by this method interpreted 
     312   * as bool. 
     313   * 
     314   * \exception tXML2WrapperException is thrown if the requested attribute's value is available or not true/false 
     315   * 
     316   * \param name         The name of the attribute 
     317   * 
     318   * \returns Whether the attribute's value was "true" or "false" 
     319   */ 
    184320  inline const bool GetBoolAttribute(const std::string &name) const 
    185321  { 
Note: See TracChangeset for help on using the changeset viewer.