doc/macros.txt

   1 HEAD- Macros Overview; macros; concepts and parameters for macros
   2
   3 The NoBug interface is almost completely implemented using
   4 preprocessor macros. This is required because NoBug uses the
   5 +$$__FILE__$$+, +$$__LINE__$$+ and +$$__func__$$+ macros to
   6 log information on the current file, line number and function.
   7 Moreover, all the flat namespace uppercase identifiers make it easy
   8 to recognise the macros in source code.
   9 INDEX DISABLE_SHORTNAMES; DISABLE_SHORTNAMES; require NOBUG_ prefix everywhere
  10
  11 All macros are available without condition with a `NOBUG_...` prefix. Many
  12 macros (the common cases) are also available without this prefix as a
  13 convenience, however macros without this prefix must not have been previously
  14 defined. When `NOBUG_DISABLE_SHORTNAMES` is defined before including
  15 'nobug.h', then only the `NOBUG_` prefixed macros are available and the short
  16 forms will never be defined.
  17
  18 A set of macros are provided by NoBug that are postfixed by `..._IF`. These
  19 macros have the following form:
  20
  21   * `..._IF(when, ...)`
  22
  23 They perform the desired action only if `when` is true. For example:
  24
  25   * `REQUIRE_IF(foo != NULL, foo->something == constrained)`
  26
  27 The assertion will only be performed if `foo` is non `NULL`.
  28
  29 NoBug also contains a facility to pass the xref:NOBUGCONTEXT[source context]
  30 (file, line, function) around, this can be used to write functions which
  31 handle things where one is more interested in the context of the caller rather
  32 than the location where the macro appears.
  33
  34 These macros are postfixed with `..._CTX` and take an extra context
  35 parameter (usually at last but before the logging format specifier and
  36 any variable argument list). The context parameter must be of type
  37 `const struct nobug_context`.
  38
  39 When the `_CTX` context form is used together with the conditional `_IF`
  40 form then the suffix of the macros is always `..._IF_CTX`.
  41
  42 Macros that can accept a context have no short form and must always be
  43 prefixed with `NOBUG_...`.
  44