tiramisu/doc/consistency.txt

.. default-role:: literal

.. currentmodule:: tiramisu

The global 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 :class:`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.

For example, an :class:`option.IntOption` validator waits for an `int` object of 
course, an :class:`option.StrOption` validator waits for an `str`, vs...

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()`

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.

.. currentmodule:: tiramisu.option

Other hooks are availables to validate upon a whole configuration at any time, 
for example the consistency between two options (typically, an 
:class:`IPOption` and a :class:`NetworkOption`).

Values that are calculated
--------------------------------

An option that have a callback is considered to have a value that is to be 
calculated. 

An option's property with a `force_store_value` attribute is considered to be 
modified at the first calculation.

.. automodule:: tiramisu.autolib
    :members: