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