lib.path.hasPrefix, lib.path.removePrefix: init

lib/path/default.nix

@@ -7,6 +7,7 @@ let
     isPath
     split
     match
+    typeOf
     ;
 
   inherit (lib.lists)
@@ -18,6 +19,8 @@ let
     all
     concatMap
     foldl'
+    take
+    drop
     ;
 
   inherit (lib.strings)
@@ -100,6 +103,22 @@ let
     # An empty string is not a valid relative path, so we need to return a `.` when we have no components
     (if components == [] then "." else concatStringsSep "/" components);
 
+  # Type: Path -> { root :: Path, components :: [ String ] }
+  #
+  # Deconstruct a path value type into:
+  # - root: The filesystem root of the path, generally `/`
+  # - components: All the path's components
+  #
+  # This is similar to `splitString "/" (toString path)` but safer
+  # because it can distinguish different filesystem roots
+  deconstructPath =
+    let
+      recurse = components: base:
+        # If the parent of a path is the path itself, then it's a filesystem root
+        if base == dirOf base then { root = base; inherit components; }
+        else recurse ([ (baseNameOf base) ] ++ components) (dirOf base);
+    in recurse [];
+
 in /* No rec! Add dependencies on this file at the top. */ {
 
   /* Append a subpath string to a path.
@@ -108,6 +127,12 @@ in /* No rec! Add dependencies on this file at the top. */ {
     More specifically, it checks that the first argument is a [path value type](https://nixos.org/manual/nix/stable/language/values.html#type-path"),
     and that the second argument is a valid subpath string (see `lib.path.subpath.isValid`).
 
+    Laws:
+
+    - Not influenced by subpath normalisation
+
+        append p s == append p (subpath.normalise s)
+
     Type:
       append :: Path -> String -> Path
 
@@ -149,6 +174,104 @@ in /* No rec! Add dependencies on this file at the top. */ {
           ${subpathInvalidReason subpath}'';
     path + ("/" + subpath);
 
+  /*
+  Whether the second path is a prefix of the first path, or equal to it.
+  Throws an error if the paths don't share the same filesystem root.
+
+  Laws:
+
+  - Equivalent to whether some subpath exists that can be appended to the first path to get the second path:
+
+        hasPrefix p q <-> exists s . append p s == q
+
+  - `hasPrefix` is a [non-strict partial order](https://en.wikipedia.org/wiki/Partially_ordered_set#Non-strict_partial_order) over the set of all path values
+
+  Type:
+    hasPrefix :: Path -> Path -> Bool
+
+  Example:
+    hasPrefix /foo /foo/bar
+    => true
+    hasPrefix /foo /foo
+    => true
+    hasPrefix /foo/bar /foo
+    => false
+    hasPrefix /. /foo
+    => true
+  */
+  hasPrefix =
+    path1:
+    assert assertMsg
+      (isPath path1)
+      "lib.path.hasPrefix: First argument is of type ${typeOf path1}, but a path was expected";
+    let
+      path1Deconstructed = deconstructPath path1;
+    in
+      path2:
+      assert assertMsg
+        (isPath path2)
+        "lib.path.hasPrefix: Second argument is of type ${typeOf path2}, but a path was expected";
+      let
+        path2Deconstructed = deconstructPath path2;
+      in
+        assert assertMsg
+        (path1Deconstructed.root == path2Deconstructed.root) ''
+          lib.path.hasPrefix: Filesystem roots must be the same for both paths, but paths with different roots were given:
+              first argument: "${toString path1}" with root "${toString path1Deconstructed.root}"
+              second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
+        take (length path1Deconstructed.components) path2Deconstructed.components == path1Deconstructed.components;
+
+
+  /*
+  Remove a first prefix path from a second path, the result is a normalised subpath string, see `lib.path.subpath.normalise`.
+  Throws an error if the second path doesn't start with the prefix, see `lib.path.hasPrefix`.
+  Throws an error if the first and the second path don't share the same filesystem root.
+
+  Laws:
+
+  - Inverts `append` for normalised subpaths:
+
+        removePrefix p (append p s) == subpath.normalise s
+
+  Type:
+    removePrefix :: Path -> Path -> String
+
+  Example:
+    removePrefix /foo /foo/bar
+    => "./bar"
+    removePrefix /foo /foo
+    => "./."
+    removePrefix /foo/bar /foo
+    => <error>
+    removePrefix /. /foo
+    => "./foo"
+  */
+  removePrefix =
+    path1:
+    assert assertMsg
+      (isPath path1)
+      "lib.path.removePrefix: First argument is of type ${typeOf path1}, but a path was expected";
+    let
+      path1Deconstructed = deconstructPath path1;
+      path1Length = length path1Deconstructed.components;
+    in
+      path2:
+      assert assertMsg
+        (isPath path2)
+        "lib.path.removePrefix: Second argument is of type ${typeOf path2}, but a path was expected";
+      let
+        path2Deconstructed = deconstructPath path2;
+      in
+        assert assertMsg
+        (path1Deconstructed.root == path2Deconstructed.root) ''
+          lib.path.removePrefix: Filesystem roots must be the same for both paths, but paths with different roots were given:
+              first argument: "${toString path1}" with root "${toString path1Deconstructed.root}"
+              second argument: "${toString path2}" with root "${toString path2Deconstructed.root}"'';
+        if take path1Length path2Deconstructed.components == path1Deconstructed.components
+        then joinRelPath (drop path1Length path2Deconstructed.components)
+        else throw ''
+          lib.path.removePrefix: The first prefix path argument (${toString path1}) is not a prefix of the second path argument (${toString path2})'';
+
   /* Whether a value is a valid subpath string.
 
   - The value is a string

lib/path/tests/unit.nix

@@ -3,7 +3,7 @@
 { libpath }:
 let
   lib = import libpath;
-  inherit (lib.path) append subpath;
+  inherit (lib.path) hasPrefix removePrefix append subpath;
 
   cases = lib.runTests {
     # Test examples from the lib.path.append documentation
@@ -40,6 +40,40 @@ let
       expected = false;
     };
 
+    testHasPrefixExample1 = {
+      expr = hasPrefix /foo /foo/bar;
+      expected = true;
+    };
+    testHasPrefixExample2 = {
+      expr = hasPrefix /foo /foo;
+      expected = true;
+    };
+    testHasPrefixExample3 = {
+      expr = hasPrefix /foo/bar /foo;
+      expected = false;
+    };
+    testHasPrefixExample4 = {
+      expr = hasPrefix /. /foo;
+      expected = true;
+    };
+
+    testRemovePrefixExample1 = {
+      expr = removePrefix /foo /foo/bar;
+      expected = "./bar";
+    };
+    testRemovePrefixExample2 = {
+      expr = removePrefix /foo /foo;
+      expected = "./.";
+    };
+    testRemovePrefixExample3 = {
+      expr = (builtins.tryEval (removePrefix /foo/bar /foo)).success;
+      expected = false;
+    };
+    testRemovePrefixExample4 = {
+      expr = removePrefix /. /foo;
+      expected = "./foo";
+    };
+
     # Test examples from the lib.path.subpath.isValid documentation
     testSubpathIsValidExample1 = {
       expr = subpath.isValid null;

lib/strings.nix

@@ -264,7 +264,8 @@ rec {
         lib.strings.hasPrefix: The first argument (${toString pref}) is a path value, but only strings are supported.
             There is almost certainly a bug in the calling code, since this function always returns `false` in such a case.
             This function also copies the path to the Nix store, which may not be what you want.
-            This behavior is deprecated and will throw an error in the future.''
+            This behavior is deprecated and will throw an error in the future.
+            You might want to use `lib.path.hasPrefix` instead, which correctly supports paths.''
       (substring 0 (stringLength pref) str == pref);
 
   /* Determine whether a string has given suffix.
@@ -624,7 +625,8 @@ rec {
         lib.strings.removePrefix: The first argument (${toString prefix}) is a path value, but only strings are supported.
             There is almost certainly a bug in the calling code, since this function never removes any prefix in such a case.
             This function also copies the path to the Nix store, which may not be what you want.
-            This behavior is deprecated and will throw an error in the future.''
+            This behavior is deprecated and will throw an error in the future.
+            You might want to use `lib.path.removePrefix` instead, which correctly supports paths.''
     (let
       preLen = stringLength prefix;
       sLen = stringLength str;