~bzr-pqm/bzr/bzr.dev

Configuring Bazaar

==================

A configuration option has:

* a name: a valid python identifier (even if it's not used as an

  identifier in python itself)

* a value: a unicode string or a list of unicode strings.

Option

------

The Option object is used to define its properties:

* name: a name: a valid python identifier (even if it's not used as an

  identifier in python itself). This is also used to register the option.

* default: the default value that Stack.get() should return if no

  value can be found for the option.

* default_from_env: a list of environment variables. The first variable set

  will provide a default value overriding 'default' which remains the

  default value if *no* environment variable is set.

* help: a doc string describing the option, the first line should be a

  summary and can be followed by a blank line and a more detailed

  explanation.

* from_unicode: a callable accepting a unicode string and returning a

  suitable value for the option. If the string cannot be coerced it should

  return None.

* invalid: the action to be taken when an invalid value is encountered in a

  store (during a Stack.get()).

Sections

--------

Options are grouped into sections which share some properties with the well

known dict objects:

* the key is the name,

* you can get, set and remove an option,

* the value is a unicode string.

MutableSection is needed to set or remove an option, ReadOnlySection should

be used otherwise.

Stores

------

Options can be persistent in which case they are saved into Stores.

``config.Store`` defines the abstract interface that all stores should

implement.

This object doesn't provide direct access to the options, it only provides

access to Sections. This is deliberate to ensure that sections can be

properly shared by reusing the same underlying objects. Accessing options

should be done via the ``Section`` objects.

A ``Store`` can contain one or more sections, each section is uniquely

identified by a unicode string.

``config.ConfigObjStore`` is an implementation that use ``ConfigObj``.

Depending on the object it is associated with (or not) a ``Store`` also needs

to implement a locking mechanism. ``LockableConfigObjStore`` implements such a

mechanism for ``ConfigObj`` based stores.

Classes are provided for the usual Bazaar configuration files and could be

used as examples to define new ones if needed. The associated tests provides a

basis for new classes which only need to register themselves in the right

places to inherit from the existing basic tests and add their own specific

ones.

Filtering sections

------------------

For some contexts, only some sections from a given store will apply. Defining

which is what the ``SectionMatcher`` objects are about.

The main constraint here is that a ``SectionMatcher`` should delay the loading

of the associated store as long as possible. The constructor should collect

all data needed for the selection and uses it while processing the sections in

``get_sections``.

Only ``ReadOnlySection`` objects are manipulated here but a

``SectionMatcher`` can return dedicated ``Section`` objects to provide

additional context (the ``LocationSection`` add an ``extra_path`` attribute

to implement the ``appendpath`` policy for example). If no sections match,

an empty list is returned.

Options local to a section can also be defined for special purposes and be

handled by ``Section.get()``. One such option is ``relpath`` which is

defined in ``LocationSection`` as an alternative to the ``appendpath``

policy.

For ``appendpath``, the ``LocationSection`` will carry ``extra_path`` as

``832013-expand-in-stack`` and ``relpath`` will be available as a

``Section`` local option with the same value. Note that such options can

only be expanded inside the section that defines them.

Specific section matchers can be implemented by overriding ``get_sections``

or just ``match``.

``bzrlib`` provides:

* ``LocationMatcher(store, location)``: To select all sections that match

  ``location``.

* ``NameMatcher(store, unique_id)``: To select a single section matching

  ``unique_id``.

Stacks

------

An option can take different values depending on the context it is used. Such

a context can involve configuration files, options from the command line,

default values in bzrlib and then some.

Such a context is implemented by creating a list of ``Section`` stacked upon

each other. A ``Stack`` can then be asked for an option value and returns the

first definition found.

This provides a great flexibility to decide priorities between sections when

the stack is defined without to worry about them in the code itself.

A stack also defines a mutable section (which can be None) to handle

modifications.

Many sections (or even stores) are aimed at providing default values for an

option but these sections shouldn't be modified lightly as modifying an option

used for different contexts will indeed be seen by all these contexts.

Default values in configuration files are defined by users. Developers

shouldn't have to modify them, as such, no mechanism nor heuristics are used

to find which section (or sections) should be modified.

A ``Stack`` defines a mutable section when there is no ambiguity.  If there

is one, then the *user* should be able to decide and in this case a new

``Stack`` can be created cheaply.

Different stacks can be created for different purposes, the existing

``GlobalStack``, ``LocationStack`` and ``BranchStack`` can be used as basis

or examples. These classes are the only ones that should be used in code,

``Stores`` can be used to build them but shouldn't be used otherwise, ditto

for sections. Again, the associated tests could and should be used against the

created stacks.