doc/macros.txt

   1 Macros
   2 ------
   3 The NoBug interface is almost completely implemented using preprocessor macros.
   4 This is required because NoBug uses the `+++__FILE__+++` and `+++__LINE__+++`
   5 macros to log information on the current file and the current line
   6 number within that file. Moreover, all the flat namespace uppercase
   7 identifiers make it ease to recognise the macros in source code.
   8
   9 All macros are available without condition with the 'NOBUG' prefix. Macros are
  10 also available without the NOBUG prefix as a convenience, however macros
  11 without this prefix must not have been previously defined. All assertion and
  12 logging macros have a corresponding form postfixed by '_DBG'. Such macros will
  13 only be active within a debugger.
  14
  15 When `NOBUG_DISABLE_SHORTNAMES` is defined by the user, then only the `NOBUG_`
  16 prefixed macros are available and the short forms will never be defined.
  17
  18 A set of macros are provided by NoBug that are postfixed by `_IF`.
  19 These macros have the following form:
  20
  21   * `~WHATEVER~_IF(when, ...)`
  22
  23 They perform the desired action only if `when` is true. For
  24 example:
  25
  26   * `REQUIRE_IF(foo != NULL, foo->something == constrained)`
  27
  28 The assertion will only be performed if `foo` is non `NULL`.
  29
  30 Debugger versions are available using _IF_DBG postfixed to the name of the
  31 macro.
  32
  33 Parameters types
  34 ~~~~~~~~~~~~~~~~
  35 We use names for parameters which descripe their type. This names are
  36 orthogonal through all macro definitions.
  37
  38 [grid="all"]
  39 `---------`------------------------------------------------------------------
  40 `when`    Assertion is only performed if expression `when` is true at runtime
  41 `expr`    Test without side effects
  42 `fmt`     printf-like format string
  43 `...`     If not preceded by `fmt`, then printf-like format string followed by its arguments; otherwise, only its arguments
  44 `flag`    Flag to enable custom logging groups
  45 `type`    Data type to be checked as a single identifier name
  46 `pointer` Pointer to type
  47 `lvl`     Log level
  48 `depth`   Depth for invariants and dumps
  49 ---------------------------------------------------------------------------
  50