···
+
Collection of functions useful for debugging
+
broken nix expressions.
+
* `trace`-like functions take two values, print
+
the first to stderr and return the second.
+
* `traceVal`-like functions take one argument
+
which both printed and returned.
+
* `traceSeq`-like functions fully evaluate their
+
traced value before printing (not just to “weak
+
head normal form” like trace does by default).
+
* Functions that end in `-Fn` take an additional
+
function as their first argument, which is applied
+
to the traced value before it is printed.
···
+
Conditionally trace the supplied message, based on a predicate.
+
: Message that should be traced
+
traceIf :: bool -> string -> a -> a
+
## `lib.debug.traceIf` usage example
x: if pred then trace msg x else x;
+
Trace the supplied value after applying a function to it, and
+
return the original value.
+
: Value to trace and return
+
traceValFn :: (a -> b) -> a -> a
+
## `lib.debug.traceValFn` usage example
+
traceValFn (v: "mystring ${v}") "foo"
+
Trace the supplied value and return it.
+
: Value to trace and return
+
## `lib.debug.traceVal` usage example
traceVal = traceValFn id;
+
`builtins.trace`, but the value is `builtins.deepSeq`ed first.
+
traceSeq :: a -> b -> b
+
## `lib.debug.traceSeq` usage example
+
trace { a.b.c = 3; } null
+
traceSeq { a.b.c = 3; } null
+
trace: { a = { b = { c = 3; }; }; }
y: trace (builtins.deepSeq x x) y;
+
Like `traceSeq`, but only evaluate down to depth n.
+
This is very useful because lots of `traceSeq` usages
+
lead to an infinite recursion.
+
: 1\. Function argument
+
: 2\. Function argument
+
: 3\. Function argument
+
traceSeqN :: Int -> a -> b -> b
+
## `lib.debug.traceSeqN` usage example
+
traceSeqN 2 { a.b.c = 3; } null
+
trace: { a = { b = {…}; }; }
let snip = v: if isList v then noQuotes "[…]" v
else if isAttrs v then noQuotes "{…}" v
···
in trace (generators.toPretty { allowPrettyValues = true; }
(modify depth snip x)) y;
+
A combination of `traceVal` and `traceSeq` that applies a
+
provided function to the value to be traced after `deepSeq`ing
v: traceValFn f (builtins.deepSeq v v);
+
A combination of `traceVal` and `traceSeq`.
traceValSeq = traceValSeqFn id;
+
A combination of `traceVal` and `traceSeqN` that applies a
+
provided function to the value to be traced.
+
: 2\. Function argument
v: traceSeqN depth (f v) v;
+
A combination of `traceVal` and `traceSeqN`.
+
: 1\. Function argument
traceValSeqN = traceValSeqNFn id;
+
Trace the input and output of a function `f` named `name`,
+
This is useful for adding around a function call,
+
to see the before/after of values as they are transformed.
+
: 1\. Function argument
+
: 2\. Function argument
+
: 3\. Function argument
+
: 4\. Function argument
+
## `lib.debug.traceFnSeqN` usage example
+
traceFnSeqN 2 "id" (x: x) { a.b.c = 3; }
+
trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; }
traceFnSeqN = depth: name: f: v:
···
+
Evaluates a set of tests.
+
A test is an attribute set `{expr, expected}`,
+
denoting an expression and its expected result.
+
The result is a `list` of __failed tests__, each represented as
+
`{name, expected, result}`,
+
- What was passed as `expected`
+
- The actual `result` of the test
+
Used for regression testing of the functions in lib; see
+
tests.nix for more examples.
+
Important: Only attributes that start with `test` are executed.
+
- If you want to run only a subset of the tests add the attribute `tests = ["testName"];`
+
## `lib.debug.runTests` usage example
+
expr = lib.and true false;
+
expr = lib.and true false;
tests: concatLists (attrValues (mapAttrs (name: test:
let testsToRun = if tests ? tests then tests.tests else [];
in if (substring 0 4 name == "test" || elem name testsToRun)
···
then [ { inherit name; expected = test.expected; result = test.expr; } ]
+
Create a test assuming that list elements are `true`.
+
: 1\. Function argument
+
## `lib.debug.testAllTrue` usage example
+
{ testX = allTrue [ true ]; }
testAllTrue = expr: { inherit expr; expected = map (x: true) expr; };
pyrox.dev