4b00606582a345b268fa09cba6aed864f012bc09
[tiramisu.git] / doc / consistency.txt
1 .. default-role:: literal
2
3 The global configuration's consistency
4 ========================================
5
6 :module: :api:`config.py`
7 :tests: :api:`test_option_consistency.py`
8
9 Option's values type validation
10 --------------------------------
11
12 When a value is set to the option, the value is validated by the 
13 option's :api:`option.Option()` validator's type.
14
15 Notice that if the option is `multi`, that is the `multi` attribute is set to 
16 `True`, then the validation of the option value accepts a list of values 
17 of the same type.
18
19 Requirements
20 ------------
21
22 Configuration options can specify requirements as parameters at the init 
23 time, the specification of some links between options or groups allows 
24 to carry out a dependencies calculation. For example, an option can ben 
25 hidden if another option has been set with some expected value. This is 
26 just an example, because the possibilities are hudge.
27
28 A requirement is specified using a list of triplets. The first element 
29 of the triplet gives the path of the option that is required, the second 
30 element is the value wich is expected to trigger the callback, and the 
31 third one is the callback's action name (`hide`, `show`...)::
32
33     stroption = StrOption('str', 'Test string option', default="abc", 
34                           requires=[('int', 1, 'hide')])
35
36 Take a look at an example here 
37 :api:`test_option_consistency.test_hidden_if_in()`
38
39 Config updates
40 ---------------
41
42 New configuration options and groups can be dynamically added. 
43
44 The configuration has to be *updated* after that the description has been 
45 passed to the Config objet, see:
46
47 ::
48
49     >>> config = Config(descr)
50     >>> newoption = BoolOption('newoption', 'dummy twoo', default=False)
51     >>> descr.add_child(newoption)
52     >>> config.update()
53     >>> config.newoption
54     False
55
56 in 
57
58 - :api:`test_option_consistency.test_newoption_add_in_descr()`
59 - :api:`test_option_consistency.test_newoption_add_in_subdescr()`
60 - :api:`test_option_consistency.test_newoption_add_in_config()`
61
62
63 Validation upon a whole configuration object
64 ----------------------------------------------
65
66 An option's integrity can be validated towards a whole configuration.
67
68 This type of validation is very open. Let's take a use case : an option 
69 has a certain value, and the value of this option can change the owner 
70 of another option or option group... Everything is possible.
71
72 For example, the configuration paths have to be unique in the 
73 :ref:`glossary#schema`, the validation is carried out at the 
74 :api:`config.Config._cfgimpl_build()` time in the 
75 :api:`config.Config._validate_duplicates()` method.
76
77 Other hook are availables to validate upon a whole configuration at any 
78 time.
79
80 .. FIXME : get the validates hooks from the original config pypy's code
81
82 Identical option names 
83 ----------------------
84
85 If an :api:`option.Option()` happens to be defined twice in the 
86 :ref:`glossary#schema` (e.g. the :api:`option.OptionDescription()`), 
87 :that is the two options actually have the same name, an exception is raised.
88
89 The calculation is currently carried out in the samespace, for example 
90 if `config.gc.name` is defined, another option in `gc` with the name 
91 `name` is **not** allowed, whereas `config.whateverelse.name` is still 
92 allowed. 
93     
94 .. the calculation was carried out by the requires, wich is not a goog idead
95
96     Type constraints with the `multi` type
97     ----------------------------------------
98
99     By convention, if a multi option has somme requires, the constraints on 
100     the multi type is in all the OptionGroup (a group has to be `multi`, and 
101     a multi of the same length).
102
103     See :api:`test_option_consistency.test_multi_constraints()`
104