first steps with tiramisu doc

doc/config.txt

@@ -362,8 +362,8 @@ read/write or read only mode::
     >>> print c.od1.var3
     value 
     
-Properties can also be defined on option groups, 
+Properties can also be defined on an option group, (that is, on an 
-(that is, on :ref:`option description`s), let's hide a group and try to access to it::
+:term:`option description`), let's hide a group and try to access to it::
 
     >>> c.read_write()
     >>> print c.od2.var4
@@ -404,24 +404,23 @@ The requirements
 
 Let's create an option wich has requirements::
 
-    >>> var1 = UnicodeOption('var1', '', u'value', requires=(('od1.var2', 
+    >>> from tiramisu.option import *
-       'non', 'hidden'),))
+    >>> from tiramisu.config import *
     >>> var2 = UnicodeOption('var2', '', u'oui')
-    >>> var3 = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 
+    >>> var1 = UnicodeOption('var1', '', u'value', requires=[{'option':var2, 'expected':u'non', 'action':'hidden'}])
-        'non', 'hidden'), ('od1.var2', 'non', 'disabled')))
+    >>> var3 = UnicodeOption('var3', '', u'value', requires=[{'option':var2, 'expected':u'non', 'action':'hidden'}, {'option':var2, 'expected':u'non', 'action':'disabled'}])
     >>> var4 = UnicodeOption('var4', '', u'oui')
-    >>>
     >>> od1 = OptionDescription('od1', '', [var1, var2, var3])
-    >>> od2 = OptionDescription('od2', '', [var4], requires=(('od1.var2', 
+    >>> od2 = OptionDescription('od2', '', [var4], requires=[{'option':od1.var2, 'expected':u'oui', 'action':'hidden', 'inverse':True}])
-        'oui', 'hidden', True),))
     >>> rootod = OptionDescription('rootod', '', [od1, od2])
     >>> c = Config(rootod)
-    >>> c.read_write()    
+    >>> c.read_write()
 
-The requirement here is the tuple `('od1.var2' , 'non', 'hidden')` wich means 
+The requirement here is the dict `{'option':var2, 'expected':u'non', 
-that is the option `'od1.var2'` is set to `'non'`, the option `'od1.var1'` is 
+'action':'hidden'}` wich means that is the option `'od1.var2'` is set to 
-gonna be hidden. On the other hand, if the option `'od1.var2'` is different 
+`'non'`, the option `'od1.var1'` is gonna be hidden. On the other hand, if the 
-from `'non'`, the option `'od1.var1'` is not hidden any more::
+option `'od1.var2'` is different from `'non'`, the option `'od1.var1'` is not 
+hidden any more::
 
     >>> print c.cfgimpl_get_settings()[rootod.od1.var1]
     []
@@ -443,10 +442,11 @@ from `'non'`, the option `'od1.var1'` is not hidden any more::
     >>> print c.od1.var1
     value
     
-The requirement on `od2` is `('od1.var2', 'oui', 'hidden', True)`, which means 
+The requirement on `od2` is `{'option':od1.var2, 'expected':u'oui', 
-that if the option `od1.var2` is set to `oui`, the option is not hidden 
+'action':'hidden', 'inverse':True}`, which means that if the option `od1.var2` 
-(because of the `True` at the end of the tuple wich means 'inverted', take a 
+is set to `oui`, the option is not hidden (because of the `True` at the end of 
-look at the :doc:`consistency` document.):: 
+the tuple wich means 'inverted', take a look at the :doc:`consistency` 
+document.)::
 
     >>> print c.od2.var4
     oui
@@ -473,21 +473,110 @@ Requirements can be accumulated
 Requirements can be accumulated for different or identical properties (inverted 
 or not)::
 
