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