===========
The Log API
===========

When debugging a program, inserting `printf` statements is quite
common. This is also quite common to finally find the bugs, and remove
the prints. Unfortunately, bugs sometimes reappear and putting back
all prints can be tedious.

In order to avoid this enable/disable/... cycle, DSX offers a "level"
feature for printing APIs.  Desired `verbosity` level is then defined
on software generation, not in the sources.

The verbosity
=============

There are 3 ordered verbosity levels defined. They are inclusive
levels. Setting global verbosity level to:

* ``NONE`` implies only `print` statements marked ``NONE`` should be
  printed,

* ``TRACE`` implies only `print` statements marked ``TRACE`` or
  ``NONE`` should be printed,

* ``DEBUG`` implies only `print` statements marked ``TRACE``, ``NONE``
  or ``DEBUG`` should be printed.

Functions
=========

.. c:function:: void srl_log(verbosity, const char *msg)

   Conditionally prints a message.

   :type verbosity: `A verbosity level`_
   :param verbosity: The minimal required verbosity level needed for
                     the message to appear

   :param msg: Message to print

.. c:function:: void srl_log_printf(verbosity, const char *msg, ...)

   Conditionally prints a printf-formatted message.

   :type verbosity: `A verbosity level`_
   :param verbosity: The minimal required verbosity level needed for
                     the message to appear

   :param msg: Message format to print

   :param ...: printf-like positional arguments to ``msg``

.. c:function:: void srl_putc(const char chr)

   Unconditionally prints a character to some textual output
   backend. This is unsupported

   :param char chr: A character

Assertions
==========

.. c:macro:: srl_assert(expr)

   Ensures the passed expression evaluates to non-zero. If the
   assertion fails, make the program stop.

   :param expr: A valid C expression having a value.

.. _A verbosity level: `The verbosity`_