Logging
===========

Yimmo logging API.

.. warning::

   The log API and format are more tailored to libyimmo development than
   they are to development of projects which *use* libyimmo. Tidying this
   up is on the TODO list.




.. c:type:: ymo_log_level_t

   Yimmo log levels.
   
   :YMO_LOG_FATAL: An event has occurred which is considered unrecoverable.
   :YMO_LOG_ERROR: An event has occurred which limits or prevents normal
       operation for at least one connection.
   :YMO_LOG_WARNING: An error may occur if no corrective action is taken.
   :YMO_LOG_NOTICE: An anomlous or noteworthy event has taken place.
   :YMO_LOG_INFO: General non-error, user information.
   :YMO_LOG_DEBUG: General non-error, developer information.
   :YMO_LOG_TRACE: This is a log level intended almost exclusively for yimmo development.
       It provides fine-grained logging on most of the internal functions,
       including parsing operations and object creation/destruction.


   .. code-block:: c
      :caption: Definition
   
      typedef enum ymo_log_level {
          /** An event has occurred which is considered unrecoverable. */
          YMO_LOG_FATAL,
          /** An event has occurred which limits or prevents normal
           *  operation for at least one connection. */
          YMO_LOG_ERROR,
          /** An error may occur if no corrective action is taken. */
          YMO_LOG_WARNING,
          YMO_LOG_NOTICE, /* An anomlous or noteworthy event has taken place. */
          YMO_LOG_INFO,   /* General non-error, no-developer information. */
          YMO_LOG_DEBUG,  /* General non-error, developer information. */
          /** This is a log level intended almost exclusively for yimmo development.
           *  It provides fine-grained logging on most of the internal functions,
           *  including parsing operations and object creation/destruction. */
          YMO_LOG_TRACE,
      } ymo_log_level_t;


.. c:function:: void ymo_log_init(void)

   Initialize the logger (atm, just sets the level from the env var,
   ``YIMMO_LOG_LEVEL``).
   



.. c:function:: void ymo_log(ymo_log_level_t level, const char* fmt, ...);

   Log function
   
   :param level: the log level of the current message
   :param fmt: printf-style format string for subsequent variadic args



.. c:function:: void ymo_log_msg(ymo_log_level_t level, const char* msg)

   Log function
   
   :param level: the log level of the current message
   :param msg: puts-style log message



.. c:function:: ymo_log_level_t ymo_log_get_level(void)

   Get the current log-level.
   
   :returns: the current log level



.. c:function:: const char* ymo_log_get_level_name(ymo_log_level_t level)

   Get the name for a given log level.
   
   :param level: the level whose name we want
   :returns: the level name in string form



.. c:function:: ymo_log_level_t ymo_log_set_level(ymo_log_level_t level)

   Set the current log-level.
   
   :param level: the level at which the logger should omit messages
   :returns: the current log level



.. c:function:: ymo_log_level_t ymo_log_set_level_by_name(const char* level_name)

   Set the current log-level by name, e.g. ymo_log_set_level_by_name("TRACE")
   
   :param level: the level at which the logger should omit messages
   :returns: the current log level



Compile time log-level max. 



.. c:macro:: ymo_log_fatal

   Compile-time FATAL log function/convenience macro 


   .. code-block:: c
      :caption: Definition
   
      #define ymo_log_fatal(...) \
              ymo_log(YMO_LOG_FATAL, __VA_ARGS__)


.. c:macro:: ymo_log_error

   Compile-time ERROR log function/convenience macro 


   .. code-block:: c
      :caption: Definition
   
      #define ymo_log_error(...) \
              ymo_log(YMO_LOG_ERROR, __VA_ARGS__)


.. c:macro:: ymo_log_warning

   Compile-time WARNING log function/convenience macro 


   .. code-block:: c
      :caption: Definition
   
      #define ymo_log_warning(...) \
              ymo_log(YMO_LOG_WARNING, __VA_ARGS__)


.. c:macro:: ymo_log_notice

   Compile-time NOTICE log function/convenience macro 


   .. code-block:: c
      :caption: Definition
   
      #define ymo_log_notice(...) \
              ymo_log(YMO_LOG_NOTICE, __VA_ARGS__)


.. c:macro:: ymo_log_info

   Compile-time INFO log function/convenience macro 


   .. code-block:: c
      :caption: Definition
   
      #define ymo_log_info(...) \
              ymo_log(YMO_LOG_INFO, __VA_ARGS__)


.. c:macro:: ymo_log_debug

   Compile-time DEBUG log function/convenience macro 


   .. code-block:: c
      :caption: Definition
   
      #define ymo_log_debug(fmt, ...) \
              ymo_log(YMO_LOG_DEBUG, "%s:%i: "fmt, __func__, __LINE__, __VA_ARGS__)


.. c:macro:: ymo_log_trace

   Compile-time TRACE log function/convenience macro 


   .. code-block:: c
      :caption: Definition
   
      #define ymo_log_trace(fmt, ...) \
              ymo_log(YMO_LOG_TRACE, "%s:%s:%i: "fmt, YMO_SOURCE, __func__, __LINE__, __VA_ARGS__)