========================
The configuration module
========================

This configuration module (called cmod) is dedicated to configuration storage and export.

Every Pyrame module can register in the cmod and store its configuration parameters.
The modules are stored in a tree representing the arborescence of the system.

The cmod contains at any time a copy of the configuration of all the modules and it can generate xml files containing all the parameters to be used with :doc:`calxml <calxml_format>`.

 
API
===

.. automodule:: cmd_cmod
    :members: 
    :member-order: bysource

How to use it?
==============

First load the configuration file with *load_config_cmod*. Then use *transition_cmod* to make the state machine do a transition.

How does it works?
==================

The module uses the following algorithm to parse the configuration and apply phases. Every time a new module instance is found while parsing, the module:

    - searches in the module API for the name phasename_modulename
    - gets the parameters name of this function
    - gets the parameters values from the xml configuration or from the defaults file.
    - executes the function on the corresponding module with the parameters
    - continues with all the child modules 
    - searches in the module API for the name phasename_fin_modulename
    - executes the function on the corresponding module with the parameters

As you can see, two different functions are called for every module: one when the module is first found and another after finding all its child modules.

Example
=======

Imagine we want to initialize a setup with a network switch and two connected cards. We have to initialize the switch with its port number as a parameter, then set the ip address for the two cards and finally calculate the MAC table on the switch. We will implement three functions.

.. code-block:: python

   def init_switch(switch_nb_port):
     init_ports(nb_port)

   def init_nic(nic_ip):
     setup_ip(nic_ip)

   def init_fin_switch():
     calc_mac_table()

Then create an xml file like this:

.. code-block:: xml

   <switch name="sw">
     <param name="switch_nb_port">6</param>
     <nic name="nic1">
       <param name="nic_ip">192.168.0.1</param>
     </nic>
     <nic name="nic2">
       <param name="nic_ip">192.168.0.2</param>
     </nic>
   </switch>

When the init phase is applied, these functions will be called in this order:

- init_switch("6")
- init_nic("192.168.0.1")
- init_nic("192.168.0.1")
- init_fin_switch()

Note that all parameters are strings. If a function does not exists (like init_fin_nic in the example), it is simply ignored.