lib/trivial: add `pipe` function

`pipe` is a useful operator for creating pipelines of functions.

It works around the usual problem of e.g. string operations becoming
deeply nested functions.

In principle, there are four different ways this function could be
written:

pipe val [ f1 .. fn ]
pipe val [ fn .. f1 ]
compose [ f1 .. fn ] val
compose [ fn .. f1 ] val

The third and fourth form mirror composition of functions, they would
be the same as e.g. `(f1 << f2 << f3 .. << fn) val`.
However, it is not clear which direction the list should have (as one
can see in the second form, which is the most absurd.

In order not to confuse users, we decide for the most “intuitive”
form, which mirrors the way unix pipes work (thus the name `pipe`).
The flow of data goes from left to right.

Co-Authored-By: Silvan Mosberger <infinisil@icloud.com>

1 files changed, 37 insertions, 0 deletions

diff --git a/lib/trivial.nix b/lib/trivial.nix
index 54c66cfce7b..3a25e31fb05 100644
--- a/lib/trivial.nix
+++ b/lib/trivial.nix
@@ -29,6 +29,43 @@ rec {
     # Value to ignore
     y: x;
 
+  /* Pipes a value through a list of functions, left to right.
+
+     Type: pipe :: a -> [<functions>] -> <return type of last function>
+     Example:
+       pipe 2 [
+         (x: x + 2)  # 2 + 2 = 4
+         (x: x * 2)  # 4 * 2 = 8
+       ]
+       => 8
+
+       # ideal to do text transformations
+       pipe [ "a/b" "a/c" ] [
+
+         # create the cp command
+         (map (file: ''cp "${src}/${file}" $out\n''))
+
+         # concatenate all commands into one string
+         lib.concatStrings
+
+         # make that string into a nix derivation
+         (pkgs.runCommand "copy-to-out" {})
+
+       ]
+       => <drv which copies all files to $out>
+
+     The output type of each function has to be the input type
+     of the next function, and the last function returns the
+     final value.
+  */
+  pipe = val: functions:
+    let reverseApply = x: f: f x;
+    in builtins.foldl' reverseApply val functions;
+  /* note please don’t add a function like `compose = flip pipe`.
+     This would confuse users, because the order of the functions
+     in the list is not clear. With pipe, it’s obvious that it
+     goes first-to-last. With `compose`, not so much.
+  */
 
   ## Named versions corresponding to some builtin operators.