Merge branch 'master' of ssh://git.labs.libre-entreprise.org/gitroot/tiramisu
[tiramisu.git] / doc / config.txt
1 .. default-role:: literal
2
3 ===============================
4 Options handling basics
5 ===============================
6
7 Tiramisu is made of almost 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 types
11 - :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
12
13 Accessing the `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 `Option` objects (in this case the `BoolOption`), are organized into a tree
45 into nested `OptionDescription` objects. Every option has a name, as does every
46 option group. The parts of the full name of the option are separated by dots:
47 e.g. ``cfg.optgroup.optname``.
48
49 Let's make the protocol of accessing a config's attribute explicit
50 (because explicit is better than implicit):
51
52 1. If the option has not been declared, an `AttributeError` is raised,
53
54 2. If an option is declared, but neither a value nor a default value has
55    been set, the returned value is `None`,
56
57 3. If an option is declared and a default value has been set, but no value
58    has been set, the returned value is the default value of the option,
59
60 4. If an option is declared, and a value has been set, the returned value is
61    the value of the option.
62
63 But there are special exceptions. We will see later on that an option can be a
64 :term:`mandatory option`. A mandatory option is an option that must have a defined value.
65 If no value have been set yet, the value is `None`.
66 When the option is called to retrieve a value, an exception is raised.
67
68 What if a value has been set and `None` is to be returned again ? Don't
69 worry, an option value can be "reseted" with the help of the `option.Option.reset()`
70 method.
71
72 If you know the path:
73
74 ::
75
76     >>> config.gc.dummy
77     False
78
79 Setting the values of the options
80 ----------------------------------------
81
82 An important part of the setting of the configuration consists of setting the
83 values of the configuration options. There are different ways of setting values,
84 the first one is of course the `__setattr__` method
85
86 ::
87
88     cfg.name = value
89
90 And if you wanna come back to a default value, use the builtin `del()` function::
91
92     del(cfg.name)
93
94 .. module:: tiramisu.config
95
96 .. _`tree`:
97
98 The handling of options
99 ~~~~~~~~~~~~~~~~~~~~~~~~~~
100
101 The handling of options is split into two parts: the description of
102 which options are available, what their possible values and defaults are
103 and how they are organized into a tree. A specific choice of options is
104 bundled into a configuration object which has a reference to its option
105 description (and therefore makes sure that the configuration values
106 adhere to the option description).
107
108
109 Common manipulations
110 ------------------------
111
112 Let's perform some common manipulation on some options:
113
114 >>> from tiramisu.config import Config
115 >>> from tiramisu.option import UnicodeOption, OptionDescription
116 >>>
117 >>> var1 = UnicodeOption('var1', 'first variable')
118 >>> var2 = UnicodeOption('var2', '', u'value')
119 >>>
120 >>> od1 = OptionDescription('od1', 'first OD', [var1, var2])
121 >>> rootod = OptionDescription('rootod', '', [od1])
122
123 let's set somme access rules on the main namespace
124
125 >>> c = Config(rootod)
126 >>> c.read_write()
127
128 let's travel the namespaces
129
130 >>> print c
131 [od1]
132 >>> print c.od1
133 var1 = None
134 var2 = value
135 >>> print c.od1.var1
136 None
137 >>> print c.od1.var2
138 value
139
140 let's modify a value (careful to the value's type...)
141
142 >>> c.od1.var1 = 'value'
143 Traceback (most recent call last):
144 [...]
145 ValueError: invalid value value for option var1
146 >>> c.od1.var1 = u'value'
147 >>> print c.od1.var1
148 value
149 >>> c.od1.var2 = u'value2'
150 >>> print c.od1.var2
151 value2
152
153 let's come back to the default value
154
155 >>> del(c.od1.var2)
156 >>> print c.od1.var2
157 value
158
159 The value is saved in a :class:`~tiramisu.value.Value` object.
160 It is on this object that we have to trigger the `reset`
161
162
163
164
165 Configuration's interesting methods
166 ------------------------------------------
167
168 A `Config` object is informed by an `option.OptionDescription`
169 instance. The attributes of the ``Config`` objects are the names of the
170 children of the ``OptionDescription``.
171
172 Here are the (useful) methods on ``Config`` (or `SubConfig`).
173
174 .. currentmodule:: tiramisu.config
175
176 .. class:: Config
177
178 .. autoclass:: SubConfig
179     :members: find, find_first, __iter__, iter_groups, iter_all, make_dict
180
181     .. automethod:: __init__
182
183     .. rubric:: Summary
184
185     .. autosummary::
186
187        find
188        find_first
189
190        __iter__
191        iter_groups
192        iter_all
193
194        make_dict
195
196     .. rubric:: Methods
197
198
199 A :class:`~config.CommonConfig` is a abstract base class. A
200 :class:`~config.SubConfig` is an just in time created objects that wraps an
201 ::class:`~option.OptionDescription`. A SubConfig differs from a Config in the
202 ::fact that a config is a root object and has an environnement, a context wich
203 ::defines the different properties, access rules, vs... There is generally only
204 ::one Config, and many SubConfigs.