-    >>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non', 
+    >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, 
-        'hidden'), ('od1.var1', 'oui', 'hidden')))
+        'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'expected':'oui', 
-    >>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non', 
+        'action':'hidden'}])
-        'hidden'), ('od1.var1', 'oui', 'disabled', True)))
+    >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, 
-
+        'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'excepted':'oui', 
+        'action':'disabled', 'inverse':True}])
+    
 But it is not possible to have inverted requirements on the same property. 
 Here is an impossible situation::
 
-    >>> a = UnicodeOption('var3', '', u'value', requires=(('od1.var2', 'non', 
+    >>> a = UnicodeOption('var3', '', u'value', requires=[{'option':od1.var2, 
-        'hidden'), ('od1.var1', 'oui', 'hidden', True)))
+        'expected':'non', 'action':'hidden'}, {'option':od1.var1, 'expected':'oui', 
+        'hidden', True}])
+    
     Traceback (most recent call last):
     [...]
     ValueError: inconsistency in action types for option: var3 action: hidden
+            
+The calculations
+~~~~~~~~~~~~~~~~~
 
-        
+Let's create four calculation functions::
+
+    def return_calc():
+        #return an unicode value
+        return u'calc'
+    
+    def return_value(value):
+       return value
+    
+    def return_value_param(param=u''):
+       return param
+    
+    def return_no_value_if_non(value):
+        #if value is not u'non' return value
+        if value == u'non':
+            return None
+        else:
+            return value
+
+Then we create four options using theses functions::
+
+    >>> var1 = UnicodeOption('var1', '', callback=return_calc)
+    >>> var2 = UnicodeOption('var2', '', callback=return_value, callback_params={'': (u'value',)})
+    >>> var3 = UnicodeOption('var3', '', callback=return_value_param, callback_params={'param': (u'value_param',)})
+    >>> var4 = UnicodeOption('var4', '', callback=return_no_value_if_non, callback_params={'': (('od1.var5', False),)})
+    >>> var5 = UnicodeOption('var5', '', u'oui')
+    >>> od1 = OptionDescription('od1', '', [var1, var2, var3, var4, var5])
+    >>> rootod = OptionDescription('rootod', '', [od1])
+    >>> c = Config(rootod)
+    >>> c.read_write()
+
+The first option `var1` returns the result of the `return_calc` function, wich 
+is `u'calc'`::
+
+    >>> print c.od1.var1
+    calc
+
+The second option `var2` returns the result of the `return_value` fucntion, 
+wich is `value`. The parameter `u'value'` is passed to this function::
+
+    >>> print c.od1.var2
+    value
+
+The third option `var3` returns the result of the function `return_value_param`
+with the named parameter `param` and the value `u'value_param'`::
+
+    >>> print c.od1.var3
+    value_param
+
+The fourth option `var4` returns the reslut of the function `return_no_value_if_non` 
+that is the value of `od1.var5` exceptif the value is  u`non`::
+
+    >>> print c.od1.var4
+    oui
+    >>> c.od1.var5 = u'new'
+    >>> print c.od1.var4
+    new
+    >>> c.od1.var5 = u'non'
+    >>> print c.od1.var4
+    None
+    
+The calculation replaces the default value. 
+If we modify the value, the calculation is not carried out any more::
+
+    >>> print c.od1.var1
+    calc
+    >>> c.od1.var1 = u'new_value'
+    >>> print c.od1.var1
+    new_value
+    
+To force the calculation to be carried out in some cases, one must add the 
+`frozen` and the `force_default_on_freeze` properties::
+
+    >>> c.cfgimpl_get_settings()[rootod.od1.var1].append('frozen')
+    >>> c.cfgimpl_get_settings()[rootod.od1.var1].append('force_default_on_freeze')
+    >>> print c.od1.var1
+    calc
+    >>> c.cfgimpl_get_settings()[rootod.od1.var1].remove('frozen')
+    >>> c.cfgimpl_get_settings()[rootod.od1.var1].remove('force_default_on_freeze')
+    >>> print c.od1.var1
+    new_value
+    
+     
 Configuration's interesting methods 
 ------------------------------------------