rename FileOption to FilenameOption
[tiramisu.git] / doc / getting-started.txt
1 ==================================
2 Getting started
3 ==================================
4
5 What is options handling ?
6 =================================
7
8 Due to more and more available options required to set up an operating system, 
9 compiler options or whatever, it became quite annoying to hand the necessary 
10 options to where they are actually used and even more annoying to add new 
11 options. To circumvent these problems the configuration control was 
12 introduced...
13
14 What is Tiramisu ?
15 ===================
16
17 Tiramisu is an options handler and an options controller, which aims at
18 producing flexible and fast options access. The main advantages are its access
19 rules and the fact that the whole consistency is preserved at any time, see
20 :doc:`consistency`. There is of course type and structure validations, but also
21 validations towards the whole options. Furthermore, options can be reached and 
22 changed according to the access rules from nearly everywhere in your appliance.
23
24 Just the facts
25 ==============
26
27 .. _gettingtiramisu:
28
29 Download
30 ---------
31
32 To obtain a copy of the sources, check it out from the repository using `git`.
33 We suggest using `git` if one wants to access to the current developments.
34
35 ::
36
37     git clone git://git.labs.libre-entreprise.org/tiramisu.git
38
39 This will get you a fresh checkout of the code repository in a local directory
40 named ``tiramisu``.
41
42 Getting started
43 -------------------
44
45 Option objects can be created in different ways. Let's perform very basic
46 :class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
47 manipulations:
48
49 ::
50
51     >>> from tiramisu.config import Config
52     >>> from tiramisu.option import OptionDescription, BoolOption
53     >>> # let's create a group of options... with only one option inside
54     >>> descr = OptionDescription("optgroup", "", [
55     ...     BoolOption("bool", "", default=False)])
56     >>> # c is a namespace as well as a container for the options
57     >>> c = Config(descr)
58     >>> c.bool
59     False
60     >>> c.bool = True
61     >>> c.bool
62     True
63
64 So by now, we have:
65
66 - a namespace (which is `c` here)
67 - the access of an option's value by the
68   attribute access way (here `bool`, which is a boolean option 
69   :class:`~tiramisu.option.BoolOption()`.
70
71 So, option objects are produced at the entry point `c` and then handed down to 
72 where they are actually used when `c.bool` is triggered. This keeps options 
73 local but available at any timer and consistent.
74
75 Once the namespace is created, we can set a 
76 :meth:`~config.CommonConfig.read_write()` access to the options::
77
78     >>> c.read_write()
79
80 which enables us to set a bunch of access rules that we wil explain later in 
81 :doc:`status`.