imaging::XmlReader Class Reference
[XML Module]

Reads XML files using a stream interface. More...

#include <XmlReader.hpp>

List of all members.

Public Member Functions

 XmlReader (const std::string &xml_file_name, const std::string &root_element)
 ~XmlReader ()
XmlReaderoperator>> (const stream_command &command)
template<size_t N, class data_t>
XmlReaderoperator>> (ublas::fixed_vector< data_t, N > &value)
template<size_t N, class data_t>
XmlReaderoperator>> (std::vector< ublas::fixed_vector< data_t, N > > &vector)
XmlReaderoperator>> (std::vector< float_t > &vector)
XmlReaderoperator>> (float_t &value)
XmlReaderoperator>> (size_t &value)
XmlReaderoperator>> (int &value)
XmlReaderoperator>> (bool &value)
XmlReaderoperator>> (std::string &string)
XmlReaderoperator>> (std::vector< std::string > &vector)
template<class data_t>
XmlReaderoperator>> (const default_value< data_t > &command)
template<class data_t>
XmlReaderoperator>> (const try_read< data_t > &command)
template<class data_t>
XmlReaderoperator>> (std::vector< data_t > &vector)
template<class data_t>
XmlReaderoperator>> (std::vector< boost::shared_ptr< data_t > > &vector)
template<class data_t>
XmlReaderoperator>> (data_t &object)
size_t n_elements () const
size_t n_child_elements () const
std::string current_element_name () const

Static Public Attributes

static const stream_command end_element
 Stream command to end an element.

Classes

class  attribute
 Stream command to select an attribute at the current path. More...
class  child_element
 Stream command to add a child element to the current path. More...
class  default_value
 Stream command to read an object if it is present at the current path and to retrieve an default value if not. More...
class  element
 Stream command to add an element to the current path. More...
class  try_read
 Stream command to read an object if it is present at the current path and to keep it unchanged if not. More...
class  XmlNoTagException
 This exception is throw if the attempt to read an object fails. More...


Detailed Description

Reads XML files using a stream interface.

This class enables you to read an XML file using an interface which loosely resembles the stream interface used in iostream to read from input streams. An XmlReader object is initialized by an XML file and then represents an XML stream which you can read using operator>>(data_t &), where data_t is the type of the object to be read. XmlReader provides the stream operator for the built-in data types. If called for other types, XmlReader calls the function xml_handler<data_t>::read_object() which then reads the object from the stream. I.e. by specializing xml_handler for custom data types the user enables XmlReader to read these types. Implementations of xml_handler for various classes of the imaging2 modules can be found in the files xmlio.hpp and xmlio.cxx in the module subdirectories.

Consider the following XML file:

  <imaging2>
    <person age="50">Franz</person>
    <person age="50">Arne</person>
    
    <some_float>0.5</some_float>
    <some_float>1.0</some_float>
    <some_float>1.5</some_float>
  </imaging2>

An XmlReader object reads objects at the position of its current path. This path is the sequence of element names (and possibly indices) which leads to a given node in an XML file. This concept is very similiar to the idea of XPath. The current path of a XmlReader can be altered by passing stream commands to the input stream. An example is given below:

  using imaging;
  
  XmlReader xml_in("some_file.xml", "imaging2"); // read some_file.xml; "imaging2" is the root element
  
  std::string name;
  unsigned int age = 0;
  
  xml_in >> XmlReader::element("person"); // select element "person"
  xml_in >> XmlReader::attribute("age") >> age; // read attribute "age"
  xml_in >> name >> XmlReader::end_element; // read the person's name and close element "person"
  
  std::vector<float_t> some_floats;
  xml_in >> XmlReader::element("some_float"); // select element "some_float"
  xml_in >> some_floats; // read the floats                         
                         // there is no need to pass XmlReader::end_element here,
                            because float is a built-in type
Here, XmlReader::element(), XmlReader::attribute() and XmlReader::end_element are stream commands. In case of the above XML file, the vector some_floats will be resized to length 3 and will hold the data 0.5, 1.0, 1.5.

Assume further that the user has implemented a class Person and xml_handler<Person> which reads a person's data as above. Assuming that the class declaration and the declaration of xml_handler<Person> both reside in "Person.h", then she can use XmlReader in the following way:

  #include "Person.h"
  
  XmlReader xml_in("some_file.xml", "imaging2"); // read some_file.xml; "imaging2" is the root element
  
  Person person;
  std::vector<Person> people;
  
  xml_in >> person; // read person (note that there is no need to select the element "person")
  xml_in >> people; // read all the people at the current path
In case of the above XML file, the vector people will be resized to length 1 and will hold the data of fifty years old Franz.

Note reading a vector of floats is different from a custom data type. For the custom data Person neither XmlReader::element() nor XmlReader::end_element have to be passed to the stream. In case of a vector of floats XmlReader::element() must be passed, but not XmlReader::end_element. The reason for this behavior is that XmlReader does not know which element name identifies the floats. Introducing a standard element name (such as <float> </float>) would often be inconvenient because it makes intuitive element names like <super_parameter>10^9</super_parameter> impossible. This behavior is the same for all built-in types.

