main.dox

/*! \mainpage
 \tableofcontents
 This library is intended to be used to create and load XML files to a C structure. \n
 It is a 2-part software described hereafter. \n
 The first part is a C++ library that is used to parse and retrieve values from XML file, and create
 XMl files from a list of specifications. This library is described in section \ref cpplib \n
 The second part is a python script that generates a C code to automatically create XML from a C structure, 
 fill the C structure from an XML file and compare an XML file with the C structure to find the common and
 and different items. The generated C interface is described in section \ref C_Interface
 The usage of the python script is described in \ref xmlpp
 
 For people only willing to use this library in their code without necessarily understand how it works and what are 
 the additional features provided by the C++ API, reading the sections \ref C_Interface and \ref xmlpp is probably 
 sufficient. 
 
 \section Requirements requirements
 This library requires the following dependencies to be installed:
  - libxml2 and libxlm2-devel
  - boost-devel
 
 \section cpplib C++ Library
 This C++ library is a XML parser based on libxml2. 
 As an example, the following structure will be used
 \include Example/ex_struct.h
 The corresponding complete XML file is 
 \include Example/ex_struct.xml
 The following XML is going to be used as an example of partial XML also containing non 
 existing fields
 \include Example/partial_ex_struct.xml
 
 Both XMLConfParser and XMLConfWriter modules relies on the XMLConfDocument class. The latter 
 provides the back-end for navigating the XML document and will not be described here.
 \subsection XMLConfParser XMLConfParser
 It provides a useful API to retrieve values from the XML files through the getValue() method 
 \code
 bool getValue(std::string path, int &ref);
 bool getValue(std::string path, unsigned int &ref);
 bool getValue(std::string path, float &ref);
 bool getValue(std::string path, double &ref);
 bool getValue(std::string path, char *ref);
 bool getValue(std::string path, std::string &ref);
 \endcode
 The path used in these methods is a string representation of the structure field. Using the 
 example struct (full code can be found in Example/main_parser.cc):
 \dontinclude Example/main_parser.cc
 \skipline parser;
 \until my_double
 
 
 It also provides methods to check the content of the XML file. 
 It can tell whether the tag for a specific field of the C structure is found in the XML:
 \skipline pathExists
 \until my_double is
 Which produces the following output:
 \verbinclude Example/DocGen/parser_path_exist.txt
 
 
 It can print a list of tags that are present in the XML but not corresponding to any of the paths provided
 with the addCheckElement() method.
 This can be used to check for tags present in the XML but not corresponding to any of the field present
 in the C structure:
 \skipline startCheckAdditional
 \until printAdditional
 This piece of code will output:
 \verbinclude Example/DocGen/parser_add.txt
 
 
 The last feature offered is the possibility to get the list of paths you are interested in 
 that are present in the XML. This list is created from the paths used on pathExists(). 
 In the example we called pathExists() for
 \copydoc list_pe
 
 And the xml provides new values for 
  - exampleStruct.name
  - exampleStruct.external_var
  - exampleStruct.my_substruct.my_double 
 
 The code hereafter shows the usage of this feature:
 \skipline string diff
 \until }
 And produces the following output:
 \verbinclude Example/DocGen/parser_diff.txt
 
 \subsection XMLConfWriter XMLConfWriter
 
  It provides a useful API to write values in the XML files through the addPath() method 
 \code
 bool addPath(std::string path, unsigned int ref);
 bool addPath(std::string path, int ref);
 bool addPath(std::string path, float ref);
 bool addPath(std::string path, double ref);
 bool addPath(std::string path, char* ref);
 bool addPath(std::string path, std::string ref);
 bool addPathAsHex(std::string path, int ref);
 \endcode
 The path used in these methods is a string representation of the structure field. Using the 
 example struct (full code can be found in Example/main_writer.cc):
 
 \dontinclude Example/main_writer.cc
 We must first create the in-memory XML document and initialise the structure:
 \skipline writer;
 \until createDocument
 Then the desired elements of the structure are added to the XML document.
 \skipline addPathAsHex
 \until my_double
 And finally the document is written on disk
 \skipline writeDocument
 
 The resulting XML file is 
 \verbinclude Example/example_writer.xml
 
 
 \section xmlpp xmlpp.py script
 This python script takes as input a header file describing C structures and generates the code for the 
 automatic structure filling and XML creation. If more than one structure is present in the header
 file, you must specify which one is the top one. Use it with:
 \code
 xmlpp.py {headerFile.h} --struct {topStructure}
 \endcode
 This will produce besides your {headerFile.h} two C++ files {headerFileProxy.h} and {headerFileProxy.cc} 
 that you should include in your compilation.
 
 
 \section C_Interface C Interface
 This C interface is probably the only part that most users will use. Starting from the example structure 
 given above, the xmlpp.py script will generate ex_structProxy.h and ex_structProxy.cc. These files provide 
 the following functions, callable from C code: 
 \dontinclude Example/ex_structProxy.h
 \skipline read_file
 \until getLast
 
 \dontinclude Example/ex_structProxy.h
  - \skipline read_file
  Use this function to read a new XML file.\n
  fileName is the full path to the XML file to read.
  - \line apply
  Use this function to apply the loaded XML file to your structure. \n
  ptr is a pointer to the structure you want to fill.
  - \line test
  Use this function to print the list of elements in the structure that are not present in the XML and 
  print the list of tags present in the XML that are not in the structure. 
  - \line start
  The next two functions work together and are used to get the list of fields that received a new value 
  from the XML.
  This one should be used first and returns a pointer to the first modified element. If no element has 
  been modified it return a NULL pointer.
  - \line next
  This function will return a pointer to the next modified element. After reaching the last element this
  function will return a NULL pointer.
  - \line create
  Use this function to create an XML file corresponding to the structure. The current values of the structure
  are set in the file.\n
  ptr is a pointer to the reference structure.
  fileName is the full path to the XML file to write.
  - \line getLast
  If one of the function returns with an error code (-1), use this function to retrieve the last fatal 
  error that occurred.\n
  The fatal error will warn you about malformed XML files, specifying what is the error and where it can
  be found.\n 
  An example of error occurring when an end tag has a typo:
  \verbatim
Fatal error: Document not parsed successfully.
File: partial.xml at (l:5, c:27): expected '>
\endverbatim
  Or for an opening tag without its closing tag:
  \verbatim
Fatal error: Document not parsed successfully.
File: partial.xml at (l:8, c:1): Premature end of data in tag my_struct line 2
 \endverbatim
  
  
  A fully working example using this interface can be found in Example/main_proxy.cc\n
  \dontinclude Example/main_proxy.cc
  Start by declaring the structure and reading the new XML file:
  \skipline test;
  \until getLast
  Then apply the content of the file to structure to initialise it:
  \line apply
  We can then do the operation again with a partial XML file
  \skipline read_file
  \until apply
  The structure now contains the following values:
  \verbinclude Example/DocGen/proxy_values.txt
  Then we print the list of differences between the structure and the file
  \skipline test
  giving the following output:
  \verbinclude Example/DocGen/proxy_diff.txt
  We can determine which fields of the structure have been modified in the XML. We request the
  pointer to the first modified element and we can compare the address of the pointer with the address of
  our structure fields to determine which one. We then loop on the next elements until the pointer becomes
  NULL, indicating the past-the-end element. 
  \skipline void
  \until }
  This outputs the following:
  \verbinclude Example/DocGen/proxy_mod.txt
  We can finally finish by modifying the structure and write the final XML:
  \skipline strcpy
  \until create
  Which is 
  \verbinclude Example/outputStruct.xml 
 */