.. highlight:: ini

Config File Syntax
==================

Rattail config files follow the traditional `INI file`_ syntax, e.g. here is a
snippet::

   [rattail]
   app_title = Poser

.. _INI file: https://en.wikipedia.org/wiki/INI_file

That example can be broken down into 3 parts:

* section (the name in square brackets, "rattail")
* option (the name of the setting being defined, "app_title")
* value (the value for the setting, "Poser")

When logic within the app needs to retrieve a value from config, it does so by
requesting both the section and option by name, for example:

.. code-block:: python

   config.get('rattail', 'app_title')   # returns "Poser"

Under the hood we use Python's `configparser`_ module to parse config files.

.. _configparser: https://docs.python.org/3/library/configparser.html

If you think it would be handy for your app to have a new setting for some
reason, just create one and use it like so::

   [poser]
   foo = bar

.. code-block:: python

   config.get('poser', 'foo')   # returns "bar"

So far our examples have been for simple string values.  There is no way within
the standard INI file syntax, to define any data types other than string.
However the Rattail config parser/object can "coerce" values to a given type if
so requested, for example::

   [poser]
   foo_flag = true
   foo_number = 42
   foo_entries =
       first
       second
       third

.. code-block:: python

   config.getbool('poser', 'foo_flag')      # returns True
   config.getint('poser', 'foo_number')     # returns 42
   config.getlist('poser', 'foo_entries')   # returns ["first", "second", "third"]