#include <vpXmlParser.h>

Public Member Functions
Public Member Functions Inherited from vpXmlParser
	vpXmlParser ()
	vpXmlParser (const vpXmlParser &_twin)
virtual	~vpXmlParser ()
void	parse (const std::string &filename)
void	save (const std::string &filename, bool append=false)
void	setMap (const std::map< std::string, int > &_map)
void	setMainTag (const std::string &tag)

Static Public Member Functions
Static Public Member Functions Inherited from vpXmlParser
static void	cleanup ()

Protected Member Functions Inherited from vpXmlParser
std::map< std::string, int >	nodeMap
std::string	main_tag
virtual void	readMainClass (xmlDocPtr doc, xmlNodePtr node)=0
virtual void	writeMainClass (xmlNodePtr node)=0
bool	xmlReadBoolChild (xmlDocPtr doc, xmlNodePtr node)
char *	xmlReadCharChild (xmlDocPtr doc, xmlNodePtr node)
double	xmlReadDoubleChild (xmlDocPtr doc, xmlNodePtr node)
float	xmlReadFloatChild (xmlDocPtr doc, xmlNodePtr node)
int	xmlReadIntChild (xmlDocPtr doc, xmlNodePtr node)
std::string	xmlReadStringChild (xmlDocPtr doc, xmlNodePtr node)
unsigned int	xmlReadUnsignedIntChild (xmlDocPtr doc, xmlNodePtr node)
void	xmlWriteBoolChild (xmlNodePtr node, const char *label, bool value)
void	xmlWriteCharChild (xmlNodePtr node, const char label, const char value)
void	xmlWriteDoubleChild (xmlNodePtr node, const char *label, double value)
void	xmlWriteFloatChild (xmlNodePtr node, const char *label, float value)
void	xmlWriteIntChild (xmlNodePtr node, const char *label, int value)
void	xmlWriteStringChild (xmlNodePtr node, const char *label, const std::string &value)
void	xmlWriteUnsignedIntChild (xmlNodePtr node, const char *label, unsigned int value)

Detailed Description

This class intends to simplify the creation of xml parser based on the libxml2 third party library.

This class can be useful to manage external data parameters (for example for configuration of an experiment, ...).

Warning: This class is only available if libxml2 is installed and detected by ViSP. Installation instructions are provided here https://visp.inria.fr/3rd_xml2.

Note: After ViSP 3.2.0 release we introduce pugixml built-in 3rd party library that replaces favorably libxml2. For example vpXmlParserCamera uses now pugixml instead of inheriting from vpXmlParser.

In order to use this class, you have to create a new class inheriting from this one. In the child class, you have to implement the methods:

writeMainClass()
readMainClass()

These two methods depends on the data to parse, and must not be directly called (they are called from the parse() and the save() methods).

Following is an example of implementation for the document:

<config>
    <range>5</range>
    <step>7</step>
    <size_filter>3</size_filter>
</config>

A class to parse this document is declared as follows:

#include <libxml/parser.h>
 
class vpDataParser: public vpXmlParser
{
private:
  int m_range;
  int m_step;
  int m_size_filter
public:
  typedef enum{
    config,
    range,
    step,
    size_filter
  } dataToParse
 
  vpDataParser(){
    nodeMap["config"] = config;
    nodeMap["range"] = range;
    nodeMap["step"] = step;
    nodeMap["size_filter"] = size_filter;
  }
 
  virtual void writeMainClass(xmlNodePtr node);
  virtual void readMainClass(xmlDocPtr doc, xmlNodePtr node);
 
  // additional methods specific to the data to parse such as: accessors
}

The readMainClass function implementation is:

void
vpDataParser::readMainClass(xmlDocPtr doc, xmlNodePtr node)
{
  for (xmlNodePtr tmpNode = node->xmlChildrenNode; tmpNode != nullptr; tmpNode = tmpNode->next) {
    if(tmpNode->type == XML_ELEMENT_NODE) {
 
      std::map<std::string, int>::iterator iter = this->nodeMap.find((char*)tmpNode->name);
      if(iter == nodeMap.end()) {
        continue;
      }
 
      switch (iter->second){
      case range:
        this->m_range = xmlReadIntChild(doc, tmpNode);
        break;
      case step:
        this->m_step = xmlReadIntChild(doc, tmpNode);
        break;
      case size_filter:
        this->m_size_filter = xmlReadIntChild(doc, tmpNode);
        break;
      default:
        std::cout << "problem in the readMainClass (" << iter->second
                  << " , " << iter->first << " )" << std::endl; break;
      }
    }
  }
}

Data can now be accessed through the internal variables of the class vpDataParser.

