mirrors/nixpkgs
1
0
Fork 1
mirror of https://github.com/NixOS/nixpkgs.git synced 2024-11-18 03:30:45 +00:00
Code Issues Wiki Activity

lib.path: Make documentation more uniform

Browse source 
- Always have a trailing dot after sentences
- Link more things
- Fix some formatting
- Use `append` instead of `+ ("/"`
This commit is contained in:
Silvan Mosberger 2023-08-08 00:06:27 +02:00
parent c72480119a
commit b5c492b4ba
1 changed files with 26 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
lib/path/default.nix
View file

@ -125,13 +125,13 @@ in /* No rec! Add dependencies on this file at the top. */ {
Like `path + ("/" + string)` but safer, because it errors instead of returning potentially surprising results. 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"), 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`). and that the second argument is a [valid subpath string](#function-library-lib.path.subpath.isValid).
Laws: Laws:
- Not influenced by subpath normalisation - Not influenced by subpath [normalisation](#function-library-lib.path.subpath.normalise):
append p s == append p (subpath.normalise s) append p s == append p (subpath.normalise s)
Type: Type:
append :: Path -> String -> Path append :: Path -> String -> Path
@ -179,9 +179,9 @@ in /* No rec! Add dependencies on this file at the top. */ {
Laws: Laws:
- `hasPrefix p q` is only true if `q == append p s` for some subpath `s`. - `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 - `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: Type:
hasPrefix :: Path -> Path -> Bool hasPrefix :: Path -> Path -> Bool
@ -220,11 +220,11 @@ in /* No rec! Add dependencies on this file at the top. */ {
/* /*
Remove the first path as a component-wise prefix from the second path. Remove the first path as a component-wise prefix from the second path.
The result is a normalised subpath string, see `lib.path.subpath.normalise`. The result is a [normalised subpath string](#function-library-lib.path.subpath.normalise).
Laws: Laws:
- Inverts `append` for normalised subpaths: - 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 removePrefix p (append p s) == subpath.normalise s
@ -322,13 +322,13 @@ in /* No rec! Add dependencies on this file at the top. */ {
A subpath string points to a specific file or directory within an absolute base directory. 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. 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 value is a string.
- The string is not empty - The string is not empty.
- The string doesn't start with a `/` - The string doesn't start with a `/`.
- The string doesn't contain any `..` path components - The string doesn't contain any `..` path components.
Type: Type:
subpath.isValid :: String -> Bool subpath.isValid :: String -> Bool
@ -368,11 +368,11 @@ in /* No rec! Add dependencies on this file at the top. */ {
Like `concatStringsSep "/"` but safer, specifically: Like `concatStringsSep "/"` but safer, specifically:
- All elements must be valid subpath strings, see `lib.path.subpath.isValid` - All elements must be [valid subpath strings](#function-library-lib.path.subpath.isValid).
- The result gets normalised, see `lib.path.subpath.normalise` - 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 `"./."` - The edge case of an empty list gets properly handled by returning the neutral subpath `"./."`.
Laws: Laws:
@ -386,12 +386,12 @@ in /* No rec! Add dependencies on this file at the top. */ {
subpath.join [ (subpath.normalise p) "./." ] == subpath.normalise p subpath.join [ (subpath.normalise p) "./." ] == subpath.normalise p
subpath.join [ "./." (subpath.normalise p) ] == subpath.normalise p subpath.join [ "./." (subpath.normalise p) ] == subpath.normalise p
- Normalisation - the result is normalised according to `lib.path.subpath.normalise`: - Normalisation - the result is [normalised](#function-library-lib.path.subpath.normalise):
subpath.join ps == subpath.normalise (subpath.join ps) subpath.join ps == subpath.normalise (subpath.join ps)
- For non-empty lists, the implementation is equivalent to normalising the result of `concatStringsSep "/"`. - 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. Note that the above laws can be derived from this one:
ps != [] -> subpath.join ps == subpath.normalise (concatStringsSep "/" ps) ps != [] -> subpath.join ps == subpath.normalise (concatStringsSep "/" ps)
@ -441,7 +441,7 @@ in /* No rec! Add dependencies on this file at the top. */ {
/* /*
Split [a subpath](#function-library-lib.path.subpath.isValid) into its path component strings. Split [a subpath](#function-library-lib.path.subpath.isValid) into its path component strings.
Throw an error if the subpath isn't valid. Throw an error if the subpath isn't valid.
Note that the returned path components are also valid subpath strings, though they are intentionally not [normalised](#function-library-lib.path.subpath.normalise). 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: Laws:
@ -469,16 +469,15 @@ in /* No rec! Add dependencies on this file at the top. */ {
${subpathInvalidReason subpath}''; ${subpathInvalidReason subpath}'';
splitRelPath subpath; splitRelPath subpath;
/* Normalise a subpath. Throw an error if the subpath isn't valid, see /* Normalise a subpath. Throw an error if the subpath isn't [valid](#function-library-lib.path.subpath.isValid).
`lib.path.subpath.isValid`
- Limit repeating `/` to a single one - Limit repeating `/` to a single one.
- Remove redundant `.` components - Remove redundant `.` components.
- Remove trailing `/` and `/.` - Remove trailing `/` and `/.`.
- Add leading `./` - Add leading `./`.
Laws: Laws:
@ -490,15 +489,15 @@ in /* No rec! Add dependencies on this file at the top. */ {
subpath.normalise p != subpath.normalise q -> $(realpath ${p}) != $(realpath ${q}) subpath.normalise p != subpath.normalise q -> $(realpath ${p}) != $(realpath ${q})
- Don't change the result when appended to a Nix path value: - Don't change the result when [appended](#function-library-lib.path.append) to a Nix path value:
base + ("/" + p) == base + ("/" + subpath.normalise p) append base p == append base (subpath.normalise p)
- Don't change the path according to `realpath`: - Don't change the path according to `realpath`:
$(realpath ${p}) == $(realpath ${subpath.normalise p}) $(realpath ${p}) == $(realpath ${subpath.normalise p})
- Only error on invalid subpaths: - Only error on [invalid subpaths](#function-library-lib.path.subpath.isValid):
builtins.tryEval (subpath.normalise p)).success == subpath.isValid p builtins.tryEval (subpath.normalise p)).success == subpath.isValid p