See also:
XmlWriter

Constructor & Destructor Documentation

imaging::XmlReader::XmlReader ( const std::string &  xml_file_name,
const std::string &  root_element 
)

Constructs an XML input stream from file file_name and sets the current path to root_element. An XML file can only have one root node, so it is okay to fix it during construction.

References imaging::MessageInterface::DEBUG_ONLY, and imaging::MessageInterface::out.

imaging::XmlReader::~XmlReader (  ) 

Destructor. Closes the input file.


Member Function Documentation

XmlReader & imaging::XmlReader::operator>> ( const stream_command &  command  ) 

Passes any other stream command to the stream.

template<size_t N, class data_t>
XmlReader& imaging::XmlReader::operator>> ( ublas::fixed_vector< data_t, N > &  value  )  [inline]

Reads a ublas::fixed_vector from the stream.

template<size_t N, class data_t>
XmlReader& imaging::XmlReader::operator>> ( std::vector< ublas::fixed_vector< data_t, N > > &  vector  )  [inline]

Reads a vector of fixed size vectors from the stream. The function assumes that each vector is enclosed by element tags identified by the last XmlReader::element() passed to the input stream. In this respect this function is different from the generic version operator>>(data_t &).

References end_element.

XmlReader & imaging::XmlReader::operator>> ( std::vector< float_t > &  vector  ) 

Reads a vector of floats from the stream. The function assumes that each string is enclosed by element tags identified by the last XmlReader::element() passed to the input stream. In this respect this function is different from the generic version operator>>(data_t &).

XmlReader & imaging::XmlReader::operator>> ( float_t value  ) 

Reads a floating point value from the stream.

XmlReader & imaging::XmlReader::operator>> ( size_t value  ) 

Reads an unsigned integer from the stream.

XmlReader & imaging::XmlReader::operator>> ( int &  value  ) 

Reads an integer from the stream.

XmlReader & imaging::XmlReader::operator>> ( bool &  value  ) 

Reads a bool from the stream.

XmlReader & imaging::XmlReader::operator>> ( std::string &  string  ) 

Reads string from the stream.

XmlReader & imaging::XmlReader::operator>> ( std::vector< std::string > &  vector  ) 

Reads a vector of strings from the stream. The function assumes that each string is enclosed by element tags identified by the last XmlReader::element() passed to the input stream. In this respect this function is different from the generic version operator>>(data_t &).

template<class data_t>
XmlReader& imaging::XmlReader::operator>> ( const default_value< data_t > &  command  )  [inline]

Passes an XmlReader::default_value() command to the stream.

References imaging::XmlReader::default_value< data_t >::_default_object, and imaging::XmlReader::default_value< data_t >::_object.

template<class data_t>
XmlReader& imaging::XmlReader::operator>> ( const try_read< data_t > &  command  )  [inline]

Passes an XmlReader::try_read() command to the stream.

References imaging::XmlReader::try_read< data_t >::_object.

template<class data_t>
XmlReader& imaging::XmlReader::operator>> ( std::vector< data_t > &  vector  )  [inline]

Reads a vector of data_t objects from the stream. The class specialization xml_handler<data_t> has to be defined.

References end_element.

template<class data_t>
XmlReader& imaging::XmlReader::operator>> ( std::vector< boost::shared_ptr< data_t > > &  vector  )  [inline]

Constructs data_t objects in vector and reads data_t objects from the stream. The class specialization xml_handler<data_t> has to be defined.

References end_element.

template<class data_t>
XmlReader& imaging::XmlReader::operator>> ( data_t &  object  )  [inline]

Reads a data_t object from the stream. The class specialization xml_handler<data_t>::read_object() has to be defined.

References end_element.

size_t imaging::XmlReader::n_elements (  )  const

Returns the number of different nodes in the document which are referenced by the current path. If the current path uniquely determines an object this function returns 1. If no object exists at the current path it returns 0.

size_t imaging::XmlReader::n_child_elements (  )  const

Returns the number of child nodes of elements in the document which are referenced by the current path.

std::string imaging::XmlReader::current_element_name (  )  const

Returns the name of the current element. In case the last element was selected by passing XmlReader::element(identifier) to the stream, this function returns identifier.


Member Data Documentation

const XmlReader::stream_command imaging::XmlReader::end_element [static]

Stream command to end an element.

Stream command to remove the last element from the current path. Every XmlReader::element(std::string &) and XmlReader::element(std::string &, size_t) command passed to the input stream has to be followed by an Xml::end_element command. This is not true for XmlReader::element(size_t) and XmlReader::attribute() commands.

Referenced by operator>>().


The documentation for this class was generated from the following files:

Generated on Tue Feb 10 10:01:31 2009 for imaging2 by  doxygen 1.5.5