:mod:`config` -- board configuration
====================================

.. module:: config
	:synopsis: board configuration

.. note:: A global instance of the `Settings` class is instantiated in this module. When used by the custom code, this instance **must** be used. Do not create additional instances - can lead to undefined behavior and/or broken settings.

Import board settings like this::

	from config import settings

Classes
-------

.. class:: Settings()

	This class, while not being a direct descendant of the ``dict`` class, provides an interface as close to one as possible:

	Each board has a set of keys, no other keys should be added to the config. Each key has the following format: ``<category>-<i?>-<parameter>``. The value can be a string or an integer. If the value is an integer, the *category* and the *parameter* are separated by the ``-i-``. If the value is a string, *parameter* follows the *category*.

	For example, ``sys-lang`` (i.e. the *lang* parameter in the *sys* category), is the key for the value of type ``string``. ``net-i-dhcp`` (i.e. the *dhcp* parameter in the *net* category) is the key for the value of type ``int``.

	Boolean values are not supported. Instead, integer values (``0`` and ``1``) are used.

	.. method:: __getitem__(key)

		Returns the current value for the ``key``. Raises a ``KeyError`` if the key is not found (**NB**: older implementations do not throw an exception, but return ``None``)

	.. method:: __setitem__(key, value)

		Calls :meth:`~config.Settings.set()`

	.. method:: __contains__(key)

		Return ``True`` if the board config has the ``key``. No extra keys are allowed, the return value of this method for a given ``key`` is constant for the current version of the board firmware.

	.. method:: __delitem__(key):

		Removes the current value associated with the ``key``. The key itself is **not** removed (the key set is constant). The value is effectively reset to the factory default.

	.. method:: __str__():

		Returns the string, containg the dict-like representation of the object (ref :meth:`~config.Settings.dump()`).

	.. method:: get(key, default=None):

		Return the value for ``key`` if key is in the board config, else ``default``. If default is not given, it defaults to ``None``, so that this method never raises a ``KeyError``.

	.. method:: set(key, value):

		Sets the value for the given ``key``. The key must be valid (i.e. ``key in settings`` **must** be ``True``). The code will try to convert the ``value`` to the type, required by the key.

		No exception is raised, if something goes wrong, the new value is silently ignored.

	.. method:: commit(grp=None):

		If one or more values have been changed, the changes are committed to the underlying storage at an arbitrary moment. Call this method to force dumping all the changes (ex. before a system reset).

		If ``grp`` is not None, only the values for the keys in the category ``grp`` will be saved.

	.. method:: backup(output)

		Save the current configuration as a JSON file named ``output``.

	.. method:: restore(input)

		Restore the previously saved configuration (ref :meth:`config.Settings.backup()`)

	.. method:: dump()

		Returns the current configuration as a ``dict``.

	.. method:: parse(cfg, grp=None)

		For each key in the ``cfg`` dictionary, checks whether this key belongs to the board config, then checks if the key's category equals ``grp`` (if ``grp`` is not None). If the key passes all checks, the corresponding value of the board config is updated.

	.. method:: reset(group=None)

		Resets all values to the factory defaults (if ``group`` is not None, resets only the values for the keys in the ``group`` category)

	.. method:: correct(grp=None)

		Performs some checks and corrects the inappropriate values. If ``grp`` is not None, only the ``grp`` category is checked.