lib/debug.nix

   1 /**
   2   Collection of functions useful for debugging
   3   broken nix expressions.
   4
   5   * `trace`-like functions take two values, print
   6     the first to stderr and return the second.
   7   * `traceVal`-like functions take one argument
   8     which both printed and returned.
   9   * `traceSeq`-like functions fully evaluate their
  10     traced value before printing (not just to “weak
  11     head normal form” like trace does by default).
  12   * Functions that end in `-Fn` take an additional
  13     function as their first argument, which is applied
  14     to the traced value before it is printed.
  15 */
  16 { lib }:
  17 let
  18   inherit (lib)
  19     isList
  20     isAttrs
  21     substring
  22     attrValues
  23     concatLists
  24     const
  25     elem
  26     generators
  27     id
  28     mapAttrs
  29     trace;
  30 in
  31
  32 rec {
  33
  34   # -- TRACING --
  35
  36   /**
  37     Conditionally trace the supplied message, based on a predicate.
  38
  39
  40     # Inputs
  41
  42     `pred`
  43
  44     : Predicate to check
  45
  46     `msg`
  47
  48     : Message that should be traced
  49
  50     `x`
  51
  52     : Value to return
  53
  54     # Type
  55
  56     ```
  57     traceIf :: bool -> string -> a -> a
  58     ```
  59
  60     # Examples
  61     :::{.example}
  62     ## `lib.debug.traceIf` usage example
  63
  64     ```nix
  65     traceIf true "hello" 3
  66     trace: hello
  67     => 3
  68     ```
  69
  70     :::
  71   */
  72   traceIf =
  73     pred:
  74     msg:
  75     x: if pred then trace msg x else x;
  76
  77   /**
  78     Trace the supplied value after applying a function to it, and
  79     return the original value.
  80
  81
  82     # Inputs
  83
  84     `f`
  85
  86     : Function to apply
  87
  88     `x`
  89
  90     : Value to trace and return
  91
  92     # Type
  93
  94     ```
  95     traceValFn :: (a -> b) -> a -> a
  96     ```
  97
  98     # Examples
  99     :::{.example}
 100     ## `lib.debug.traceValFn` usage example
 101
 102     ```nix
 103     traceValFn (v: "mystring ${v}") "foo"
 104     trace: mystring foo
 105     => "foo"
 106     ```
 107
 108     :::
 109   */
 110   traceValFn =
 111     f:
 112     x: trace (f x) x;
 113
 114   /**
 115     Trace the supplied value and return it.
 116
 117     # Inputs
 118
 119     `x`
 120
 121     : Value to trace and return
 122
 123     # Type
 124
 125     ```
 126     traceVal :: a -> a
 127     ```
 128
 129     # Examples
 130     :::{.example}
 131     ## `lib.debug.traceVal` usage example
 132
 133     ```nix
 134     traceVal 42
 135     # trace: 42
 136     => 42
 137     ```
 138
 139     :::
 140   */
 141   traceVal = traceValFn id;
 142
 143   /**
 144     `builtins.trace`, but the value is `builtins.deepSeq`ed first.
 145
 146
 147     # Inputs
 148
 149     `x`
 150
 151     : The value to trace
 152
 153     `y`
 154
 155     : The value to return
 156
 157     # Type
 158
 159     ```
 160     traceSeq :: a -> b -> b
 161     ```
 162
 163     # Examples
 164     :::{.example}
 165     ## `lib.debug.traceSeq` usage example
 166
 167     ```nix
 168     trace { a.b.c = 3; } null
 169     trace: { a = <CODE>; }
 170     => null
 171     traceSeq { a.b.c = 3; } null
 172     trace: { a = { b = { c = 3; }; }; }
 173     => null
 174     ```
 175
 176     :::
 177   */
 178   traceSeq =
 179     x:
 180     y: trace (builtins.deepSeq x x) y;
 181
 182   /**
 183     Like `traceSeq`, but only evaluate down to depth n.
 184     This is very useful because lots of `traceSeq` usages
 185     lead to an infinite recursion.
 186
 187
 188     # Inputs
 189
 190     `depth`
 191
 192     : 1\. Function argument
 193
 194     `x`
 195
 196     : 2\. Function argument
 197
 198     `y`
 199
 200     : 3\. Function argument
 201
 202     # Type
 203
 204     ```
 205     traceSeqN :: Int -> a -> b -> b
 206     ```
 207
 208     # Examples
 209     :::{.example}
 210     ## `lib.debug.traceSeqN` usage example
 211
 212     ```nix
 213     traceSeqN 2 { a.b.c = 3; } null
 214     trace: { a = { b = {…}; }; }
 215     => null
 216     ```
 217
 218     :::
 219   */
 220   traceSeqN = depth: x: y:
 221     let snip = v: if      isList  v then noQuotes "[…]" v
 222                   else if isAttrs v then noQuotes "{…}" v
 223                   else v;
 224         noQuotes = str: v: { __pretty = const str; val = v; };
 225         modify = n: fn: v: if (n == 0) then fn v
 226                       else if isList  v then map (modify (n - 1) fn) v
 227                       else if isAttrs v then mapAttrs
 228                         (const (modify (n - 1) fn)) v
 229                       else v;
 230     in trace (generators.toPretty { allowPrettyValues = true; }
 231                (modify depth snip x)) y;
 232
 233   /**
 234     A combination of `traceVal` and `traceSeq` that applies a
 235     provided function to the value to be traced after `deepSeq`ing
 236     it.
 237
 238
 239     # Inputs
 240
 241     `f`
 242
 243     : Function to apply
 244
 245     `v`
 246
 247     : Value to trace
 248   */
 249   traceValSeqFn =
 250     f:
 251     v: traceValFn f (builtins.deepSeq v v);
 252
 253   /**
 254     A combination of `traceVal` and `traceSeq`.
 255
 256     # Inputs
 257
 258     `v`
 259
 260     : Value to trace
 261
 262   */
 263   traceValSeq = traceValSeqFn id;
 264
 265   /**
 266     A combination of `traceVal` and `traceSeqN` that applies a
 267     provided function to the value to be traced.
 268
 269
 270     # Inputs
 271
 272     `f`
 273
 274     : Function to apply
 275
 276     `depth`
 277
 278     : 2\. Function argument
 279
 280     `v`
 281
 282     : Value to trace
 283   */
 284   traceValSeqNFn =
 285     f:
 286     depth:
 287     v: traceSeqN depth (f v) v;
 288
 289   /**
 290     A combination of `traceVal` and `traceSeqN`.
 291
 292     # Inputs
 293
 294     `depth`
 295
 296     : 1\. Function argument
 297
 298     `v`
 299
 300     : Value to trace
 301   */
 302   traceValSeqN = traceValSeqNFn id;
 303
 304   /**
 305     Trace the input and output of a function `f` named `name`,
 306     both down to `depth`.
 307
 308     This is useful for adding around a function call,
 309     to see the before/after of values as they are transformed.
 310
 311
 312     # Inputs
 313
 314     `depth`
 315
 316     : 1\. Function argument
 317
 318     `name`
 319
 320     : 2\. Function argument
 321
 322     `f`
 323
 324     : 3\. Function argument
 325
 326     `v`
 327
 328     : 4\. Function argument
 329
 330
 331     # Examples
 332     :::{.example}
 333     ## `lib.debug.traceFnSeqN` usage example
 334
 335     ```nix
 336     traceFnSeqN 2 "id" (x: x) { a.b.c = 3; }
 337     trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; }
 338     => { a.b.c = 3; }
 339     ```
 340
 341     :::
 342   */
 343   traceFnSeqN = depth: name: f: v:
 344     let res = f v;
 345     in lib.traceSeqN
 346         (depth + 1)
 347         {
 348           fn = name;
 349           from = v;
 350           to = res;
 351         }
 352         res;
 353
 354
 355   # -- TESTING --
 356
 357   /**
 358     Evaluates a set of tests.
 359
 360     A test is an attribute set `{expr, expected}`,
 361     denoting an expression and its expected result.
 362
 363     The result is a `list` of __failed tests__, each represented as
 364     `{name, expected, result}`,
 365
 366     - expected
 367       - What was passed as `expected`
 368     - result
 369       - The actual `result` of the test
 370
 371     Used for regression testing of the functions in lib; see
 372     tests.nix for more examples.
 373
 374     Important: Only attributes that start with `test` are executed.
 375
 376     - If you want to run only a subset of the tests add the attribute `tests = ["testName"];`
 377
 378
 379     # Inputs
 380
 381     `tests`
 382
 383     : Tests to run
 384
 385     # Type
 386
 387     ```
 388     runTests :: {
 389       tests = [ String ];
 390       ${testName} :: {
 391         expr :: a;
 392         expected :: a;
 393       };
 394     }
 395     ->
 396     [
 397       {
 398         name :: String;
 399         expected :: a;
 400         result :: a;
 401       }
 402     ]
 403     ```
 404
 405     # Examples
 406     :::{.example}
 407     ## `lib.debug.runTests` usage example
 408
 409     ```nix
 410     runTests {
 411       testAndOk = {
 412         expr = lib.and true false;
 413         expected = false;
 414       };
 415       testAndFail = {
 416         expr = lib.and true false;
 417         expected = true;
 418       };
 419     }
 420     ->
 421     [
 422       {
 423         name = "testAndFail";
 424         expected = true;
 425         result = false;
 426       }
 427     ]
 428     ```
 429
 430     :::
 431   */
 432   runTests =
 433     tests: concatLists (attrValues (mapAttrs (name: test:
 434     let testsToRun = if tests ? tests then tests.tests else [];
 435     in if (substring 0 4 name == "test" ||  elem name testsToRun)
 436        && ((testsToRun == []) || elem name tests.tests)
 437        && (test.expr != test.expected)
 438
 439       then [ { inherit name; expected = test.expected; result = test.expr; } ]
 440       else [] ) tests));
 441
 442   /**
 443     Create a test assuming that list elements are `true`.
 444
 445
 446     # Inputs
 447
 448     `expr`
 449
 450     : 1\. Function argument
 451
 452
 453     # Examples
 454     :::{.example}
 455     ## `lib.debug.testAllTrue` usage example
 456
 457     ```nix
 458     { testX = allTrue [ true ]; }
 459     ```
 460
 461     :::
 462   */
 463   testAllTrue = expr: { inherit expr; expected = map (x: true) expr; };
 464 }