To store the data in a xml file, the function save has to be called. This function needs the implementation of the writeMainClass function.

For example,

void
vpDataParser::writeMainClass(xmlNodePtr node)
{
  xmlWriteIntChild(node, "range", m_range);
  xmlWriteIntChild(node, "step", m_step);
  xmlWriteIntChild(node, "size_filter", m_size_filter);
}

Examples: testXmlParser.cpp.

Definition at line 184 of file vpXmlParser.h.

Constructor & Destructor Documentation

◆ vpXmlParser() [1/2]

BEGIN_VISP_NAMESPACE vpXmlParser::vpXmlParser ( )

Basic constructor.

Initialise the main tag with default value.

Definition at line 55 of file vpXmlParser.cpp.

References main_tag, and nodeMap.

Referenced by vpXmlParser().

◆ vpXmlParser() [2/2]

vpXmlParser::vpXmlParser ( const vpXmlParser & _twin )

Cpoy constructor.

Parameters

_twin : The parser to copy.

Definition at line 82 of file vpXmlParser.cpp.

References main_tag, nodeMap, and vpXmlParser().

◆ ~vpXmlParser()

vpXmlParser::~vpXmlParser ( )

virtual

Basic destructor that does nothing.

Warning: As stated in http://xmlsoft.org/html/libxml-parser.html#xmlCleanupParser to clean up memory allocated by the xml2 library itself, the user should call xmlCleanupParser() only when the process has finished using the xml2 library. In case of doubt abstain from calling this function or do it just before calling exit() to avoid leak reports from valgrind ! That's why in ViSP the destructor doesn't call xmlCleanupParser(). Rather we provide the static function vpXmlParser::cleanup() that calls xmlCleanupParser() that could be called just before exit().

See also: cleanup()

Definition at line 72 of file vpXmlParser.cpp.

Member Function Documentation

◆ cleanup()

void vpXmlParser::cleanup ( )

static

As stated in http://xmlsoft.org/html/libxml-parser.html#xmlCleanupParser to clean up memory allocated by the xml2 library itself, the user should call xmlCleanupParser() only when the process has finished using the xml2 library. In case of doubt abstain from calling this function or do it just before calling exit() to avoid leak reports from valgrind ! That's why in ViSP the destructor doesn't call xmlCleanupParser(). Rather we provide the static function vpXmlParser::cleanup() that calls xmlCleanupParser() that could be called just before exit().

Examples: testXmlParser.cpp.

Definition at line 485 of file vpXmlParser.cpp.

◆ parse()

void vpXmlParser::parse ( const std::string & filename )

parse the document. The data in the file are stored in the attributes of the child class. This method calls the readMainClass method which has to be implemented for every child class depending on the content to parse.

Parameters

filename : name of the file to parse

Definition at line 418 of file vpXmlParser.cpp.

References vpException::ioError, readMainClass(), and vpERROR_TRACE.

Referenced by check-tests.JavaParser::parse().

◆ readMainClass()

virtual void vpXmlParser::readMainClass	(	xmlDocPtr	doc,
		xmlNodePtr	node )

protectedpure virtual

pure virtual method used to read the document.

As the content of the function depends on the structure of the file to read, data name, data types and data values, it has to be reimplemented for every type of filename.

Parameters

doc	: a pointer representing the document
node	: the root node of the document

Examples: testXmlParser.cpp.

Referenced by parse().

◆ save()

void vpXmlParser::save	(	const std::string &	filename,
		bool	append = false )

Save the content of the class in the file given in parameters. The data of the class are in the child class. This method calls the write_main_class method which has to be implemented for every class depending on the data to save.

Parameters

filename	: the name of the file used to record the data
append	: if true and if the file exists, the data will be added to the data already in the file

Definition at line 450 of file vpXmlParser.cpp.

References vpException::ioError, main_tag, vpERROR_TRACE, and writeMainClass().

Referenced by gen_java.JavaWrapperGenerator::finalize(), and gen_java.JavaWrapperGenerator::gen().

◆ setMainTag()

void vpXmlParser::setMainTag ( const std::string & tag )

inline

set the name of the main tag

The main tag corresponds to the name of the root node

Parameters

tag	: name of the root node of the document

Definition at line 302 of file vpXmlParser.h.

References main_tag.

◆ setMap()

void vpXmlParser::setMap ( const std::map< std::string, int > & _map )

inline

Set the map describing the data to parse. This map stores the name of each node and an associated key used to simplify the parsing of the file.

If the following file want to be parsed:

<config>
  <range>5</range>
  <step>7</step>
  <size_filter>3</size_filter>
