diff options
| -rw-r--r-- | lib/filesystem.nix | 234 |
1 files changed, 167 insertions, 67 deletions
diff --git a/lib/filesystem.nix b/lib/filesystem.nix index c416db02eb57..5a78bcca4ebd 100644 --- a/lib/filesystem.nix +++ b/lib/filesystem.nix @@ -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 + + `path` + + : 1\. Function argument + + # Type + + ``` + pathIsRegularFile :: Path -> Bool + ``` + + # Examples + :::{.example} + ## `lib.filesystem.pathIsRegularFile` usage example + + ```nix + pathIsRegularFile /. + => false - pathIsRegularFile /this/does/not/exist - => false + pathIsRegularFile /this/does/not/exist + => false - pathIsRegularFile /some/file.nix - => true + 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, ... }: |