Merge branch 'master' of ssh://git.labs.libre-entreprise.org/gitroot/tiramisu
[tiramisu.git] / doc / config.txt
1 .. default-role:: literal
2
3 ===============================
4 Configuration handling basics
5 ===============================
6
7 Tiramisu is designed with three main objects :
8
9 - :class:`tiramisu.config.Config` witch is the whole configuration entry point
10 - :class:`tiramisu.option.Option` stands for the option type
11 - :class:`tiramisu.option.OptionDescription` stands for the description (the schema)
12
13 Accessing the configuration `Option`'s
14 -----------------------------------------
15
16 The `Config` object attribute access notation stands for the value of the
17 configuration's `Option`. That is, the `Config`'s object attribute is the name
18 of the `Option`, and the value is the value accessed by the `__getattr__`
19 attribute access mechanism.
20
21 If the attribute of the `Config` called by `__getattr__` has not been set before
22 (by the classic `__setattr__` mechanism), the default value of the `Option`
23 object is returned, and if no `Option` has been declared in the
24 `OptionDescription` (that is the schema of the configuration), an
25 `AttributeError` is raised.
26
27 ::
28
29     >>> gcdummy = BoolOption('dummy', 'dummy', default=False)
30     >>> gcdummy._name
31     'dummy'
32     >>> gcdummy.getdefault()
33     False
34     >>> descr = OptionDescription('tiramisu', '', [gcdummy])
35     >>> cfg = Config(descr)
36     >>> cfg.dummy
37     False
38     >>> cfg.dummy = True
39     >>> cfg.dummy
40     True
41     >>> cfg.idontexist
42     AttributeError: 'OptionDescription' object has no attribute 'idontexist'
43
44 The configuration `Option` objects (in this case the `BoolOption`), are
45 organized into a tree into nested `OptionDescription` objects. Every
46 option has a name, as does every option group. The parts of the full
47 name of the option are separated by dots: e.g.
48 ``config.optgroup.optname``.
49
50 Let's make the protocol of accessing a config's attribute explicit
51 (because explicit is better than implicit):
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 know the path:
69
70 ::
71
72     >>> config.gc.dummy
73     False
74
75 Setting the values of the options
76 ----------------------------------------
77
78 An important part of the setting of the configuration consists of setting the
79 values of the configuration options. There are different ways of setting values,
80 the first one is of course the `__setattr__` method
81
82 ::
83
84     cfg.name = value
85
86 .. module:: tiramisu.config
87
88 The handling of options is split into two parts: the description of
89 which options are available, what their possible values and defaults are
90 and how they are organized into a tree. A specific choice of options is
91 bundled into a configuration object which has a reference to its option
92 description (and therefore makes sure that the configuration values
93 adhere to the option description).
94
95 Configuration's interesting methods
96 ------------------------------------------
97
98 A `Config` object is informed by an `option.OptionDescription`
99 instance. The attributes of the ``Config`` objects are the names of the
100 children of the ``OptionDescription``.
101
102 Here are the (useful) methods on ``Config``:
103
104
105 With this `config.Config()` configuration management entry point,
106 it is possible to
107
108 - `iter` on config, notice that there is an iteration order wich is
109   the order of the :ref:`optdescr` specification entries,
110 - compare two configs (equality),
111 - export the whole config into a `dict` with `config.make_dict()`,
112
113 `option.Option()` objects in a config are iterable in the pythonic
114 way, that is something like `[(name, value) for name, value in config]`.
115
116 To iter on groups in the same manner, use the
117 `config.Config.iter_groups()` method wich yields generators too.
118
119 .. currentmodule:: tiramisu.config
120
121 .. autoclass:: Config
122
123     .. automethod:: __init__
124
125     .. rubric:: Methods
126
127     .. autosummary::
128
129       ~Config.find
130       ~Config.find_first
131       ~Config.iter_groups
132       ~Config.__iter__
133
134     .. automethod:: find
135     .. automethod:: find_first
136     .. automethod:: iter_groups
137     .. automethod:: __iter__