642 lines
22 KiB
Nix
642 lines
22 KiB
Nix
|
/* Functions for working with path values. */
|
||
|
|
# See ./README.md for internal docs
|
||
|
|
{ lib }:
|
||
|
|
let
|
||
|
|
|
||
|
|
inherit (builtins)
|
||
|
|
isString
|
||
|
|
isPath
|
||
|
|
split
|
||
|
|
match
|
||
|
|
typeOf
|
||
|
|
storeDir
|
||
|
|
;
|
||
|
|
|
||
|
|
inherit (lib.lists)
|
||
|
|
length
|
||
|
|
head
|
||
|
|
last
|
||
|
|
genList
|
||
|
|
elemAt
|
||
|
|
all
|
||
|
|
concatMap
|
||
|
|
foldl'
|
||
|
|
take
|
||
|
|
drop
|
||
|
|
;
|
||
|
|
|
||
|
|
listHasPrefix = lib.lists.hasPrefix;
|
||
|
|
|
||
|
|
inherit (lib.strings)
|
||
|
|
concatStringsSep
|
||
|
|
substring
|
||
|
|
;
|
||
|
|
|
||
|
|
inherit (lib.asserts)
|
||
|
|
assertMsg
|
||
|
|
;
|
||
|
|
|
||
|
|
inherit (lib.path.subpath)
|
||
|
|
isValid
|
||
|
|
;
|
||
|
|
|
||
|
|
# Return the reason why a subpath is invalid, or `null` if it's valid
|
||
|
|
subpathInvalidReason = value:
|
||
|
|
if ! isString value then
|
||
|
|
"The given value is of type ${builtins.typeOf value}, but a string was expected"
|
||
|
|
else if value == "" then
|
||
|
|
"The given string is empty"
|
||
|
|
else if substring 0 1 value == "/" then
|
||
|
|
"The given string \"${value}\" starts with a `/`, representing an absolute path"
|
||
|
|
# We don't support ".." components, see ./path.md#parent-directory
|
||
|
|
else if match "(.*/)?\\.\\.(/.*)?" value != null then
|
||
|
|
"The given string \"${value}\" contains a `..` component, which is not allowed in subpaths"
|
||
|
|
else null;
|
||
|
|
|
||
|
|
# Split and normalise a relative path string into its components.
|
||
|
|
# Error for ".." components and doesn't include "." components
|
||
|
|
splitRelPath = path:
|
||
|
|
let
|
||
|
|
# Split the string into its parts using regex for efficiency. This regex
|
||
|
|
# matches patterns like "/", "/./", "/././", with arbitrarily many "/"s
|
||
|
|
# together. These are the main special cases:
|
||
|
|
# - Leading "./" gets split into a leading "." part
|
||
|
|
# - Trailing "/." or "/" get split into a trailing "." or ""
|
||
|
|
# part respectively
|
||
|
|
#
|
||
|
|
# These are the only cases where "." and "" parts can occur
|
||
|
|
parts = split "/+(\\./+)*" path;
|
||
|
|
|
||
|
|
# `split` creates a list of 2 * k + 1 elements, containing the k +
|
||
|
|
# 1 parts, interleaved with k matches where k is the number of
|
||
|
|
# (non-overlapping) matches. This calculation here gets the number of parts
|
||
|
|
# back from the list length
|
||
|
|
# floor( (2 * k + 1) / 2 ) + 1 == floor( k + 1/2 ) + 1 == k + 1
|
||
|
|
partCount = length parts / 2 + 1;
|
||
|
|
|
||
|
|
# To assemble the final list of components we want to:
|
||
|
|
# - Skip a potential leading ".", normalising "./foo" to "foo"
|
||
|
|
# - Skip a potential trailing "." or "", normalising "foo/" and "foo/." to
|
||
|
|
# "foo". See ./path.md#trailing-slashes
|
||
|
|
skipStart = if head parts == "." then 1 else 0;
|
||
|
|
skipEnd = if last parts == "." || last parts == "" then 1 else 0;
|
||
|
|
|
||
|
|
# We can now know the length of the result by removing the number of
|
||
|
|
# skipped parts from the total number
|
||
|
|
componentCount = partCount - skipEnd - skipStart;
|
||
|
|
|
||
|
|
in
|
||
|
|
# Special case of a single "." path component. Such a case leaves a
|
||
|
|
# componentCount of -1 due to the skipStart/skipEnd not verifying that
|
||
|
|
# they don't refer to the same character
|
||
|
|
if path == "." then []
|
||
|
|
|
||
|
|
# Generate the result list directly. This is more efficient than a
|
||
|
|
# combination of `filter`, `init` and `tail`, because here we don't
|
||
|
|
# allocate any intermediate lists
|
||
|
|
else genList (index:
|
||
|
|
# To get to the element we need to add the number of parts we skip and
|
||
|
|
# multiply by two due to the interleaved layout of `parts`
|
||
|
|
elemAt parts ((skipStart + index) * 2)
|
||
|
|
) componentCount;
|
||
|
|
|
||
|
|
# Join relative path components together
|
||
|
|
joinRelPath = components:
|
||
|
|
# Always return relative paths with `./` as a prefix (./path.md#leading-dots-for-relative-paths)
|
||
|
|
"./" +
|
||
|
|
# 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 [];
|
||
|
|
|
||
|
|
# The components of the store directory, typically [ "nix" "store" ]
|
||
|
|
storeDirComponents = splitRelPath ("./" + storeDir);
|
||
|
|
# The number of store directory components, typically 2
|
||
|
|
storeDirLength = length storeDirComponents;
|
||
|
|
|
||
|
|
# Type: [ String ] -> Bool
|
||
|
|
#
|
||
|
|
# Whether path components have a store path as a prefix, according to
|
||
|
|
# https://nixos.org/manual/nix/stable/store/store-path.html#store-path.
|
||
|
|
componentsHaveStorePathPrefix = components:
|
||
|
|
# path starts with the store directory (typically /nix/store)
|
||
|
|
listHasPrefix storeDirComponents components
|
||
|
|
# is not the store directory itself, meaning there's at least one extra component
|
||
|
|
&& storeDirComponents != components
|
||
|
|
# and the first component after the store directory has the expected format.
|
||
|
|
# NOTE: We could change the hash regex to be [0-9a-df-np-sv-z],
|
||
|
|
# because these are the actual ASCII characters used by Nix's base32 implementation,
|
||
|
|
# but this is not fully specified, so let's tie this too much to the currently implemented concept of store paths.
|
||
|
|
# Similar reasoning applies to the validity of the name part.
|
||
|
|
# We care more about discerning store path-ness on realistic values. Making it airtight would be fragile and slow.
|
||
|
|
&& match ".{32}-.+" (elemAt components storeDirLength) != null;
|
||
|
|
|
||
|
|
in /* No rec! Add dependencies on this file at the top. */ {
|
||
|
|
|
||
|
|
/*
|
||
|
|
Append a subpath string to a path.
|
||
|
|
|
||
|
|
Like `path + ("/" + string)` but safer, because it errors instead of returning potentially surprising results.
|
||
|
|
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](#function-library-lib.path.subpath.isValid).
|
||
|
|
|
||
|
|
Laws:
|
||
|
|
|
||
|
|
- Not influenced by subpath [normalisation](#function-library-lib.path.subpath.normalise):
|
||
|
|
|
||
|
|
append p s == append p (subpath.normalise s)
|
||
|
|
|
||
|
|
Type:
|
||
|
|
append :: Path -> String -> Path
|
||
|
|
|
||
|
|
Example:
|
||
|
|
append /foo "bar/baz"
|
||
|
|
=> /foo/bar/baz
|
||
|
|
|
||
|
|
# subpaths don't need to be normalised
|
||
|
|
append /foo "./bar//baz/./"
|
||
|
|
=> /foo/bar/baz
|
||
|
|
|
||
|
|
# can append to root directory
|
||
|
|
append /. "foo/bar"
|
||
|
|
=> /foo/bar
|
||
|
|
|
||
|
|
# first argument needs to be a path value type
|
||
|
|
append "/foo" "bar"
|
||
|
|
=> <error>
|
||
|
|
|
||
|
|
# second argument needs to be a valid subpath string
|
||
|
|
append /foo /bar
|
||
|
|
=> <error>
|
||
|
|
append /foo ""
|
||
|
|
=> <error>
|
||
|
|
append /foo "/bar"
|
||
|
|
=> <error>
|
||
|
|
append /foo "../bar"
|
||
|
|
=> <error>
|
||
|
|
*/
|
||
|
|
append =
|
||
|
|
# The absolute path to append to
|
||
|
|
path:
|
||
|
|
# The subpath string to append
|
||
|
|
subpath:
|
||
|
|
assert assertMsg (isPath path) ''
|
||
|
|
lib.path.append: The first argument is of type ${builtins.typeOf path}, but a path was expected'';
|
||
|
|
assert assertMsg (isValid subpath) ''
|
||
|
|
lib.path.append: Second argument is not a valid subpath string:
|
||
|
|
${subpathInvalidReason subpath}'';
|
||
|
|
path + ("/" + subpath);
|
||
|
|
|
||
|
|
/*
|
||
|
|
Whether the first path is a component-wise prefix of the second path.
|
||
|
|
|
||
|
|
Laws:
|
||
|
|
|
||
|
|
- `hasPrefix p q` is only true if [`q == append p s`](#function-library-lib.path.append) for some [subpath](#function-library-lib.path.subpath.isValid) `s`.
|
||
|
|
|
||
|
|
- `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 the first path as a component-wise prefix from the second path.
|
||
|
|
The result is a [normalised subpath string](#function-library-lib.path.subpath.normalise).
|
||
|
|
|
||
|
|
Laws:
|
||
|
|
|
||
|
|
- Inverts [`append`](#function-library-lib.path.append) for [normalised subpath string](#function-library-lib.path.subpath.normalise):
|
||
|
|
|
||
|
|
removePrefix p (append p s) == subpath.normalise s
|
||
|
|
|
||
|
|
Type:
|
||
|
|
removePrefix :: Path -> Path -> String
|
||
|
|
|
||
|
|
Example:
|
||
|
|
removePrefix /foo /foo/bar/baz
|
||
|
|
=> "./bar/baz"
|
||
|
|
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;
|
||
|
|
success = take path1Length path2Deconstructed.components == path1Deconstructed.components;
|
||
|
|
components =
|
||
|
|
if success then
|
||
|
|
drop path1Length path2Deconstructed.components
|
||
|
|
else
|
||
|
|
throw ''
|
||
|
|
lib.path.removePrefix: The first path argument "${toString path1}" is not a component-wise prefix of the second path argument "${toString 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}"'';
|
||
|
|
joinRelPath components;
|
||
|
|
|
||
|
|
/*
|
||
|
|
Split the filesystem root from a [path](https://nixos.org/manual/nix/stable/language/values.html#type-path).
|
||
|
|
The result is an attribute set with these attributes:
|
||
|
|
- `root`: The filesystem root of the path, meaning that this directory has no parent directory.
|
||
|
|
- `subpath`: The [normalised subpath string](#function-library-lib.path.subpath.normalise) that when [appended](#function-library-lib.path.append) to `root` returns the original path.
|
||
|
|
|
||
|
|
Laws:
|
||
|
|
- [Appending](#function-library-lib.path.append) the `root` and `subpath` gives the original path:
|
||
|
|
|
||
|
|
p ==
|
||
|
|
append
|
||
|
|
(splitRoot p).root
|
||
|
|
(splitRoot p).subpath
|
||
|
|
|
||
|
|
- Trying to get the parent directory of `root` using [`readDir`](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-readDir) returns `root` itself:
|
||
|
|
|
||
|
|
dirOf (splitRoot p).root == (splitRoot p).root
|
||
|
|
|
||
|
|
Type:
|
||
|
|
splitRoot :: Path -> { root :: Path, subpath :: String }
|
||
|
|
|
||
|
|
Example:
|
||
|
|
splitRoot /foo/bar
|
||
|
|
=> { root = /.; subpath = "./foo/bar"; }
|
||
|
|
|
||
|
|
splitRoot /.
|
||
|
|
=> { root = /.; subpath = "./."; }
|
||
|
|
|
||
|
|
# Nix neutralises `..` path components for all path values automatically
|
||
|
|
splitRoot /foo/../bar
|
||
|
|
=> { root = /.; subpath = "./bar"; }
|
||
|
|
|
||
|
|
splitRoot "/foo/bar"
|
||
|
|
=> <error>
|
||
|
|
*/
|
||
|
|
splitRoot =
|
||
|
|
# The path to split the root off of
|
||
|
|
path:
|
||
|
|
assert assertMsg
|
||
|
|
(isPath path)
|
||
|
|
"lib.path.splitRoot: Argument is of type ${typeOf path}, but a path was expected";
|
||
|
|
let
|
||
|
|
deconstructed = deconstructPath path;
|
||
|
|
in {
|
||
|
|
root = deconstructed.root;
|
||
|
|
subpath = joinRelPath deconstructed.components;
|
||
|
|
};
|
||
|
|
|
||
|
|
/*
|
||
|
|
Whether a [path](https://nixos.org/manual/nix/stable/language/values.html#type-path)
|
||
|
|
has a [store path](https://nixos.org/manual/nix/stable/store/store-path.html#store-path)
|
||
|
|
as a prefix.
|
||
|
|
|
||
|
|
:::{.note}
|
||
|
|
As with all functions of this `lib.path` library, it does not work on paths in strings,
|
||
|
|
which is how you'd typically get store paths.
|
||
|
|
|
||
|
|
Instead, this function only handles path values themselves,
|
||
|
|
which occur when Nix files in the store use relative path expressions.
|
||
|
|
:::
|
||
|
|
|
||
|
|
Type:
|
||
|
|
hasStorePathPrefix :: Path -> Bool
|
||
|
|
|
||
|
|
Example:
|
||
|
|
# Subpaths of derivation outputs have a store path as a prefix
|
||
|
|
hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo/bar/baz
|
||
|
|
=> true
|
||
|
|
|
||
|
|
# The store directory itself is not a store path
|
||
|
|
hasStorePathPrefix /nix/store
|
||
|
|
=> false
|
||
|
|
|
||
|
|
# Derivation outputs are store paths themselves
|
||
|
|
hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo
|
||
|
|
=> true
|
||
|
|
|
||
|
|
# Paths outside the Nix store don't have a store path prefix
|
||
|
|
hasStorePathPrefix /home/user
|
||
|
|
=> false
|
||
|
|
|
||
|
|
# Not all paths under the Nix store are store paths
|
||
|
|
hasStorePathPrefix /nix/store/.links/10gg8k3rmbw8p7gszarbk7qyd9jwxhcfq9i6s5i0qikx8alkk4hq
|
||
|
|
=> false
|
||
|
|
|
||
|
|
# Store derivations are also store paths themselves
|
||
|
|
hasStorePathPrefix /nix/store/nvl9ic0pj1fpyln3zaqrf4cclbqdfn1j-foo.drv
|
||
|
|
=> true
|
||
|
|
*/
|
||
|
|
hasStorePathPrefix = path:
|
||
|
|
let
|
||
|
|
deconstructed = deconstructPath path;
|
||
|
|
in
|
||
|
|
assert assertMsg
|
||
|
|
(isPath path)
|
||
|
|
"lib.path.hasStorePathPrefix: Argument is of type ${typeOf path}, but a path was expected";
|
||
|
|
assert assertMsg
|
||
|
|
# This function likely breaks or needs adjustment if used with other filesystem roots, if they ever get implemented.
|
||
|
|
# Let's try to error nicely in such a case, though it's unclear how an implementation would work even and whether this could be detected.
|
||
|
|
# See also https://github.com/NixOS/nix/pull/6530#discussion_r1422843117
|
||
|
|
(deconstructed.root == /. && toString deconstructed.root == "/")
|
||
|
|
"lib.path.hasStorePathPrefix: Argument has a filesystem root (${toString deconstructed.root}) that's not /, which is currently not supported.";
|
||
|
|
componentsHaveStorePathPrefix deconstructed.components;
|
||
|
|
|
||
|
|
/*
|
||
|
|
Whether a value is a valid subpath string.
|
||
|
|
|
||
|
|
A subpath string points to a specific file or directory within an absolute base directory.
|
||
|
|
It is a stricter form of a relative path that excludes `..` components, since those could escape the base directory.
|
||
|
|
|
||
|
|
- The value is a string.
|
||
|
|
|
||
|
|
- The string is not empty.
|
||
|
|
|
||
|
|
- The string doesn't start with a `/`.
|
||
|
|
|
||
|
|
- The string doesn't contain any `..` path components.
|
||
|
|
|
||
|
|
Type:
|
||
|
|
subpath.isValid :: String -> Bool
|
||
|
|
|
||
|
|
Example:
|
||
|
|
# Not a string
|
||
|
|
subpath.isValid null
|
||
|
|
=> false
|
||
|
|
|
||
|
|
# Empty string
|
||
|
|
subpath.isValid ""
|
||
|
|
=> false
|
||
|
|
|
||
|
|
# Absolute path
|
||
|
|
subpath.isValid "/foo"
|
||
|
|
=> false
|
||
|
|
|
||
|
|
# Contains a `..` path component
|
||
|
|
subpath.isValid "../foo"
|
||
|
|
=> false
|
||
|
|
|
||
|
|
# Valid subpath
|
||
|
|
subpath.isValid "foo/bar"
|
||
|
|
=> true
|
||
|
|
|
||
|
|
# Doesn't need to be normalised
|
||
|
|
subpath.isValid "./foo//bar/"
|
||
|
|
=> true
|
||
|
|
*/
|
||
|
|
subpath.isValid =
|
||
|
|
# The value to check
|
||
|
|
value:
|
||
|
|
subpathInvalidReason value == null;
|
||
|
|
|
||
|
|
|
||
|
|
/*
|
||
|
|
Join subpath strings together using `/`, returning a normalised subpath string.
|
||
|
|
|
||
|
|
Like `concatStringsSep "/"` but safer, specifically:
|
||
|
|
|
||
|
|
- All elements must be [valid subpath strings](#function-library-lib.path.subpath.isValid).
|
||
|
|
|
||
|
|
- The result gets [normalised](#function-library-lib.path.subpath.normalise).
|
||
|
|
|
||
|
|
- The edge case of an empty list gets properly handled by returning the neutral subpath `"./."`.
|
||
|
|
|
||
|
|
Laws:
|
||
|
|
|
||
|
|
- Associativity:
|
||
|
|
|
||
|
|
subpath.join [ x (subpath.join [ y z ]) ] == subpath.join [ (subpath.join [ x y ]) z ]
|
||
|
|
|
||
|
|
- Identity - `"./."` is the neutral element for normalised paths:
|
||
|
|
|
||
|
|
subpath.join [ ] == "./."
|
||
|
|
subpath.join [ (subpath.normalise p) "./." ] == subpath.normalise p
|
||
|
|
subpath.join [ "./." (subpath.normalise p) ] == subpath.normalise p
|
||
|
|
|
||
|
|
- Normalisation - the result is [normalised](#function-library-lib.path.subpath.normalise):
|
||
|
|
|
||
|
|
subpath.join ps == subpath.normalise (subpath.join ps)
|
||
|
|
|
||
|
|
- For non-empty lists, the implementation is equivalent to [normalising](#function-library-lib.path.subpath.normalise) the result of `concatStringsSep "/"`.
|
||
|
|
Note that the above laws can be derived from this one:
|
||
|
|
|
||
|
|
ps != [] -> subpath.join ps == subpath.normalise (concatStringsSep "/" ps)
|
||
|
|
|
||
|
|
Type:
|
||
|
|
subpath.join :: [ String ] -> String
|
||
|
|
|
||
|
|
Example:
|
||
|
|
subpath.join [ "foo" "bar/baz" ]
|
||
|
|
=> "./foo/bar/baz"
|
||
|
|
|
||
|
|
# normalise the result
|
||
|
|
subpath.join [ "./foo" "." "bar//./baz/" ]
|
||
|
|
=> "./foo/bar/baz"
|
||
|
|
|
||
|
|
# passing an empty list results in the current directory
|
||
|
|
subpath.join [ ]
|
||
|
|
=> "./."
|
||
|
|
|
||
|
|
# elements must be valid subpath strings
|
||
|
|
subpath.join [ /foo ]
|
||
|
|
=> <error>
|
||
|
|
subpath.join [ "" ]
|
||
|
|
=> <error>
|
||
|
|
subpath.join [ "/foo" ]
|
||
|
|
=> <error>
|
||
|
|
subpath.join [ "../foo" ]
|
||
|
|
=> <error>
|
||
|
|
*/
|
||
|
|
subpath.join =
|
||
|
|
# The list of subpaths to join together
|
||
|
|
subpaths:
|
||
|
|
# Fast in case all paths are valid
|
||
|
|
if all isValid subpaths
|
||
|
|
then joinRelPath (concatMap splitRelPath subpaths)
|
||
|
|
else
|
||
|
|
# Otherwise we take our time to gather more info for a better error message
|
||
|
|
# Strictly go through each path, throwing on the first invalid one
|
||
|
|
# Tracks the list index in the fold accumulator
|
||
|
|
foldl' (i: path:
|
||
|
|
if isValid path
|
||
|
|
then i + 1
|
||
|
|
else throw ''
|
||
|
|
lib.path.subpath.join: Element at index ${toString i} is not a valid subpath string:
|
||
|
|
${subpathInvalidReason path}''
|
||
|
|
) 0 subpaths;
|
||
|
|
|
||
|
|
/*
|
||
|
|
Split [a subpath](#function-library-lib.path.subpath.isValid) into its path component strings.
|
||
|
|
Throw an error if the subpath isn't valid.
|
||
|
|
Note that the returned path components are also [valid subpath strings](#function-library-lib.path.subpath.isValid), though they are intentionally not [normalised](#function-library-lib.path.subpath.normalise).
|
||
|
|
|
||
|
|
Laws:
|
||
|
|
|
||
|
|
- Splitting a subpath into components and [joining](#function-library-lib.path.subpath.join) the components gives the same subpath but [normalised](#function-library-lib.path.subpath.normalise):
|
||
|
|
|
||
|
|
subpath.join (subpath.components s) == subpath.normalise s
|
||
|
|
|
||
|
|
Type:
|
||
|
|
subpath.components :: String -> [ String ]
|
||
|
|
|
||
|
|
Example:
|
||
|
|
subpath.components "."
|
||
|
|
=> [ ]
|
||
|
|
|
||
|
|
subpath.components "./foo//bar/./baz/"
|
||
|
|
=> [ "foo" "bar" "baz" ]
|
||
|
|
|
||
|
|
subpath.components "/foo"
|
||
|
|
=> <error>
|
||
|
|
*/
|
||
|
|
subpath.components =
|
||
|
|
# The subpath string to split into components
|
||
|
|
subpath:
|
||
|
|
assert assertMsg (isValid subpath) ''
|
||
|
|
lib.path.subpath.components: Argument is not a valid subpath string:
|
||
|
|
${subpathInvalidReason subpath}'';
|
||
|
|
splitRelPath subpath;
|
||
|
|
|
||
|
|
/*
|
||
|
|
Normalise a subpath. Throw an error if the subpath isn't [valid](#function-library-lib.path.subpath.isValid).
|
||
|
|
|
||
|
|
- Limit repeating `/` to a single one.
|
||
|
|
|
||
|
|
- Remove redundant `.` components.
|
||
|
|
|
||
|
|
- Remove trailing `/` and `/.`.
|
||
|
|
|
||
|
|
- Add leading `./`.
|
||
|
|
|
||
|
|
Laws:
|
||
|
|
|
||
|
|
- Idempotency - normalising multiple times gives the same result:
|
||
|
|
|
||
|
|
subpath.normalise (subpath.normalise p) == subpath.normalise p
|
||
|
|
|
||
|
|
- Uniqueness - there's only a single normalisation for the paths that lead to the same file system node:
|
||
|
|
|
||
|
|
subpath.normalise p != subpath.normalise q -> $(realpath ${p}) != $(realpath ${q})
|
||
|
|
|
||
|
|
- Don't change the result when [appended](#function-library-lib.path.append) to a Nix path value:
|
||
|
|
|
||
|
|
append base p == append base (subpath.normalise p)
|
||
|
|
|
||
|
|
- Don't change the path according to `realpath`:
|
||
|
|
|
||
|
|
$(realpath ${p}) == $(realpath ${subpath.normalise p})
|
||
|
|
|
||
|
|
- Only error on [invalid subpaths](#function-library-lib.path.subpath.isValid):
|
||
|
|
|
||
|
|
builtins.tryEval (subpath.normalise p)).success == subpath.isValid p
|
||
|
|
|
||
|
|
Type:
|
||
|
|
subpath.normalise :: String -> String
|
||
|
|
|
||
|
|
Example:
|
||
|
|
# limit repeating `/` to a single one
|
||
|
|
subpath.normalise "foo//bar"
|
||
|
|
=> "./foo/bar"
|
||
|
|
|
||
|
|
# remove redundant `.` components
|
||
|
|
subpath.normalise "foo/./bar"
|
||
|
|
=> "./foo/bar"
|
||
|
|
|
||
|
|
# add leading `./`
|
||
|
|
subpath.normalise "foo/bar"
|
||
|
|
=> "./foo/bar"
|
||
|
|
|
||
|
|
# remove trailing `/`
|
||
|
|
subpath.normalise "foo/bar/"
|
||
|
|
=> "./foo/bar"
|
||
|
|
|
||
|
|
# remove trailing `/.`
|
||
|
|
subpath.normalise "foo/bar/."
|
||
|
|
=> "./foo/bar"
|
||
|
|
|
||
|
|
# Return the current directory as `./.`
|
||
|
|
subpath.normalise "."
|
||
|
|
=> "./."
|
||
|
|
|
||
|
|
# error on `..` path components
|
||
|
|
subpath.normalise "foo/../bar"
|
||
|
|
=> <error>
|
||
|
|
|
||
|
|
# error on empty string
|
||
|
|
subpath.normalise ""
|
||
|
|
=> <error>
|
||
|
|
|
||
|
|
# error on absolute path
|
||
|
|
subpath.normalise "/foo"
|
||
|
|
=> <error>
|
||
|
|
*/
|
||
|
|
subpath.normalise =
|
||
|
|
# The subpath string to normalise
|
||
|
|
subpath:
|
||
|
|
assert assertMsg (isValid subpath) ''
|
||
|
|
lib.path.subpath.normalise: Argument is not a valid subpath string:
|
||
|
|
${subpathInvalidReason subpath}'';
|
||
|
|
joinRelPath (splitRelPath subpath);
|
||
|
|
|
||
|
|
}
|