2547923fd4fd3b58b3778afaf7103b9d61d7b060
[tiramisu.git] / doc / config.txt
1 .. default-role:: literal
2
3 ===============================
4 Configuration 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 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 But there are special exceptions. We will see later on that an option can be a 
65 :term:`mandatory option`. A mandatory option is an option that must have a defined value. 
66 If no value have been set yet, the value is `None`. 
67 When the option is called to retrieve a value, an exception is raised. 
68
69 What if a value has been set and `None` is to be returned again ? Don't
70 worry, an option value can be "reseted" with the help of the `option.Option.reset()`
71 method.
72
73 If you know the path:
74
75 ::
76
77     >>> config.gc.dummy
78     False
79
80 Setting the values of the options
81 ----------------------------------------
82
83 An important part of the setting of the configuration consists of setting the
84 values of the configuration options. There are different ways of setting values,
85 the first one is of course the `__setattr__` method
86
87 ::
88
89     cfg.name = value
90
91 And if you wanna come back to a default value, use the builtin `del()` function::
92
93     del(cfg.name)
94
95 .. module:: tiramisu.config
96
97 The handling of options is split into two parts: the description of
98 which options are available, what their possible values and defaults are
99 and how they are organized into a tree. A specific choice of options is
100 bundled into a configuration object which has a reference to its option
101 description (and therefore makes sure that the configuration values
102 adhere to the option description).
103
104 Configuration's interesting methods
105 ------------------------------------------
106
107 A `Config` object is informed by an `option.OptionDescription`
108 instance. The attributes of the ``Config`` objects are the names of the
109 children of the ``OptionDescription``.
110
111 Here are the (useful) methods on ``Config`` (or `SubConfig`).
112
113 .. currentmodule:: tiramisu.config
114
115 .. class:: Config
116
117 .. autoclass:: SubConfig
118     :members: find, find_first, __iter__, iter_groups, iter_all, make_dict
119
120     .. automethod:: __init__
121     
122     .. rubric:: Summary
123
124     .. autosummary::
125  
126        find
127        find_first
128
129        __iter__
130        iter_groups
131        iter_all
132
133        make_dict
134
135     .. rubric:: Methods
136
137  
138 A :class:`~config.CommonConfig` is a abstract base class. A 
139 :class:`~config.SubConfig` is an just in time created objects that wraps an 
140 ::class:`~option.OptionDescription`. A SubConfig differs from a Config in the 
141 ::fact that a config is a root object and has an environnement, a context wich 
142 ::defines the different properties, access rules, vs... There is generally only 
143 ::one Config, and many SubConfigs.