doc/macros.txt

   1 HEAD- 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 ease
   8 to recognise the macros in source code.
   9
  10 All macros are available without condition with a `NOBUG_...` prefix.
  11 Many macros (the common cases) are also available without this prefix
  12 as a convenience, however macros without this prefix must not have
  13 been previously defined. When `NOBUG_DISABLE_SHORTNAMES` is defined
  14 before including 'nobug.h', then only the `NOBUG_` prefixed macros
  15 are available and the short forms will never be defined.
  16
  17 A set of macros are provided by NoBug that are postfixed by `..._IF`.
  18 These macros have the following form:
  19
  20   * `..._IF(when, ...)`
  21
  22 They perform the desired action only if `when` is true. For example:
  23
  24   * `REQUIRE_IF(foo != NULL, foo->something == constrained)`
  25
  26 The assertion will only be performed if `foo` is non `NULL`.
  27
  28 NoBug also also contains a facility to pass the source context (file,
  29 line, function) around, this can be used to write functions which
  30 handle things where one is more interested in the context of the caller
  31 than the location where the macros appears.
  32
  33 This macros are postfixed with `..._CTX` and take an extra context
  34 parameter (usually at last but before the logging format specifier and
  35 any variable argument list). The context parameter must be of type
  36 `const struct nobug_context`.
  37
  38 When the `_CTX` context form is used together with the conditional `_IF`
  39 form then the suffix of the macros is always `..._IF_CTX`.
  40
  41 The macros which take a context have no short form and must always be
  42 prefixed with `NOBUG_...`.
  43