.. _alpreferences:

ALPreferences
==============

.. toctree::
   :hidden:
   :maxdepth: 1

   alpreferences-api

Overview | :ref:`API <alpreferences-api>`

What it does
------------

ALPreferences allows access to xml preference files and provides convertion to and from ALValues.

How it works
------------

A preference as an ALValue array is defined as follows:

- **[0]**: Name of the preference
- **[1]**: Description of the preference
- **[2]**: The value of the preference (can contain other preferences if it is of type array)
- **[3]**: (optional) The name of the data when inserted into memory

A typical preference xml file looks like this:

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8" ?>
   <ModulePreference
     name="aldebaran-robotics.com@ModuleName"
     xmlns="http://www.aldebaran-robotics.com/ns/ALPreference"
     schemaLocation="ModulePreference.xsd">
   
     <Preference name="key1" description="a string" value="value" type="string" />
     <Preference name="key2" description="an int" value="1" type="int" />
     <Preference name="key3" description="a bool" value="true" type="bool" />
     <Preference name="key4" description="a float" value="1.0" type="float" />
     <!-- ... more preferences ... -->
   
     <Preference name="key5" description="a multi-level preference" type="array">
       <Preference name="key6" description="inner preference" value="value" type="string" />
       <!-- ... more preferences ... -->
     </Preference>
   </ModulePreference>

On NAO, preferences are typically stored in one of these paths:

- ``/home/nao/.config/naoqi/``
- ``/etc/naoqi/``

These conform to the general patterns:

- Home config: ``~/.config/<applicationName>/<filename>``
- SDK config: ``<sdk_prefix>/etc/<applicationName>/<filename>``
- System config: ``/etc/<applicationName>/<filename>``