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 or a list of unicode strings.
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.
16
50
* name: a name: a valid python identifier (even if it's not used as an
17
51
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
19
57
* default: the default value that Stack.get() should return if no
20
58
value can be found for the option.
26
64
* help: a doc string describing the option, the first line should be a
27
65
summary and can be followed by a blank line and a more detailed
66
explanation. This will be displayed to the user with::
30
* from_unicode: a callable accepting a unicode string and returning a
31
suitable value for the option. If the string cannot be coerced it should
68
bzr help <option name>
34
70
* invalid: the action to be taken when an invalid value is encountered in a
35
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).
122
An option can take different values depending on the context it is used. Such
123
a context can involve configuration files, options from the command line,
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,
124
164
default values in bzrlib and then some.
126
166
Such a context is implemented by creating a list of ``Section`` stacked upon
added
removed
doc/developers/configuration.txt
