← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/configuration.txt

  • Committer: Robert Collins
  • Date: 2006-04-26 08:21:09 UTC
  • mto: (1686.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 1687.
  • Revision ID: robertc@robertcollins.net-20060426082109-4dcd5b716ac322a1
Add a special cased weaves to knit converter.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/configuration.txt
1
 
Configuring Bazaar
2
 
==================
3
 
 
4
 
A configuration option has:
5
 
 
6
 
* a name: a valid python identifier (even if it's not used as an
7
 
  identifier in python itself)
8
 
 
9
 
* a value: a unicode string
10
 
 
11
 
Option
12
 
------
13
 
 
14
 
The Option object is used to define its properties:
15
 
 
16
 
* name: a name: a valid python identifier (even if it's not used as an
17
 
  identifier in python itself). This is also used to register the option.
18
 
 
19
 
* default: the default value that Stack.get() should return if no
20
 
  value can be found for the option.
21
 
 
22
 
Since plugins should be able to lazily register options, the associated help
23
 
is not part of the object but provided at registration time.
24
 
 
25
 
Sections
26
 
--------
27
 
 
28
 
Options are grouped into sections which share some properties with the well
29
 
known dict objects:
30
 
 
31
 
* the key is the name,
32
 
* you can get, set and remove an option,
33
 
* the value is a unicode string.
34
 
 
35
 
MutableSection is needed to set or remove an option, ReadOnlySection should
36
 
be used otherwise.
37
 
 
38
 
Stores
39
 
------
40
 
 
41
 
Options can be persistent in which case they are saved into Stores.
42
 
 
43
 
``config.Store`` defines the abstract interface that all stores should
44
 
implement.
45
 
 
46
 
This object doesn't provide direct access to the options, it only provides
47
 
access to Sections. This is deliberate to ensure that sections can be
48
 
properly shared by reusing the same underlying objects. Accessing options
49
 
should be done via the ``Section`` objects.
50
 
 
51
 
A ``Store`` can contain one or more sections, each section is uniquely
52
 
identified by a unicode string.
53
 
 
54
 
``config.ConfigObjStore`` is an implementation that use ``ConfigObj``.
55
 
 
56
 
Depending on the object it is associated with (or not) a ``Store`` also needs
57
 
to implement a locking mechanism. ``LockableConfigObjStore`` implements such a
58
 
mechanism for ``ConfigObj`` based stores.
59
 
 
60
 
Classes are provided for the usual Bazaar configuration files and could be
61
 
used as examples to define new ones if needed. The associated tests provides a
62
 
basis for new classes which only need to register themselves in the right
63
 
places to inherit from the existing basic tests and add their own specific
64
 
ones.
65
 
 
66
 
Filtering sections
67
 
------------------
68
 
 
69
 
For some contexts, only some sections from a given store will apply. Defining
70
 
which is what the ``SectionMatcher`` are about.
71
 
 
72
 
The main constraint here is that a ``SectionMatcher`` should delay the loading
73
 
of the associated store as long as possible. The constructor should collect
74
 
all data needed for the selection and uses it while processing the sections in
75
 
``get_sections``.
76
 
 
77
 
Only ``ReadOnlySection`` objects are manipulated here but a ``SectionMatcher``
78
 
can return dedicated ``Section`` to provide additional context (the
79
 
``LocationSection`` add an ``extra_path`` attribute to implement the
80
 
``appendpath`` policy for example).
81
 
 
82
 
.. FIXME: Replace the appendpath example if/when it's deprecated ;)
83
 
 
84
 
Stacks
85
 
------
86
 
 
87
 
An option can take different values depending on the context it is used. Such
88
 
a context can involve configuration files, options from the command line,
89
 
default values in bzrlib and then some.
90
 
 
91
 
Such a context is implemented by creating a list of ``Section`` stacked upon
92
 
each other. A ``Stack`` can then be asked for an option value and returns the
93
 
first definition found.
94
 
 
95
 
This provides a great flexibility to decide priorities between sections when
96
 
the stack is defined without to worry about them in the code itself.
97
 
 
98
 
A stack also defines a mutable section (which can be None) to handle
99
 
modifications.
100
 
 
101
 
Many sections (or even stores) are aimed at providing default values for an
102
 
option but these sections shouldn't be modified lightly as modifying an option
103
 
used for different contexts will indeed be seen by all these contexts.
104
 
 
105
 
Default values in configuration files are defined by users. Developers
106
 
shouldn't have to modify them, as such, no mechanism nor heuristics are used
107
 
to find which section (or sections) should be modified.
108
 
 
109
 
A ``Stack`` defines a mutable section when there is no ambiguity.  If there
110
 
is one, then the *user* should be able to decide and in this case a new
111
 
``Stack`` can be created cheaply.
112
 
 
113
 
Different stacks can be created for different purposes, the existing
114
 
``GlobalStack``, ``LocationStack`` and ``BranchStack`` can be used as basis
115
 
or examples. These classes are the only ones that should be used in code,
116
 
``Stores`` can be used to build them but shouldn't be used otherwise, ditto
117
 
for sections. Again, the associated tests could and should be used against the
118
 
created stacks.