lib/debug.nix

   1 /* Collection of functions useful for debugging
   2    broken nix expressions.
   3
   4    * `trace`-like functions take two values, print
   5      the first to stderr and return the second.
   6    * `traceVal`-like functions take one argument
   7      which both printed and returned.
   8    * `traceSeq`-like functions fully evaluate their
   9      traced value before printing (not just to “weak
  10      head normal form” like trace does by default).
  11    * Functions that end in `-Fn` take an additional
  12      function as their first argument, which is applied
  13      to the traced value before it is printed.
  14 */
  15 { lib }:
  16 let
  17   inherit (lib)
  18     isList
  19     isAttrs
  20     substring
  21     attrValues
  22     concatLists
  23     const
  24     elem
  25     generators
  26     id
  27     mapAttrs
  28     trace;
  29 in
  30
  31 rec {
  32
  33   # -- TRACING --
  34
  35   /* Conditionally trace the supplied message, based on a predicate.
  36
  37      Type: traceIf :: bool -> string -> a -> a
  38
  39      Example:
  40        traceIf true "hello" 3
  41        trace: hello
  42        => 3
  43   */
  44   traceIf =
  45     # Predicate to check
  46     pred:
  47     # Message that should be traced
  48     msg:
  49     # Value to return
  50     x: if pred then trace msg x else x;
  51
  52   /* Trace the supplied value after applying a function to it, and
  53      return the original value.
  54
  55      Type: traceValFn :: (a -> b) -> a -> a
  56
  57      Example:
  58        traceValFn (v: "mystring ${v}") "foo"
  59        trace: mystring foo
  60        => "foo"
  61   */
  62   traceValFn =
  63     # Function to apply
  64     f:
  65     # Value to trace and return
  66     x: trace (f x) x;
  67
  68   /* Trace the supplied value and return it.
  69
  70      Type: traceVal :: a -> a
  71
  72      Example:
  73        traceVal 42
  74        # trace: 42
  75        => 42
  76   */
  77   traceVal = traceValFn id;
  78
  79   /* `builtins.trace`, but the value is `builtins.deepSeq`ed first.
  80
  81      Type: traceSeq :: a -> b -> b
  82
  83      Example:
  84        trace { a.b.c = 3; } null
  85        trace: { a = <CODE>; }
  86        => null
  87        traceSeq { a.b.c = 3; } null
  88        trace: { a = { b = { c = 3; }; }; }
  89        => null
  90   */
  91   traceSeq =
  92     # The value to trace
  93     x:
  94     # The value to return
  95     y: trace (builtins.deepSeq x x) y;
  96
  97   /* Like `traceSeq`, but only evaluate down to depth n.
  98      This is very useful because lots of `traceSeq` usages
  99      lead to an infinite recursion.
 100
 101      Example:
 102        traceSeqN 2 { a.b.c = 3; } null
 103        trace: { a = { b = {…}; }; }
 104        => null
 105
 106      Type: traceSeqN :: Int -> a -> b -> b
 107    */
 108   traceSeqN = depth: x: y:
 109     let snip = v: if      isList  v then noQuotes "[…]" v
 110                   else if isAttrs v then noQuotes "{…}" v
 111                   else v;
 112         noQuotes = str: v: { __pretty = const str; val = v; };
 113         modify = n: fn: v: if (n == 0) then fn v
 114                       else if isList  v then map (modify (n - 1) fn) v
 115                       else if isAttrs v then mapAttrs
 116                         (const (modify (n - 1) fn)) v
 117                       else v;
 118     in trace (generators.toPretty { allowPrettyValues = true; }
 119                (modify depth snip x)) y;
 120
 121   /* A combination of `traceVal` and `traceSeq` that applies a
 122      provided function to the value to be traced after `deepSeq`ing
 123      it.
 124   */
 125   traceValSeqFn =
 126     # Function to apply
 127     f:
 128     # Value to trace
 129     v: traceValFn f (builtins.deepSeq v v);
 130
 131   /* A combination of `traceVal` and `traceSeq`. */
 132   traceValSeq = traceValSeqFn id;
 133
 134   /* A combination of `traceVal` and `traceSeqN` that applies a
 135   provided function to the value to be traced. */
 136   traceValSeqNFn =
 137     # Function to apply
 138     f:
 139     depth:
 140     # Value to trace
 141     v: traceSeqN depth (f v) v;
 142
 143   /* A combination of `traceVal` and `traceSeqN`. */
 144   traceValSeqN = traceValSeqNFn id;
 145
 146   /* Trace the input and output of a function `f` named `name`,
 147   both down to `depth`.
 148
 149   This is useful for adding around a function call,
 150   to see the before/after of values as they are transformed.
 151
 152      Example:
 153        traceFnSeqN 2 "id" (x: x) { a.b.c = 3; }
 154        trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; }
 155        => { a.b.c = 3; }
 156   */
 157   traceFnSeqN = depth: name: f: v:
 158     let res = f v;
 159     in lib.traceSeqN
 160         (depth + 1)
 161         {
 162           fn = name;
 163           from = v;
 164           to = res;
 165         }
 166         res;
 167
 168
 169   # -- TESTING --
 170
 171   /* Evaluates a set of tests.
 172
 173      A test is an attribute set `{expr, expected}`,
 174      denoting an expression and its expected result.
 175
 176      The result is a `list` of __failed tests__, each represented as
 177      `{name, expected, result}`,
 178
 179      - expected
 180        - What was passed as `expected`
 181      - result
 182        - The actual `result` of the test
 183
 184      Used for regression testing of the functions in lib; see
 185      tests.nix for more examples.
 186
 187      Important: Only attributes that start with `test` are executed.
 188
 189      - If you want to run only a subset of the tests add the attribute `tests = ["testName"];`
 190
 191     Example:
 192
 193      runTests {
 194        testAndOk = {
 195          expr = lib.and true false;
 196          expected = false;
 197        };
 198        testAndFail = {
 199          expr = lib.and true false;
 200          expected = true;
 201        };
 202      }
 203      ->
 204      [
 205        {
 206          name = "testAndFail";
 207          expected = true;
 208          result = false;
 209        }
 210      ]
 211
 212     Type:
 213       runTests :: {
 214         tests = [ String ];
 215         ${testName} :: {
 216           expr :: a;
 217           expected :: a;
 218         };
 219       }
 220       ->
 221       [
 222         {
 223           name :: String;
 224           expected :: a;
 225           result :: a;
 226         }
 227       ]
 228   */
 229   runTests =
 230     # Tests to run
 231     tests: concatLists (attrValues (mapAttrs (name: test:
 232     let testsToRun = if tests ? tests then tests.tests else [];
 233     in if (substring 0 4 name == "test" ||  elem name testsToRun)
 234        && ((testsToRun == []) || elem name tests.tests)
 235        && (test.expr != test.expected)
 236
 237       then [ { inherit name; expected = test.expected; result = test.expr; } ]
 238       else [] ) tests));
 239
 240   /* Create a test assuming that list elements are `true`.
 241
 242      Example:
 243        { testX = allTrue [ true ]; }
 244   */
 245   testAllTrue = expr: { inherit expr; expected = map (x: true) expr; };
 246 }