swendel/nixpkgs
1
0
Fork 0
mirror of https://github.com/SebastianWendel/nixpkgs.git synced 2024-11-06 10:16:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge #157336: lib: Improve library docs

Browse source
This commit is contained in:
Vladimír Čunát 2022-02-06 19:13:04 +01:00
parent a2cabcb38b 1e1396aafc
commit 8348c7623a
No known key found for this signature in database
GPG key ID: E747DF1F9575A3AA
2 changed files with 72 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

115
lib/sources.nix
View file

@ -20,17 +20,26 @@ let
readFile
;
# Returns the type of a path: regular (for file), symlink, or directory
pathType = p: getAttr (baseNameOf p) (readDir (dirOf p));
/*
Returns the type of a path: regular (for file), symlink, or directory.
*/
pathType = path: getAttr (baseNameOf path) (readDir (dirOf path));
# Returns true if the path exists and is a directory, false otherwise
pathIsDirectory = p: if pathExists p then (pathType p) == "directory" else false;
/*
Returns true if the path exists and is a directory, false otherwise.
*/
pathIsDirectory = path: if pathExists path then (pathType path) == "directory" else false;
# Returns true if the path exists and is a regular file, false otherwise
pathIsRegularFile = p: if pathExists p then (pathType p) == "regular" else false;
/*
Returns true if the path exists and is a regular file, false otherwise.
*/
pathIsRegularFile = path: if pathExists path then (pathType path) == "regular" else false;
# Bring in a path as a source, filtering out all Subversion and CVS
# directories, as well as backup files (*~).
/*
A basic filter for `cleanSourceWith` that removes
directories of version control system, backup files (*~)
and some generated files.
*/
cleanSourceFilter = name: type: let baseName = baseNameOf (toString name); in ! (
# Filter out version control software files/directories
(baseName == ".git" || type == "directory" && (baseName == ".svn" || baseName == "CVS" || baseName == ".hg")) ||
@ -48,43 +57,48 @@ let
(type == "unknown")
);
# Filters a source tree removing version control files and directories using cleanSourceWith
#
# Example:
# cleanSource ./.
/*
Filters a source tree removing version control files and directories using cleanSourceFilter.
Example:
cleanSource ./.
*/
cleanSource = src: cleanSourceWith { filter = cleanSourceFilter; inherit src; };
# Like `builtins.filterSource`, except it will compose with itself,
# allowing you to chain multiple calls together without any
# intermediate copies being put in the nix store.
#
# lib.cleanSourceWith {
# filter = f;
# src = lib.cleanSourceWith {
# filter = g;
# src = ./.;
# };
# }
# # Succeeds!
#
# builtins.filterSource f (builtins.filterSource g ./.)
# # Fails!
#
# Parameters:
#
# src: A path or cleanSourceWith result to filter and/or rename.
#
# filter: A function (path -> type -> bool)
# Optional with default value: constant true (include everything)
# The function will be combined with the && operator such
# that src.filter is called lazily.
# For implementing a filter, see
# https://nixos.org/nix/manual/#builtin-filterSource
#
# name: Optional name to use as part of the store path.
# This defaults to `src.name` or otherwise `"source"`.
#
cleanSourceWith = { filter ? _path: _type: true, src, name ? null }:
/*
Like `builtins.filterSource`, except it will compose with itself,
allowing you to chain multiple calls together without any
intermediate copies being put in the nix store.
Example:
lib.cleanSourceWith {
filter = f;
src = lib.cleanSourceWith {
filter = g;
src = ./.;
};
}
# Succeeds!
builtins.filterSource f (builtins.filterSource g ./.)
# Fails!
*/
cleanSourceWith =
{
# A path or cleanSourceWith result to filter and/or rename.
src,
# Optional with default value: constant true (include everything)
# The function will be combined with the && operator such
# that src.filter is called lazily.
# For implementing a filter, see
# https://nixos.org/nix/manual/#builtin-filterSource
# Type: A function (path -> type -> bool)
filter ? _path: _type: true,
# Optional name to use as part of the store path.
# This defaults to `src.name` or otherwise `"source"`.
name ? null
}:
let
orig = toSourceAttributes src;
in fromSourceAttributes {
@ -116,9 +130,11 @@ let
satisfiesSubpathInvariant = src ? satisfiesSubpathInvariant && src.satisfiesSubpathInvariant;
};
# Filter sources by a list of regular expressions.
#
# E.g. `src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]`
/*
Filter sources by a list of regular expressions.
Example: src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]
*/
sourceByRegex = src: regexes:
let
isFiltered = src ? _isLibCleanSourceWith;
@ -153,8 +169,11 @@ let
pathIsGitRepo = path: (tryEval (commitIdFromGitRepo path)).success;
# Get the commit id of a git repo
# Example: commitIdFromGitRepo <nixpkgs/.git>
/*
Get the commit id of a git repo.
Example: commitIdFromGitRepo <nixpkgs/.git>
*/
commitIdFromGitRepo =
let readCommitFromFile = file: path:
let fileName = toString path + "/" + file;

10
lib/trivial.nix
View file

@ -61,11 +61,11 @@ rec {
pipe = val: functions:
let reverseApply = x: f: f x;
in builtins.foldl' reverseApply val functions;
/* note please don’t add a function like `compose = flip pipe`.
This would confuse users, because the order of the functions
in the list is not clear. With pipe, it’s obvious that it
goes first-to-last. With `compose`, not so much.
*/
# note please don’t add a function like `compose = flip pipe`.
# This would confuse users, because the order of the functions
# in the list is not clear. With pipe, it’s obvious that it
# goes first-to-last. With `compose`, not so much.
## Named versions corresponding to some builtin operators.