681a4f8924c1b81bb43ff20ee6fd65c1caf1f33c
[tiramisu.git] / doc / config.txt
1 .. default-role:: literal
2
3 ===============================
4 Configuration handling basics
5 ===============================
6
7 `Config` and `Option` objects
8 =========================================
9
10
11 Take a look at `test_config.test_base_config()` or
12 `test_config.test_base_config_and_groups()`.
13
14 Accessing the configuration `Option`'s
15 -----------------------------------------
16
17 The `Config` object attribute access notation stands for the value of the
18 configuration's `Option`. That is, the `Config`'s object attribute is the name
19 of the `Option`, and the value is the value accessed by the `__getattr__`
20 attribute access mechanism.
21
22 If the attribute of the `Config` called by `__getattr__` has not been set before
23 (by the classic `__setattr__` mechanism), the default value of the `Option`
24 object is returned, and if no `Option` has been declared in the
25 `OptionDescription` (that is the schema of the configuration), an
26 `AttributeError` is raised.
27
28 ::
29
30     >>> gcdummy = BoolOption('dummy', 'dummy', default=False)
31     >>> gcdummy._name
32     'dummy'
33     >>> gcdummy.getdefault()
34     False
35     >>> descr = OptionDescription('tiramisu', '', [gcdummy])
36     >>> cfg = Config(descr)
37     >>> cfg.dummy
38     False
39     >>> cfg.dummy = True
40     >>> cfg.dummy
41     True
42     >>> cfg.idontexist
43     AttributeError: 'OptionDescription' object has no attribute 'idontexist'
44
45 The configuration `Option` objects (in this case the `BoolOption`), are
46 organized into a tree into nested `OptionDescription` objects. Every
47 option has a name, as does every option group. The parts of the full
48 name of the option are separated by dots: e.g.
49 ``config.optgroup.optname``.
50
51 **Can you repeat it, what is the protocol of accessing a config's attribute ?**
52
53 1. If the option has not been declared, an `AttributeError` is raised,
54
55 2. If an option is declared, but neither a value nor a default value has
56    been set, the returned value is `None`,
57
58 3. If an option is declared and a default value has been set, but no value
59    has been set, the returned value is the default value of the option,
60
61 4. If an option is declared, and a value has been set, the returned value is
62    the value of the option.
63
64 What if a value has been set and `None` is to be returned again ? Don't
65 worry, an option value can be "reseted" with the help of the `option.Option.reset()`
66 method.
67
68 If you do not want to use the pythonic way, that is the attribute access
69 way to obtain the value of the configuration option, you can also search
70 for it recursively in the whole config namespaces with the ``get()``
71 method :
72
73 ::
74
75     >>> config.get('bool')
76     True
77
78 To find the right option, `get()` searches recursively into the whole
79 tree. For example, to find an option which is in the `gc` namespace
80 there are two possibilites.
81
82 If you know the path:
83
84 ::
85
86     >>> config.gc.dummy
87     False
88
89 If you don't remember the path:
90
91 ::
92
93     >>> config.get('dummy')
94     False
95
96 Setting the values of the options
97 ----------------------------------------
98
99 An important part of the setting of the configuration consists of setting the
100 values of the configuration options. There are different ways of setting values,
101 the first one is of course the `__setattr__` method
102
103 ::
104
105     cfg.name = value
106
107 wich has the same effect that the "global" `set()` method : it expects that
108 the value owner is the default `glossary#valueowner`
109
110 ::
111
112      cfg.set(name=value)