documentation update
[tiramisu.git] / doc / consistency.txt
1 .. default-role:: literal
2
3 .. currentmodule:: tiramisu
4
5 The global consistency
6 ===========================
7
8 Identical option names
9 ----------------------
10
11 If an :class:`~option.Option()` happens to be defined twice in the
12 :term:`schema` (e.g. the :class:`~option.OptionDescription()`),
13 that is the two options actually have the same name, an exception is raised.
14
15 The calculation is currently carried out in the samespace, for example
16 if `config.gc.name` is defined, another option in `gc` with the name
17 `name` is **not** allowed, whereas `config.whateverelse.name` is still
18 allowed.
19
20 Option's values type validation
21 --------------------------------
22
23 When a value is set to the option, the value is validated by the
24 option's :class:`option.Option()` validator's type.
25
26 Notice that if the option is `multi`, that is the `multi` attribute is set to
27 `True`, then the validation of the option value accepts a list of values
28 of the same type.
29
30 For example, an :class:`option.IntOption` validator waits for an `int` object of 
31 course, an :class:`option.StrOption` validator waits for an `str`, vs...
32
33 Requirements
34 ------------
35
36 Configuration options can specify requirements as parameters at the init
37 time, the specification of some links between options or groups allows
38 to carry out a dependencies calculation. For example, an option can ben
39 hidden if another option has been set with some expected value. This is
40 just an example, because the possibilities are hudge.
41
42 A requirement is specified using a list of triplets. The first element
43 of the triplet gives the path of the option that is required, the second
44 element is the value wich is expected to trigger the callback, and the
45 third one is the callback's action name (`hide`, `show`...)::
46
47     stroption = StrOption('str', 'Test string option', default="abc",
48                           requires=[('int', 1, 'hide')])
49
50 Take a look at an example here
51 `test_option_consistency.test_hidden_if_in()`
52
53 Validation upon a whole configuration object
54 ----------------------------------------------
55
56 An option's integrity can be validated towards a whole configuration.
57
58 This type of validation is very open. Let's take a use case : an option
59 has a certain value, and the value of this option can change the owner
60 of another option or option group... Everything is possible.
61
62 .. currentmodule:: tiramisu.option
63
64 Other hooks are availables to validate upon a whole configuration at any time, 
65 for example the consistency between two options (typically, an 
66 :class:`IPOption` and a :class:`NetworkOption`).
67
68 Values that are calculated
69 --------------------------------
70
71 An option that have a callback is considered to have a value that is to be 
72 calculated. 
73
74 An option's property with a `force_store_value` attribute is considered to be 
75 modified at the first calculation.
76
77 .. automodule:: tiramisu.autolib
78     :members:
79