tiramisu/doc/optionapi.txt

.. default-role:: literal

Options API Details
=====================

:module: :api:`option.py`

.. _schema:

Description of Options
----------------------

All the constructors take a ``name`` and a ``doc`` argument as first 
arguments to give the option or option group a name and to document it. 
Most constructors take a ``default`` argument that specifies the default 
value of the option. If this argument is not supplied the default value 
is assumed to be ``None``. 

Appart from that, the `Option` object is not supposed to contain any 
other value than the `tainted` attribute, which is explained later. The 
container of the value is in the `Config` object.

``OptionDescription``
+++++++++++++++++++++

This class is used to group suboptions.

    ``__init__(self, name, doc, children)``
        ``children`` is a list of option descriptions (including
        ``OptionDescription`` instances for nested namespaces).

    ``set_group_type(self, group_name)``
        Three available group_types : `default`, `family`, `group` and 
        `master` (for master~slave group type). Notice that for a 
        master~slave group, the name of the group and the name of the 
        master option are identical.

`Options description` objects lives in the `_cfgimpl_descr` config attribute. 

If you need to access an option object, you can do it with the OptionDescription
object. Not only the value of the option by attribute access, but the option
object itself that lives behind the scene. It can always be accessed internally
with the `_cfgimpl_descr` attribute of the `config` objects. For example, with a
option named `name` in a `gc` group the `name` object can be accessed like
this::

    conf._cfgimpl_descr.name
    
of sub configs with ::

    conf.gc._cfgimpl_descr.name

This is a binding. The option objects are in the `_children` config's attribute.

Why accessing an option object ? It is possible for example freeze the
configuration option 

::

    conf.gc._cfgimpl_descr.dummy.freeze()

or to hide it, or disable it, or... anything.

.. _optioninit:

generic option ``__init__`` method:

    ``__init__(name, doc, default=None, requires=None, multi=False, mandatory=False)``

    :``default``: specifies the default value of the option. 
    :``requires``: is a list of names of options located anywhere in the configuration.
    :``multi``: means the value can be a list.
    :``mandatory``: see :ref:`glossary#mandatory`.

.. _optiontype:

``BoolOption``
++++++++++++++

Represents a choice between ``True`` and ``False``. 

``IntOption``
+++++++++++++

Represents a choice of an integer.

``FloatOption``
+++++++++++++++

Represents a choice of a floating point number.

``StrOption``
+++++++++++++

Represents the choice of a string.

``SymLinkOption``
++++++++++++++++++

Redirects to another configuration option in the configuration, that is :

- retrieves the value of the tagert,
- can set the value of the target too.

    ``__init__(self, name, path)``
    
        `path` is the path to the target, the option 

``IPOption``
+++++++++++++

Represents the choice of an ip.

``NetmaskOption``
+++++++++++++++++++

Represents the choice of a netmask.

``ChoiceOption``
++++++++++++++++

Represents a choice out of several objects. The option can also have the value
``None``.

    ``__init__(self, name, doc, values, default=None, requires=None)``
        ``values`` is a list of values the option can possibly take.