diff options
author | Silvan Mosberger <contact@infinisil.com> | 2023-10-04 17:39:20 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-10-04 17:39:20 +0200 |
commit | 5db719f69c9c27690960737d4aeadae741f5a48a (patch) | |
tree | 748eb3d0e1423c02b2df608fb51bc1602ac39b8d /lib/fileset/default.nix | |
parent | fc66242d50cf5a4cc221b0a9a7bb4e03242ef58c (diff) | |
parent | 5b4e53a30074a98621681142b4698f7c45ebc716 (diff) |
Merge pull request #256417 from tweag/fileset.trace
`lib.fileset.trace`, `lib.fileset.traceVal`: init
Diffstat (limited to 'lib/fileset/default.nix')
-rw-r--r-- | lib/fileset/default.nix | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/lib/fileset/default.nix b/lib/fileset/default.nix index f7d957bd264c1..93a552262b0c7 100644 --- a/lib/fileset/default.nix +++ b/lib/fileset/default.nix @@ -6,12 +6,14 @@ let _coerceMany _toSourceFilter _unionMany + _printFileset ; inherit (builtins) isList isPath pathExists + seq typeOf ; @@ -274,4 +276,93 @@ If a directory does not recursively contain any file, it is omitted from the sto _unionMany ]; + /* + Incrementally evaluate and trace a file set in a pretty way. + This function is only intended for debugging purposes. + The exact tracing format is unspecified and may change. + + This function takes a final argument to return. + In comparison, [`traceVal`](#function-library-lib.fileset.traceVal) returns + the given file set argument. + + This variant is useful for tracing file sets in the Nix repl. + + Type: + trace :: FileSet -> Any -> Any + + Example: + trace (unions [ ./Makefile ./src ./tests/run.sh ]) null + => + trace: /home/user/src/myProject + trace: - Makefile (regular) + trace: - src (all files in directory) + trace: - tests + trace: - run.sh (regular) + null + */ + trace = + /* + The file set to trace. + + This argument can also be a path, + which gets [implicitly coerced to a file set](#sec-fileset-path-coercion). + */ + fileset: + let + # "fileset" would be a better name, but that would clash with the argument name, + # and we cannot change that because of https://github.com/nix-community/nixdoc/issues/76 + actualFileset = _coerce "lib.fileset.trace: argument" fileset; + in + seq + (_printFileset actualFileset) + (x: x); + + /* + Incrementally evaluate and trace a file set in a pretty way. + This function is only intended for debugging purposes. + The exact tracing format is unspecified and may change. + + This function returns the given file set. + In comparison, [`trace`](#function-library-lib.fileset.trace) takes another argument to return. + + This variant is useful for tracing file sets passed as arguments to other functions. + + Type: + traceVal :: FileSet -> FileSet + + Example: + toSource { + root = ./.; + fileset = traceVal (unions [ + ./Makefile + ./src + ./tests/run.sh + ]); + } + => + trace: /home/user/src/myProject + trace: - Makefile (regular) + trace: - src (all files in directory) + trace: - tests + trace: - run.sh (regular) + "/nix/store/...-source" + */ + traceVal = + /* + The file set to trace and return. + + This argument can also be a path, + which gets [implicitly coerced to a file set](#sec-fileset-path-coercion). + */ + fileset: + let + # "fileset" would be a better name, but that would clash with the argument name, + # and we cannot change that because of https://github.com/nix-community/nixdoc/issues/76 + actualFileset = _coerce "lib.fileset.traceVal: argument" fileset; + in + seq + (_printFileset actualFileset) + # We could also return the original fileset argument here, + # but that would then duplicate work for consumers of the fileset, because then they have to coerce it again + actualFileset; } |