</config>

The following map has to be declared:

std::map dataToParse;
dataToParse["config"] = 0;
dataToParse["range"] = 1;
dataToParse["step"] = 2;
dataToParse["size_filter"] = 3;

Or, you can use keyword instead of number as key but it implies to declare in the child class an enumeration type of the name. For example:

typedef enum{
  config,
  range,
  step,
  size_filter} data_enum;
 
std::map dataToParse;
dataToParse["config"] = config;
dataToParse["range"] = range;
dataToParse["step"] = step;
dataToParse["size_filter"] = size_filter;

Parameters

_map	: the map describing the data to parse

Definition at line 293 of file vpXmlParser.h.

References nodeMap.

◆ writeMainClass()

virtual void vpXmlParser::writeMainClass ( xmlNodePtr node )

protectedpure virtual

pure virtual method used to write the document.

As the content of the function depends on the structure of the file to read, data name and data types, it has to be reimplemented for every type of file to parse.

Parameters

node	: the root node of the document

Examples: testXmlParser.cpp.

References xmlReadBoolChild(), xmlReadCharChild(), xmlReadDoubleChild(), xmlReadFloatChild(), xmlReadIntChild(), xmlReadStringChild(), xmlReadUnsignedIntChild(), xmlWriteBoolChild(), xmlWriteCharChild(), xmlWriteDoubleChild(), xmlWriteFloatChild(), xmlWriteIntChild(), xmlWriteStringChild(), and xmlWriteUnsignedIntChild().

Referenced by save().

◆ xmlReadBoolChild()

bool vpXmlParser::xmlReadBoolChild	(	xmlDocPtr	doc,
		xmlNodePtr	node )

protected

read a boolean

Warning: throw a vpException::ioError if the value cannot be parsed to a bool

Parameters

doc	: The main xml document
node	: a pointer to the node to read value

Returns: the bool value in the node

Definition at line 279 of file vpXmlParser.cpp.

References vpException::fatalError.

Referenced by writeMainClass().

◆ xmlReadCharChild()

char * vpXmlParser::xmlReadCharChild	(	xmlDocPtr	doc,
		xmlNodePtr	node )

protected

Read an array of character.

Warning: The array of characters is allocated and must be explicitly freed to avoid memory leak.

Parameters

doc	: The main xml document
node	: a pointer to the node to read value

Returns: pointer to an allocated array of character.

Definition at line 97 of file vpXmlParser.cpp.

References vpException::fatalError.

Referenced by writeMainClass().

◆ xmlReadDoubleChild()

double vpXmlParser::xmlReadDoubleChild	(	xmlDocPtr	doc,
		xmlNodePtr	node )

protected

read a double

Warning: throw a vpException::ioError if the value cannot be parsed to a double

Parameters

doc	: The main xml document
node	: a pointer to the node to read value

Returns: the double value in the node

Definition at line 209 of file vpXmlParser.cpp.

References vpException::fatalError, and vpException::ioError.

Referenced by writeMainClass().

◆ xmlReadFloatChild()

float vpXmlParser::xmlReadFloatChild	(	xmlDocPtr	doc,
		xmlNodePtr	node )

protected

read a float

Warning: throw a vpException::ioError if the value cannot be parsed to a float

Parameters

doc	: The main xml document
node	: a pointer to the node to read value

Returns: the float value in the node

Definition at line 242 of file vpXmlParser.cpp.

References vpException::fatalError, and vpException::ioError.

Referenced by writeMainClass().

◆ xmlReadIntChild()

int vpXmlParser::xmlReadIntChild	(	xmlDocPtr	doc,
		xmlNodePtr	node )

protected

read an int

Warning: throw a vpException::ioError if the value cannot be parsed to an integer

Parameters

doc	: The main xml document
node	: a pointer to the node to read value

Returns: the integer value in the node

Definition at line 141 of file vpXmlParser.cpp.

References vpException::fatalError, and vpException::ioError.

Referenced by writeMainClass().

◆ xmlReadStringChild()

std::string vpXmlParser::xmlReadStringChild	(	xmlDocPtr	doc,
		xmlNodePtr	node )

protected

Read an array of character.

Parameters

doc	: The main xml document
node	: a pointer to the node to read value

Returns: std::string representing the value.

Definition at line 117 of file vpXmlParser.cpp.

References vpException::fatalError.

Referenced by writeMainClass().

◆ xmlReadUnsignedIntChild()

unsigned int vpXmlParser::xmlReadUnsignedIntChild	(	xmlDocPtr	doc,
		xmlNodePtr	node )

protected

read an int

