tiramisu/doc/consistency.txt

.. default-role:: literal

The global configuration's consistency
========================================

Identical option names
----------------------

If an `option.Option()` happens to be defined twice in the
`glossary#schema` (e.g. the `option.OptionDescription()`),
that is the two options actually have the same name, an exception is raised.

The calculation is currently carried out in the samespace, for example
if `config.gc.name` is defined, another option in `gc` with the name
`name` is **not** allowed, whereas `config.whateverelse.name` is still
allowed.

Option's values type validation
--------------------------------

When a value is set to the option, the value is validated by the
option's `option.Option()` validator's type.

Notice that if the option is `multi`, that is the `multi` attribute is set to
`True`, then the validation of the option value accepts a list of values
of the same type.

Requirements
------------

Configuration options can specify requirements as parameters at the init
time, the specification of some links between options or groups allows
to carry out a dependencies calculation. For example, an option can ben
hidden if another option has been set with some expected value. This is
just an example, because the possibilities are hudge.

A requirement is specified using a list of triplets. The first element
of the triplet gives the path of the option that is required, the second
element is the value wich is expected to trigger the callback, and the
third one is the callback's action name (`hide`, `show`...)::

    stroption = StrOption('str', 'Test string option', default="abc",
                          requires=[('int', 1, 'hide')])

Take a look at an example here
`test_option_consistency.test_hidden_if_in()`

Config updates
---------------

New configuration options and groups can be dynamically added.

The configuration has to be *updated* after that the description has been
passed to the Config objet, see:

::

    >>> config = Config(descr)
    >>> newoption = BoolOption('newoption', 'dummy twoo', default=False)
    >>> descr.add_child(newoption)
    >>> config.update()
    >>> config.newoption
    False

in

- `test_option_consistency.test_newoption_add_in_descr()`
- `test_option_consistency.test_newoption_add_in_subdescr()`
- `test_option_consistency.test_newoption_add_in_config()`

Validation upon a whole configuration object
----------------------------------------------

An option's integrity can be validated towards a whole configuration.

This type of validation is very open. Let's take a use case : an option
has a certain value, and the value of this option can change the owner
of another option or option group... Everything is possible.

For example, the configuration paths have to be unique in the
`glossary#schema`, the validation is carried out at the
`config.Config._cfgimpl_build()` time in the
`config.Config._validate_duplicates()` method.

Other hook are availables to validate upon a whole configuration at any
time.