Configuration Files
===================

``nbtoolbelt`` can load options from a JSON configuration file:
see :ref:`configuration-file`.

Such a configuration file holds one object in JSON
(`JavaScript Object Notation <https://json.org/>`__),
with optional members for global options and options for each individual tool:

* ``nbtoolbelt``: global options that apply to multiple tools
* ``nbvalidate``: options for :doc:`nbvalidate`
* ``nbheads``: options for :doc:`nbhead`
* ``nbdump``: options for :doc:`nbdump`
* ``nbstats``: options for :doc:`nbstats`
* ``nbview``: options for :doc:`nbview`
* ``nbcat``: options for :doc:`nbcat`
* ``nbclean``: options for :doc:`nbclean`
* ``nbrun``: options for :doc:`nbrun`
* ``nbsplit``: options for :doc:`nbsplit`
* ``nbpunch``: options for :doc:`nbpunch`

The options for a tool are contained in a single object,
with a member per option.
The member name is the same as the long command-line option,
in which dashes ('``-``') have been replaced by underscores ('``_``').

Whenever a configuration file is loaded,

#. the common options from that file are applied (with attribute ``"nbtoolbelt"``),
#. those options are applied that concern the selected tool.

Thus, tool-specific options override common options in the same configuration file,
but not the other way round.

.. note:: **Note**

  * that JSON syntax is very strict;
  * that ``nbtb config [tool]`` will report the configuration using **Python syntax**;
  * that JSON *booleans* are spelled in **all lower case**: ``false`` and ``true``;
  * that JSON *strings* must be surrounded by **double quotes** (``"..."``).
  * that JSON does *not* allow trailing commas in arrays and objects;
  * that JSON does *not* support any form of *comments*.

Errors when loading a configuration file will be sent to ``stderr``,
and execution is aborted immediately.


Example
-------
Here is the :download:`embedded configuration file <nbtoolbelt.json>`:

.. literalinclude:: ../src/nbtoolbelt/data/nbtoolbelt.json
  :language: json

Here is an :download:`example configuration file <nbtoolbelt.json>`
with one global option (for verbose mode) and options for running and punching.
It can either be loaded through the command-line option ``--config nbtoolbelt.json``
or by putting it in your home directory as ``~/.nbtoolbelt.json``
(note the *dot*, which makes it a hidden file).

.. literalinclude:: nbtoolbelt.json
  :language: json