Warning: throw a vpException::ioError if the value cannot be parsed to an unsigned integer

Parameters

doc	: The main xml document
node	: a pointer to the node to read value

Returns: the unsigned integer value in the node

Definition at line 175 of file vpXmlParser.cpp.

References vpException::fatalError, and vpException::ioError.

Referenced by writeMainClass().

◆ xmlWriteBoolChild()

void vpXmlParser::xmlWriteBoolChild	(	xmlNodePtr	node,
		const char *	label,
		bool	value )

protected

write a bool.

Parameters

node	: a pointer to the node to read value
label	: label (name of the data) of the node
value	: boolean to write (true or false)

Definition at line 395 of file vpXmlParser.cpp.

Referenced by writeMainClass().

◆ xmlWriteCharChild()

void vpXmlParser::xmlWriteCharChild	(	xmlNodePtr	node,
		const char *	label,
		const char *	value )

protected

write an array of character.

Parameters

node	: a pointer to the node to read value
label	: label (name of the data) of the node
value	: pointer to the array of character to write

Definition at line 303 of file vpXmlParser.cpp.

Referenced by writeMainClass().

◆ xmlWriteDoubleChild()

void vpXmlParser::xmlWriteDoubleChild	(	xmlNodePtr	node,
		const char *	label,
		double	value )

protected

write a double.

Parameters

node	: a pointer to the node to read value
label	: label (name of the data) of the node
value	: double to write

Definition at line 363 of file vpXmlParser.cpp.

Referenced by writeMainClass().

◆ xmlWriteFloatChild()

void vpXmlParser::xmlWriteFloatChild	(	xmlNodePtr	node,
		const char *	label,
		float	value )

protected

write a float.

Parameters

node	: a pointer to the node to read value
label	: label (name of the data) of the node
value	: float to write

Definition at line 379 of file vpXmlParser.cpp.

Referenced by writeMainClass().

◆ xmlWriteIntChild()

void vpXmlParser::xmlWriteIntChild	(	xmlNodePtr	node,
		const char *	label,
		int	value )

protected

write an integer.

Parameters

node	: a pointer to the node to read value
label	: label (name of the data) of the node
value	: integer to write

Definition at line 331 of file vpXmlParser.cpp.

Referenced by writeMainClass().

◆ xmlWriteStringChild()

void vpXmlParser::xmlWriteStringChild	(	xmlNodePtr	node,
		const char *	label,
		const std::string &	value )

protected

write an array of character.

Parameters

node	: a pointer to the node to read value
label	: label (name of the data) of the node
value	: std::string to write;

Definition at line 317 of file vpXmlParser.cpp.

Referenced by writeMainClass().

◆ xmlWriteUnsignedIntChild()

void vpXmlParser::xmlWriteUnsignedIntChild	(	xmlNodePtr	node,
		const char *	label,
		unsigned int	value )

protected

write an unsigned integer.

Parameters

node	: a pointer to the node to read value
label	: label (name of the data) of the node
value	: unsigned integer to write

Definition at line 347 of file vpXmlParser.cpp.

Referenced by writeMainClass().

Member Data Documentation

◆ main_tag

std::string vpXmlParser::main_tag

protected

The name of the main tag for the file to parse

Definition at line 238 of file vpXmlParser.h.

Referenced by save(), setMainTag(), vpXmlParser(), and vpXmlParser().

◆ nodeMap

std::map<std::string, int> vpXmlParser::nodeMap

protected

The map describing the data to parse

Definition at line 233 of file vpXmlParser.h.

Referenced by setMap(), vpXmlParser(), and vpXmlParser().

Public Member Functions

Static Public Member Functions

Protected Member Functions Inherited from vpXmlParser

Detailed Description

Constructor & Destructor Documentation

◆ vpXmlParser() [1/2]

◆ vpXmlParser() [2/2]

◆ ~vpXmlParser()

Member Function Documentation

◆ cleanup()

◆ parse()

◆ readMainClass()

◆ save()

◆ setMainTag()

◆ setMap()

◆ writeMainClass()

◆ xmlReadBoolChild()

◆ xmlReadCharChild()

◆ xmlReadDoubleChild()

◆ xmlReadFloatChild()

◆ xmlReadIntChild()

◆ xmlReadStringChild()

◆ xmlReadUnsignedIntChild()

◆ xmlWriteBoolChild()

◆ xmlWriteCharChild()

◆ xmlWriteDoubleChild()

◆ xmlWriteFloatChild()

◆ xmlWriteIntChild()

◆ xmlWriteStringChild()

◆ xmlWriteUnsignedIntChild()

Member Data Documentation

◆ main_tag

◆ nodeMap