doc: migrate lib.filesystem to doc-comment format (#312222)

* doc: migrate lib.filesystem to doc-comment format

* defintion list fixes lib/filesystem.nix

Co-authored-by: Daniel Sidhion <DanielSidhion@users.noreply.github.com>

---------

Co-authored-by: Daniel Sidhion <DanielSidhion@users.noreply.github.com>
This commit is contained in:
Johannes Kirschbauer 2024-06-26 22:01:28 +02:00 committed by GitHub
parent 298465b71c
commit b5af504a3d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -1,4 +1,4 @@
/*
/**
Functions for querying information about the filesystem
without copying any files to the Nix store.
*/
@ -29,19 +29,35 @@ in
{
/*
/**
The type of a path. The path needs to exist and be accessible.
The result is either "directory" for a directory, "regular" for a regular file, "symlink" for a symlink, or "unknown" for anything else.
Type:
pathType :: Path -> String
# Inputs
Example:
pathType /.
=> "directory"
path
pathType /some/file.nix
=> "regular"
: The path to query
# Type
```
pathType :: Path -> String
```
# Examples
:::{.example}
## `lib.filesystem.pathType` usage example
```nix
pathType /.
=> "directory"
pathType /some/file.nix
=> "regular"
```
:::
*/
pathType =
builtins.readFileType or
@ -59,53 +75,97 @@ in
else (readDir (dirOf path)).${baseNameOf path}
);
/*
/**
Whether a path exists and is a directory.
Type:
pathIsDirectory :: Path -> Bool
Example:
pathIsDirectory /.
=> true
# Inputs
pathIsDirectory /this/does/not/exist
=> false
`path`
pathIsDirectory /some/file.nix
=> false
: 1\. Function argument
# Type
```
pathIsDirectory :: Path -> Bool
```
# Examples
:::{.example}
## `lib.filesystem.pathIsDirectory` usage example
```nix
pathIsDirectory /.
=> true
pathIsDirectory /this/does/not/exist
=> false
pathIsDirectory /some/file.nix
=> false
```
:::
*/
pathIsDirectory = path:
pathExists path && pathType path == "directory";
/*
/**
Whether a path exists and is a regular file, meaning not a symlink or any other special file type.
Type:
pathIsRegularFile :: Path -> Bool
Example:
pathIsRegularFile /.
=> false
# Inputs
pathIsRegularFile /this/does/not/exist
=> false
`path`
pathIsRegularFile /some/file.nix
=> true
: 1\. Function argument
# Type
```
pathIsRegularFile :: Path -> Bool
```
# Examples
:::{.example}
## `lib.filesystem.pathIsRegularFile` usage example
```nix
pathIsRegularFile /.
=> false
pathIsRegularFile /this/does/not/exist
=> false
pathIsRegularFile /some/file.nix
=> true
```
:::
*/
pathIsRegularFile = path:
pathExists path && pathType path == "regular";
/*
/**
A map of all haskell packages defined in the given path,
identified by having a cabal file with the same name as the
directory itself.
Type: Path -> Map String Path
# Inputs
`root`
: The directory within to search
# Type
```
Path -> Map String Path
```
*/
haskellPathsInDir =
# The directory within to search
root:
let # Files in the root
root-files = builtins.attrNames (builtins.readDir root);
@ -120,17 +180,30 @@ in
builtins.pathExists (value + "/${name}.cabal")
) root-files-with-paths;
in builtins.listToAttrs cabal-subdirs;
/*
/**
Find the first directory containing a file matching 'pattern'
upward from a given 'file'.
Returns 'null' if no directories contain a file matching 'pattern'.
Type: RegExp -> Path -> Nullable { path : Path; matches : [ MatchResults ]; }
# Inputs
`pattern`
: The pattern to search for
`file`
: The file to start searching upward from
# Type
```
RegExp -> Path -> Nullable { path : Path; matches : [ MatchResults ]; }
```
*/
locateDominatingFile =
# The pattern to search for
pattern:
# The file to start searching upward from
file:
let go = path:
let files = builtins.attrNames (builtins.readDir path);
@ -150,13 +223,23 @@ in
in go (if isDir then file else parent);
/*
/**
Given a directory, return a flattened list of all files within it recursively.
Type: Path -> [ Path ]
# Inputs
`dir`
: The path to recursively list
# Type
```
Path -> [ Path ]
```
*/
listFilesRecursive =
# The path to recursively list
dir:
lib.flatten (lib.mapAttrsToList (name: type:
if type == "directory" then
@ -165,7 +248,7 @@ in
dir + "/${name}"
) (builtins.readDir dir));
/*
/**
Transform a directory tree containing package files suitable for
`callPackage` into a matching nested attribute set of derivations.
@ -223,40 +306,57 @@ in
As a result, directories with no `.nix` files (including empty
directories) will be transformed into empty attribute sets.
Example:
packagesFromDirectoryRecursive {
inherit (pkgs) callPackage;
# Inputs
Structured function argument
: Attribute set containing the following attributes.
Additional attributes are ignored.
`callPackage`
: `pkgs.callPackage`
Type: `Path -> AttrSet -> a`
`directory`
: The directory to read package files from
Type: `Path`
# Type
```
packagesFromDirectoryRecursive :: AttrSet -> AttrSet
```
# Examples
:::{.example}
## `lib.filesystem.packagesFromDirectoryRecursive` usage example
```nix
packagesFromDirectoryRecursive {
inherit (pkgs) callPackage;
directory = ./my-packages;
}
=> { ... }
lib.makeScope pkgs.newScope (
self: packagesFromDirectoryRecursive {
callPackage = self.callPackage;
directory = ./my-packages;
}
=> { ... }
)
=> { ... }
```
lib.makeScope pkgs.newScope (
self: packagesFromDirectoryRecursive {
callPackage = self.callPackage;
directory = ./my-packages;
}
)
=> { ... }
Type:
packagesFromDirectoryRecursive :: AttrSet -> AttrSet
:::
*/
packagesFromDirectoryRecursive =
# Options.
{
/*
`pkgs.callPackage`
Type:
Path -> AttrSet -> a
*/
callPackage,
/*
The directory to read package files from
Type:
Path
*/
directory,
...
}: