/** @file
	@brief Ryzom AI primitive_parsing description
	
	(C) 2005 - Doub
*/
/** @page primitive_parsing Primitive parsing in AIS

AIS data are taken from multiple kind of files. One of these filetypes is the primitive file. This file format is an XML application and contains a set of hierchically organized primitives.

@section Structure

The structure of that file is controlled by another XML file called world_editor_classes.xml. There is only a few basic node types in primitive files, but these nodes are highly paramterizable and can describe a wide range of data structures. The content of these parameters is what is controlled by the world_editor_classes.xml file.

Primitive files are created with the World Editor, a dedicated tool. The files are then read by several services, which can only intepret a subset of the primitive content. In the World Editor the file is a tree of nodes called primitives, each node having parameters called fields. This does not closely reflect the XML structures. In fact although primitives are XML nodes, fields are also XML nodes, subnodes of the primitive node, of predefined standard types, the field name and content being XML parameters of the XML subnode.

Each primitive can optionnaly have a hidden field which contains a part of its alias. This half-alias uniquely identifies the primitive inside the file. Each primitive file is associated with another alias part. The combination of the file half-alias, x, and the primitive half-alias in the file, y, uniquely identifies the primitive accross all files with the alias (A:x:y). The file part of the alias is defined in another file called file_id.cfg.

@section parsing Parsing

The parsing is in fact done in 2 steps, and is not done the same in all services.

The first step is common although not being done at the same time. It load the primitive file as a DOM document and check its XML validity and its content according to the world_editor_classes.xml file. In the EGS, this step is done at loading for all files declared in the common.cfg file. On the AIS, this is done after the service initialization, even after the service starts to tick, in commands in the config file. Thus a file can be loaded well after shard initialization while it is already running for a while.

The second step consist in interpreting that DOM tree loaded by the first step. This step differs greatly from one service to another. In the EGS, each manager (an EGS manager is a singleton which manage an aspect of the game) parses all primive files and extract the primitive nodes it needs. In the AIS, a special function is called just after the first step. That function parses the DOM tree and reacts to the nodes it encounters almost like a SAX parser. It extracts the current node information (including its type, name, and eventually some simple field subnodes like its alias) and generates some NeL like commands, and then parses the primitive children. The commands are interpreted in a kind of state machine which constructs objects roughly reflecting the primitives.

The main advantage of that method is that it's possible to cache a binary representation of the commands to speedup the loading of the AIS. The drawback is the complexity involved by this dual parsing scheme and the difficulty to modify it and add new primitive types.

There is also another mechanism based on the primitive parsing. The AIS objects that are derived from the CAliasChild class rather than the CChild class have special construction methods. These methods take as a parameter the DOM tree generated by the first parsing step and creates objects in the containers with a minimal set of default values. Usually some command from the second parsing step triggers this special methods passing them only a branch of the DOM tree, where the branch closely match the AIS object architecture. This is done for example for groups, group descriptors and outposts. It cannot be done for example for managers as there is some fake primitives inside managers that are not AIS objects.

*/
