11
As a Bazaar developer there are three things you need to know about
16
You construct or get a reference to a ConfigStack subclass that's relevant
17
to the context where you want to look up a value. For instance, given a
20
print branch.get_config_stack().get('log_format')
22
This will look up the stack through all relevant configuration sources.
23
The value returned is of the type declared for that Option and if nothing
24
is specifically declared you will get the default for that option.
28
You add a new ``Option`` to the ``option_registry``, either inside
29
``bzrlib/config.py`` or during initialization of your plugin. New plugins
30
should have systematic hierarchical names so that related values are grouped
33
option_registry.register(
34
Option('dirstate.fdatasync', default=True,
35
from_unicode=bool_from_store,
36
help="Flush dirstate changes onto physical disk? ...."))
39
3. Old and new configuration code.
41
There is (as of late 2011) some older and some newer configuration code. The
42
old code has specific methods for various checks or uses classes like
43
``GlobalConfig``. Don't add to to it; try to remove it.
4
A configuration option has:
6
* a name: a valid python identifier (even if it's not used as an
7
identifier in python itself)
9
* a value: a unicode string
50
16
* name: a name: a valid python identifier (even if it's not used as an
51
17
identifier in python itself). This is also used to register the option.
53
* from_unicode: a callable accepting a unicode string and returning a
54
suitable value for the option. If the string cannot be coerced it should
57
19
* default: the default value that Stack.get() should return if no
58
20
value can be found for the option.
60
* default_from_env: a list of environment variables. The first variable set
61
will provide a default value overriding 'default' which remains the
62
default value if *no* environment variable is set.
64
* help: a doc string describing the option, the first line should be a
65
summary and can be followed by a blank line and a more detailed
66
explanation. This will be displayed to the user with::
68
bzr help <option name>
70
* invalid: the action to be taken when an invalid value is encountered in a
71
store (during a Stack.get()).
73
The value of an option is a unicode string or ``None`` if it's not
74
defined. By using ``from_unicode`` you can turn this string into a more
75
appropriate representation (a list of unicode strings for example).
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.
120
67
------------------
122
69
For some contexts, only some sections from a given store will apply. Defining
123
which is what the ``SectionMatcher`` objects are about.
70
which is what the ``SectionMatcher`` are about.
125
72
The main constraint here is that a ``SectionMatcher`` should delay the loading
126
73
of the associated store as long as possible. The constructor should collect
127
74
all data needed for the selection and uses it while processing the sections in
130
Only ``ReadOnlySection`` objects are manipulated here but a
131
``SectionMatcher`` can return dedicated ``Section`` objects to provide
132
additional context (the ``LocationSection`` add an ``extra_path`` attribute
133
to implement the ``appendpath`` policy for example). If no sections match,
134
an empty list is returned.
136
Options local to a section can also be defined for special purposes and be
137
handled by ``Section.get()``. One such option is ``relpath`` which is
138
defined in ``LocationSection`` as an alternative to the ``appendpath``
141
For ``appendpath``, the ``LocationSection`` will carry ``extra_path`` as the
142
relative path between the section name and the location used. ``relpath``
143
will be available as a ``Section`` local option with the same
144
value. ``basename`` will carry the location base name and be available as a
145
local option with the same name. Note that such options can only be expanded
146
inside the section that defines them.
148
Specific section matchers can be implemented by overriding ``get_sections``
153
* ``LocationMatcher(store, location)``: To select all sections that match
156
* ``NameMatcher(store, unique_id)``: To select a single section matching
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).
82
.. FIXME: Replace the appendpath example if/when it's deprecated ;)
162
An option can take different values depending on the context it is
163
used. This can involve configuration files, options from the command line,
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,
164
89
default values in bzrlib and then some.
166
91
Such a context is implemented by creating a list of ``Section`` stacked upon
added
removed
doc/developers/configuration.txt
