tiramisu/docs/config.rst

The :class:`Config`
====================

Tiramisu is made of almost three main classes/concepts :

- the :class:`Option` stands for the option types
- the :class:`OptionDescription` is the schema, the option's structure
- the :class:`Config` which is the whole configuration entry point

.. image:: config.png

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).

.. toctree::
    :maxdepth: 2

    option
    options
    symlinkoption
    own_option

Option description are nested Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :class:`Option` (in this case the :class:`BoolOption`),
are organized into a tree into nested
:class:`~tiramisu.option.OptionDescription` objects.

Every option has a name, as does every option group.

.. toctree::
    :maxdepth: 2

    optiondescription
    dynoptiondescription
    leadership


Config
~~~~~~

Let's perform a *Getting started* code review :

.. literalinclude:: src/getting_started.py
   :lines: 1-12
   :linenos:
   :name: GettingStarted

Let's review the code. First, line 7, we create an :class:`OptionDescription` named `optgroup`.

.. literalinclude:: src/getting_started.py
   :lines: 4, 6-7
   :emphasize-lines: 3

Option objects can be created in different ways, here we create a
:class:`BoolOption`

.. literalinclude:: src/getting_started.py
   :lines: 4, 8-9
   :emphasize-lines: 3

Then, line 12, we make a :class:`Config` with the :class:`OptionDescription` we
built :

.. literalinclude:: src/getting_started.py
   :lines: 3, 12
   :emphasize-lines: 2

Here is how to print our :class:`Config` details:

.. literalinclude:: src/getting_started.py
   :lines: 15

.. code-block:: bash

    Root config object that enables us to handle the configuration options
    
    Settings:
        forcepermissive      Access to option without verifying permissive properties
        unrestraint          Access to option without property restriction
        nowarnings           Do not warnings during validation
    
    Commands:
        cache                Manage config cache
        config               Actions to Config
        information          Manage config informations
        option               Select an option
        owner                Global owner
        permissive           Manage config permissives
        property             Manage config properties
        value                Manage config value

Then let's print our :class:`Option` details.

.. literalinclude:: src/getting_started.py
   :lines: 17

.. code-block:: bash

    Select an option
    
    Call: Select an option by path
    
    Commands:
        dict         Convert config and option to tiramisu format
        find         Find an or a list of options
        list         List options (by default list only option)
        name         get the name
        updates      Updates value with tiramisu format

Finaly, let's print the :class:`Config`.

.. literalinclude:: src/getting_started.py
   :lines: 19

.. code-block:: bash

    <tiramisu.api.Config object at 0x7f3ee6204278>

:download:`download the getting started code <src/getting_started.py>`

Go futher with `Option` and `Config`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. toctree::
    :maxdepth: 2

    property
    validator
    calculation