*************************************************************************
************		Welcome to xmlParameters++	*****************
************			version 1.0	 	*****************
*************************************************************************

		Saving/loading parameters of a C++ program from an xml tree.

			Author : Adrien Wohrer
			Institution : ODYSSEE, INRIA Sophia Antipolis
			Contact : Adrien.Wohrer@sophia.inria.fr
			Code started september 2006.


************** GOAL:


Hi, this is a small library that I wrote to load the multiple parameters of VirtualRetina, a retina simulation software.
Its goal is to be able to save/load a C++ object-based architecture to an XML tree, in which only relevant parameters should be stored (the parameters that define the C++ objects, not necessarily ALL C++ fields of the object.)

Underlying are c++ 'xml-handling' objects that wrap the real objects, and know how to save/load the parameters of the object that has been wrapped.



************** EXAMPLE OF USE:
Go to directory Example, read the README, follow the instructions.
Launch the program Test_Bus directly from directory Example (otherwise, the program aborts)


************** USEFUL FUNCTIONS AND CLASSES:

are those defined and commented in file xml_parameters.h
other headers do not concern you directly unless you are interested in the underlying architecture.


************** GENERAL PRINCIPLE OF THE CONVERSION FROM C++ CLASSES TO XML TREE

a C++ typename Toto, once it is xml_ized, can be wrapped by a c++ object xmlObject<Toto>. Globally, an xmlObject<WHATEVER> knows how to save/load itself from a given father_node of an xml tree. Two possibilities:

(CASE 1) the xmlObject has a non-empty string name xmlName ="toto"
It will then correspond to an effective NODE in the xml tree, which will be a child node of node father_node. The xml_ized parameters of Toto will be saved as attributes of node "toto". The xml_ized object members of Toto will be savable/loadable recursively from node "toto" considered as their father_node.

(CASE 2) the xmlObject has an empty string name xmlName =""
It will then correspond to no effective node in the xml tree. The xml_ized parameters of Toto will be saved as attributes of node father_node. The xml_ized object members of Toto will be savable/loadable from node father_node considered as their father_node. Be careful with this degenerated case, it leads easily to undesired behaviors.




************** SPECIAL TREATMENT FOR POINTERS:

This library allows to initialize pointers by reading an xml file, thanks to a template specialisation of xmlObject< TYPE* >. And, of course, to save initialized pointers in the xml tree.

The initialization of a pointer can include virtuality and derived objects: An object factory can build the appropriate derived object, by reading the xml file. This is used, for example, in the definition of a Retina object. All you have to do is REGISTER in the factory each derived type you want to be able to build.

A pointer to an xml_ized class is also considered as an intermediate xml object, so it also has an xmlName, with the same rules as precedingly:

(CASE 1) the pointer has a string name pointerName="totoPoint"
It will then correspond to an effective NODE in the xml tree. Node "totoPoint" will have 0 or 1 child node corresponding to the pointed object:
<father_node>
	<totoPoint>
		<tata my-int="4"/>
	</totoPoint>
</father_node>
with "tata" being the name associated to an object Tata : public Toto {}


(CASE 2) the pointer has a string name pointerName =""
It will then correspond to no effective node in the xml tree.
<father_node>
	<tata my-int="4"/>
</father_node>



************** SPECIAL TREATMENT FOR CONTAINERS (vector, list, deque) :

Follows the same rule as for pointers : the container is associated or not to a real xmlnode, according to its xmlName.
It is provided by a specialisation xmlObject <Cont<TYPE> >. where Cont is vector, list or deque.

ex:

<father_node>
	<totoVector>
		<toto my-int="4"/>
		<toto my-int="5"/>
	</totoVector>
</father_node>



*********** TO BE CONTINUED ! ******************************************
