=====================
Config file reference
=====================

By default the config file is searched in the current directory using the following regular expressions:

* ``^\.?(config|conf)[-\._]?freeports\.ya?ml$``
* ``^\.?freeports[-\._]?(config|conf)\.ya?ml$``

.. tip::
    Our preferred way of calling the config file are:

    * config.freeports.yaml
    * freeports.conf.yaml
    * freeports-config.yaml

If not present it fallback conforming to `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/>`_ (usually to ``~/.config``)
and search for a ``freeports.yaml`` or ``freeports.yml`` file. 
If no configuration is found last attempt is to *system wise* configuration file (``/etc/freeports.yaml`` or ``/etc/freeport.yml``).

.. note::
    
    In ``Windows`` systems the check on `XDG base directories` is substitute with 
    ``%LOCALAPPDATA%`` (fallback to ``~\\AppData\\Local``) or ``%PROGRAMDATA%`` (fallback to ``C:\\ProgramData``).
    The check to system wise configuration is done on ``%SystemRoot%`` (fallback to ``C:\\Windows``).


The map between command line config file variables and options is:

+----------------------+----------------------+-------------------------+
| Environment variable | Corresponding option | Type                    |
+======================+======================+=========================+
| ``verbosity``        | ``VERBOSITY``        | ``int``                 |
+----------------------+----------------------+-------------------------+
| ``batch_path``       | ``BATCH``            | ``Path``                |
+----------------------+----------------------+-------------------------+
| ``n_workers``        | ``BATCH_WORKERS``    | ``int``                 |
+----------------------+----------------------+-------------------------+
| ``out_path``         | ``OUT_CSV``          | ``Path``                |
+----------------------+----------------------+-------------------------+
| ``save_pdf``         | ``SAVE_PDF``         | ``bool``                |
+----------------------+----------------------+-------------------------+
| ``url``              | ``URL``              | ``str``                 |
+----------------------+----------------------+-------------------------+
| ``pdf``              | ``PDF``              | ``Path``                |
+----------------------+----------------------+-------------------------+
| ``format``           | ``FORMAT``           | :py:class:`PdfFormats` |
+----------------------+----------------------+-------------------------+





