/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/configuration.txt

  • Committer: Vincent Ladeuil
  • Date: 2011-12-01 11:40:05 UTC
  • mto: This revision was merged to the branch mainline in revision 6347.
  • Revision ID: v.ladeuil+lp@free.fr-20111201114005-4ctbmk5nnzoqeh2b
Better tweaks (the value is not a property of the option).

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/configuration.txt
11
11
As a Bazaar developer there are three things you need to know about
12
12
configuration.
13
13
 
14
 
1: To get a value, you construct or get a reference to a ConfigStack
15
 
subclass that's relevant to the context where you want to look up a value.
16
 
For instance, given a branch::
 
14
1. Get a value.
 
15
 
 
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
 
18
branch::
17
19
 
18
20
  print branch.get_config_stack().get('log_format')
19
21
 
21
23
The value returned is of the type declared for that Option and if nothing
22
24
is specifically declared you will get the default for that option.
23
25
 
24
 
2: To add a new option, you add a new `Option` to the `option_registry`,
25
 
either inside ``bzrlib/config.py`` or during initialization of your
26
 
plugin.  New plugins should have systematic hierarchical names so that
27
 
related values are grouped together.  ::
 
26
2. Add a new option.
 
27
 
 
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
 
31
together::
28
32
 
29
33
  option_registry.register(
30
34
      Option('dirstate.fdatasync', default=True,
31
35
            from_unicode=bool_from_store,
32
36
            help="Flush dirstate changes onto physical disk? ...."))
33
37
 
34
 
3: There is (as of late 2011) some older and some newer configuration
35
 
code.  The old code has specific methods for various checks or uses
36
 
classes like `GlobalConfig`.  Don't add to to it; try to remove it.
 
38
 
 
39
3. Old and new configuration code.
 
40
 
 
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.
37
44
 
38
45
Option
39
46
------
43
50
* name: a name: a valid python identifier (even if it's not used as an
44
51
  identifier in python itself). This is also used to register the option.
45
52
 
46
 
* a value: a unicode string. By using ``from_unicode`` you can turn this
47
 
  string into a more appropriate representation (a list of unicode strings
48
 
  for example).
49
 
 
50
53
* from_unicode: a callable accepting a unicode string and returning a
51
54
  suitable value for the option. If the string cannot be coerced it should
52
55
  return None.
60
63
 
61
64
* help: a doc string describing the option, the first line should be a
62
65
  summary and can be followed by a blank line and a more detailed
63
 
  explanation. This will be displayed to the user with ``bzr help <option
64
 
  name>``.
 
66
  explanation. This will be displayed to the user with::
 
67
 
 
68
    bzr help <option name>
65
69
 
66
70
* invalid: the action to be taken when an invalid value is encountered in a
67
71
  store (during a Stack.get()).
68
72
 
 
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).
 
76
 
69
77
Sections
70
78
--------
71
79
 
151
159
Stacks
152
160
------
153
161
 
154
 
An option can take different values depending on the context it is used. Such
155
 
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,
156
164
default values in bzrlib and then some.
157
165
 
158
166
Such a context is implemented by creating a list of ``Section`` stacked upon