From 8252861507ef85b45f739c63f27d4e9a80b31b31 Mon Sep 17 00:00:00 2001
From: Profpatsch <mail@profpatsch.de>
Date: Fri, 18 Oct 2019 17:57:33 +0200
Subject: [PATCH] lib/trivial: add `pipe` function
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`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>
---
 lib/default.nix    |  4 ++--
 lib/tests/misc.nix | 25 +++++++++++++++++++++++++
 lib/trivial.nix    | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/lib/default.nix b/lib/default.nix
index f293a1defb11..74d508ec1d6e 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -57,8 +57,8 @@ let
       hasAttr head isAttrs isBool isInt isList isString length
       lessThan listToAttrs pathExists readFile replaceStrings seq
       stringLength sub substring tail;
-    inherit (trivial) id const concat or and bitAnd bitOr bitXor bitNot
-      boolToString mergeAttrs flip mapNullable inNixShell min max
+    inherit (trivial) id const pipe concat or and bitAnd bitOr bitXor
+      bitNot boolToString mergeAttrs flip mapNullable inNixShell min max
       importJSON warn info showWarnings nixpkgsVersion version mod compare
       splitByAndCompare functionArgs setFunctionArgs isFunction;
     inherit (fixedPoints) fix fix' converge extends composeExtensions
diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix
index e5d76d4e57b7..b064faa1e1ba 100644
--- a/lib/tests/misc.nix
+++ b/lib/tests/misc.nix
@@ -18,6 +18,31 @@ runTests {
     expected = 2;
   };
 
+  testPipe = {
+    expr = pipe 2 [
+      (x: x + 2) # 2 + 2 = 4
+      (x: x * 2) # 4 * 2 = 8
+    ];
+    expected = 8;
+  };
+
+  testPipeEmpty = {
+    expr = pipe 2 [];
+    expected = 2;
+  };
+
+  testPipeStrings = {
+    expr = pipe [ 3 4 ] [
+      (map toString)
+      (map (s: s + "\n"))
+      concatStrings
+    ];
+    expected = ''
+      3
+      4
+    '';
+  };
+
   /*
   testOr = {
     expr = or true false;
diff --git a/lib/trivial.nix b/lib/trivial.nix
index 54c66cfce7b9..3a25e31fb052 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.