previous value api method
[tiramisu.git] / doc / optionapi.txt
1 .. default-role:: literal
2
3 Options API Details
4 =====================
5
6 :module: :api:`option.py`
7
8 .. _schema:
9
10 Description of Options
11 ----------------------
12
13 All the constructors take a ``name`` and a ``doc`` argument as first 
14 arguments to give the option or option group a name and to document it. 
15 Most constructors take a ``default`` argument that specifies the default 
16 value of the option. If this argument is not supplied the default value 
17 is assumed to be ``None``. 
18
19 Appart from that, the `Option` object is not supposed to contain any 
20 other value than the `tainted` attribute, which is explained later. The 
21 container of the value is in the `Config` object.
22
23 ``OptionDescription``
24 +++++++++++++++++++++
25
26 This class is used to group suboptions.
27
28     ``__init__(self, name, doc, children)``
29         ``children`` is a list of option descriptions (including
30         ``OptionDescription`` instances for nested namespaces).
31
32     ``set_group_type(self, group_name)``
33         Three available group_types : `default`, `family`, `group` and 
34         `master` (for master~slave group type). Notice that for a 
35         master~slave group, the name of the group and the name of the 
36         master option are identical.
37
38 `Options description` objects lives in the `_cfgimpl_descr` config attribute. 
39
40 If you need to access an option object, you can do it with the OptionDescription
41 object. Not only the value of the option by attribute access, but the option
42 object itself that lives behind the scene. It can always be accessed internally
43 with the `_cfgimpl_descr` attribute of the `config` objects. For example, with a
44 option named `name` in a `gc` group the `name` object can be accessed like
45 this::
46
47     conf._cfgimpl_descr.name
48     
49 of sub configs with ::
50
51     conf.gc._cfgimpl_descr.name
52
53 This is a binding. The option objects are in the `_children` config's attribute.
54
55 Why accessing an option object ? It is possible for example freeze the
56 configuration option 
57
58 ::
59
60     conf.gc._cfgimpl_descr.dummy.freeze()
61
62 or to hide it, or disable it, or... anything.
63
64 .. _optioninit:
65
66 generic option ``__init__`` method:
67
68     ``__init__(name, doc, default=None, requires=None, multi=False, mandatory=False)``
69
70     :``default``: specifies the default value of the option. 
71     :``requires``: is a list of names of options located anywhere in the configuration.
72     :``multi``: means the value can be a list.
73     :``mandatory``: see :ref:`glossary#mandatory`.
74
75 .. _optiontype:
76
77 ``BoolOption``
78 ++++++++++++++
79
80 Represents a choice between ``True`` and ``False``. 
81
82 ``IntOption``
83 +++++++++++++
84
85 Represents a choice of an integer.
86
87 ``FloatOption``
88 +++++++++++++++
89
90 Represents a choice of a floating point number.
91
92 ``StrOption``
93 +++++++++++++
94
95 Represents the choice of a string.
96
97 ``SymLinkOption``
98 ++++++++++++++++++
99
100 Redirects to another configuration option in the configuration, that is :
101
102 - retrieves the value of the tagert,
103 - can set the value of the target too.
104
105     ``__init__(self, name, path)``
106     
107         `path` is the path to the target, the option 
108
109 ``IPOption``
110 +++++++++++++
111
112 Represents the choice of an ip.
113
114 ``NetmaskOption``
115 +++++++++++++++++++
116
117 Represents the choice of a netmask.
118
119 ``ChoiceOption``
120 ++++++++++++++++
121
122 Represents a choice out of several objects. The option can also have the value
123 ``None``.
124
125     ``__init__(self, name, doc, values, default=None, requires=None)``
126         ``values`` is a list of values the option can possibly take.
127