.. Copyright (C) ALbert Mietus, SoftwareBeterMaken.nl; 2016. Part of Pathways project -*- coding: utf-8 -*-

pathways config files (5)
=========================

Pathways uses multiple ‘ExtendedInterpolation’ ini-files for almost all configuration; the command-line configuration is
an apprehend exception. Typically those files use the `.cfg` extension (not ‘ini’). When its basename is equal to the
(basename of the) :term:`ATSfile`, it is automatically read and used.

Like other ini-files, pathways cfg-files are sectioned and typical start with a ``[DEFAULT]`` section. Lines
starting with an hash (``#``) are comments and are ignored. 

Configurations are stored as a ``key=value`` format. Both *key* and *value* may contain spaces. However, spaces in keys are not
recommended! Spaces around the ‘=’-sign are ignored. Also other leading and trailing whitespace is skipped.

Although the ‘key’ is case-insensitive, configuration-keys are typically in all-lowercase. Auxiliary keys use mixed- or
upper-case. Auxiliary keys are used build values, by interpolation (or expanding) them with ``${AuxValue}`` in another
value.

Config files
------------

Typically, the configuration is combined from several locations.

* When the option ``--config <FILE>`` is used, only that file is used and all other locations are ignored.

1. A user/global configuration-file called **pathways.cfg**.

   Typically found in the users *HOME* directory, or the directory set by the environment :envvar:`PATHWAYS_CONF_DIR`,
   or runner-specific configuration.

2. The shared configuration-files called **config.cfg**. This can be found in several places:

   a) the working directory (where the tests are started), or
   b) the directory where the :term:`ATS`\es are located, typically also called :file:`ATS/`.

   .. note:: currently only 1 file is used: (b) when an ATS is specific, else (a).

   .. todo:: Fix this

3. The ATS specific file :samp:`{basename}.cfg`, in the same directory as the :term:`ATSfile`




Well known configuration-keys
-----------------------------

log
  Threshold for logging. This can be a number between **0** and **50**, or one of the standard names. The lower the number, the more is logged.

  * CRITICAL (=50)
  * ERROR
  * WARNING
  * INFO
  * DEBUG (=10)

gate
   .. todo:: Redesign the old 3-part gate and document it.

put
  An URI-style adress of the :term:`PUT`: which product is to be tested. The exact interpretation of the value depends
  on the :term:`gate`

.. todo::   extent the list

Custom config-keys
------------------

.. todo::