tiramisu/doc/config.txt

.. default-role:: literal

===============================
Options handling basics
===============================

Tiramisu is made of almost three main objects :

- :class:`tiramisu.config.Config` witch is the whole configuration entry point
- :class:`tiramisu.option.Option` stands for the option types
- :class:`tiramisu.option.OptionDescription` is the shema, the option's structure

Accessing the `Option`'s
-------------------------

The `Config` object attribute access notation stands for the value of the
configuration's `Option`. That is, the `Config`'s object attribute is the name
of the `Option`, and the value is the value accessed by the `__getattr__`
attribute access mechanism.

If the attribute of the `Config` called by `__getattr__` has not been set before
(by the classic `__setattr__` mechanism), the default value of the `Option`
object is returned, and if no `Option` has been declared in the
`OptionDescription` (that is the schema of the configuration), an
`AttributeError` is raised.

::

    >>> gcdummy = BoolOption('dummy', 'dummy', default=False)
    >>> gcdummy._name
    'dummy'
    >>> gcdummy.getdefault()
    False
    >>> descr = OptionDescription('tiramisu', '', [gcdummy])
    >>> cfg = Config(descr)
    >>> cfg.dummy
    False
    >>> cfg.dummy = True
    >>> cfg.dummy
    True
    >>> cfg.idontexist
    AttributeError: 'OptionDescription' object has no attribute 'idontexist'

The `Option` objects (in this case the `BoolOption`), are organized into a tree
into nested `OptionDescription` objects. Every option has a name, as does every
option group. The parts of the full name of the option are separated by dots:
e.g. ``cfg.optgroup.optname``.

Let's make the protocol of accessing a config's attribute explicit
(because explicit is better than implicit):

1. If the option has not been declared, an `AttributeError` is raised,

2. If an option is declared, but neither a value nor a default value has
   been set, the returned value is `None`,

3. If an option is declared and a default value has been set, but no value
   has been set, the returned value is the default value of the option,

4. If an option is declared, and a value has been set, the returned value is
   the value of the option.

But there are special exceptions. We will see later on that an option can be a
:term:`mandatory option`. A mandatory option is an option that must have a defined value.
If no value have been set yet, the value is `None`.
When the option is called to retrieve a value, an exception is raised.

What if a value has been set and `None` is to be returned again ? Don't
worry, an option value can be "reseted" with the help of the `option.Option.reset()`
method.

If you know the path:

::

    >>> config.gc.dummy
    False

Setting the values of the options
----------------------------------------

An important part of the setting of the configuration consists of setting the
values of the configuration options. There are different ways of setting values,
the first one is of course the `__setattr__` method

::

    cfg.name = value

And if you wanna come back to a default value, use the builtin `del()` function::

    del(cfg.name)

.. module:: tiramisu.config

.. _`tree`:

The handling of options
~~~~~~~~~~~~~~~~~~~~~~~~~~

The handling of options is split into two parts: the description of
which options are available, what their possible values and defaults are
and how they are organized into a tree. A specific choice of options is
bundled into a configuration object which has a reference to its option
description (and therefore makes sure that the configuration values
adhere to the option description).


Common manipulations
------------------------

Let's perform some common manipulation on some options:

>>> from tiramisu.config import Config
>>> from tiramisu.option import UnicodeOption, OptionDescription
>>>
>>> var1 = UnicodeOption('var1', 'first variable')
>>> var2 = UnicodeOption('var2', '', u'value')
>>>
>>> od1 = OptionDescription('od1', 'first OD', [var1, var2])
>>> rootod = OptionDescription('rootod', '', [od1])

let's set somme access rules on the main namespace

>>> c = Config(rootod)
>>> c.read_write()

let's travel the namespaces

>>> print c
[od1]
>>> print c.od1
var1 = None
var2 = value
>>> print c.od1.var1
None
>>> print c.od1.var2
value

let's modify a value (careful to the value's type...)

>>> c.od1.var1 = 'value'
Traceback (most recent call last):
[...]
ValueError: invalid value value for option var1
>>> c.od1.var1 = u'value'
>>> print c.od1.var1
value
>>> c.od1.var2 = u'value2'
>>> print c.od1.var2
value2

let's come back to the default value

>>> del(c.od1.var2)
>>> print c.od1.var2
value

The value is saved in a :class:`~tiramisu.value.Value` object.
It is on this object that we have to trigger the `reset`




Configuration's interesting methods
------------------------------------------

A `Config` object is informed by an `option.OptionDescription`
instance. The attributes of the ``Config`` objects are the names of the
children of the ``OptionDescription``.

Here are the (useful) methods on ``Config`` (or `SubConfig`).

.. currentmodule:: tiramisu.config

.. class:: Config

.. autoclass:: SubConfig
    :members: find, find_first, __iter__, iter_groups, iter_all, make_dict

    .. automethod:: __init__

    .. rubric:: Summary

    .. autosummary::

       find
       find_first

       __iter__
       iter_groups
       iter_all

       make_dict

    .. rubric:: Methods


A :class:`~config.CommonConfig` is a abstract base class. A
:class:`~config.SubConfig` is an just in time created objects that wraps an
::class:`~option.OptionDescription`. A SubConfig differs from a Config in the
::fact that a config is a root object and has an environnement, a context wich
::defines the different properties, access rules, vs... There is generally only
::one Config, and many SubConfigs.