tiramisu/doc/optionapi.txt

.. default-role:: literal

The `tiramisu.option.Option` options
======================================

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


.. _optdescr:

The `OptionDescription` class
-------------------------------

This class is used to group suboptions.

.. module:: tiramisu.option

.. autoclass: OptionDescription

    .. automethod:: __init__

    .. rubric:: Methods

    .. autosummary::

      ~Config.__init__
      ~Config.set_group_type

    .. automethod:: set_group_type

..


        ``__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.

The `Option` class
---------------------

It's an abstract base class for option wich are typed (int, string...)

.. _optioninit:

.. autoclass:: Option
    :special-members:
    :members:

generic option ``__init__`` method:

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

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