lib/trivial: unify & improve docstrings

- add section headers
- unify comment syntax
- add examples

Tested with:
nix-instantiate --strict --eval ./lib/tests/misc.nix
This commit is contained in:
Profpatsch 2018-07-26 00:03:51 +02:00
parent bbe31da148
commit af10842940

View file

@ -38,6 +38,8 @@ let
in in
rec { rec {
## Simple (higher order) functions
/* The identity function /* The identity function
For when you need a function that does nothing. For when you need a function that does nothing.
@ -59,7 +61,7 @@ rec {
## Named versions corresponding to some builtin operators. ## Named versions corresponding to some builtin operators.
/* Concat two strings */ /* Concatenate two lists */
concat = x: y: x ++ y; concat = x: y: x ++ y;
/* boolean or */ /* boolean or */
@ -93,10 +95,22 @@ rec {
*/ */
mergeAttrs = x: y: x // y; mergeAttrs = x: y: x // y;
# Flip the order of the arguments of a binary function. /* Flip the order of the arguments of a binary function.
Example:
flip concat [1] [2]
=> [ 2 1 ]
*/
flip = f: a: b: f b a; flip = f: a: b: f b a;
# Apply function if argument is non-null /* Apply function if argument is non-null.
Example:
mapNullable (x: x+1) null
=> null
mapNullable (x: x+1) 22
=> 23
*/
mapNullable = f: a: if isNull a then a else f a; mapNullable = f: a: if isNull a then a else f a;
# Pull in some builtins not included elsewhere. # Pull in some builtins not included elsewhere.
@ -105,20 +119,30 @@ rec {
isInt isFloat add sub lessThan isInt isFloat add sub lessThan
seq deepSeq genericClosure; seq deepSeq genericClosure;
inherit (lib.strings) fileContents;
release = fileContents ../.version; ## nixpks version strings
versionSuffix = let suffixFile = ../.version-suffix; in
if pathExists suffixFile then fileContents suffixFile else "pre-git";
# Return the Nixpkgs version number. # The current full nixpkgs version number.
version = release + versionSuffix; version = release + versionSuffix;
# The current nixpkgs version number as string.
release = lib.strings.fileContents ../.version;
# The current nixpkgs version suffix as string.
versionSuffix =
let suffixFile = ../.version-suffix;
in if pathExists suffixFile
then lib.strings.fileContents suffixFile
else "pre-git";
nixpkgsVersion = builtins.trace "`lib.nixpkgsVersion` is deprecated, use `lib.version` instead!" version; nixpkgsVersion = builtins.trace "`lib.nixpkgsVersion` is deprecated, use `lib.version` instead!" version;
# Whether we're being called by nix-shell. # Whether we're being called by nix-shell.
inNixShell = builtins.getEnv "IN_NIX_SHELL" != ""; inNixShell = builtins.getEnv "IN_NIX_SHELL" != "";
## Integer operations
# Return minimum/maximum of two numbers. # Return minimum/maximum of two numbers.
min = x: y: if x < y then x else y; min = x: y: if x < y then x else y;
max = x: y: if x > y then x else y; max = x: y: if x > y then x else y;
@ -133,6 +157,9 @@ rec {
*/ */
mod = base: int: base - (int * (builtins.div base int)); mod = base: int: base - (int * (builtins.div base int));
## Comparisons
/* C-style comparisons /* C-style comparisons
a < b, compare a b => -1 a < b, compare a b => -1
@ -162,17 +189,20 @@ rec {
cmp "fooa" "a" => -1 cmp "fooa" "a" => -1
# while # while
compare "fooa" "a" => 1 compare "fooa" "a" => 1
*/ */
splitByAndCompare = p: yes: no: a: b: splitByAndCompare = p: yes: no: a: b:
if p a if p a
then if p b then yes a b else -1 then if p b then yes a b else -1
else if p b then 1 else no a b; else if p b then 1 else no a b;
/* Reads a JSON file. */ /* Reads a JSON file. */
importJSON = path: importJSON = path:
builtins.fromJSON (builtins.readFile path); builtins.fromJSON (builtins.readFile path);
## Warnings and asserts
/* See https://github.com/NixOS/nix/issues/749. Eventually we'd like these /* See https://github.com/NixOS/nix/issues/749. Eventually we'd like these
to expand to Nix builtins that carry metadata so that Nix can filter out to expand to Nix builtins that carry metadata so that Nix can filter out
the INFO messages without parsing the message string. the INFO messages without parsing the message string.
@ -188,28 +218,36 @@ rec {
warn = msg: builtins.trace "WARNING: ${msg}"; warn = msg: builtins.trace "WARNING: ${msg}";
info = msg: builtins.trace "INFO: ${msg}"; info = msg: builtins.trace "INFO: ${msg}";
# | Add metadata about expected function arguments to a function.
# The metadata should match the format given by ## Function annotations
# builtins.functionArgs, i.e. a set from expected argument to a bool
# representing whether that argument has a default or not. /* Add metadata about expected function arguments to a function.
# setFunctionArgs : (a → b) → Map String Bool → (a → b) The metadata should match the format given by
# builtins.functionArgs, i.e. a set from expected argument to a bool
# This function is necessary because you can't dynamically create a representing whether that argument has a default or not.
# function of the { a, b ? foo, ... }: format, but some facilities setFunctionArgs : (a b) Map String Bool (a b)
# like callPackage expect to be able to query expected arguments.
This function is necessary because you can't dynamically create a
function of the { a, b ? foo, ... }: format, but some facilities
like callPackage expect to be able to query expected arguments.
*/
setFunctionArgs = f: args: setFunctionArgs = f: args:
{ # TODO: Should we add call-time "type" checking like built in? { # TODO: Should we add call-time "type" checking like built in?
__functor = self: f; __functor = self: f;
__functionArgs = args; __functionArgs = args;
}; };
# | Extract the expected function arguments from a function. /* Extract the expected function arguments from a function.
# This works both with nix-native { a, b ? foo, ... }: style This works both with nix-native { a, b ? foo, ... }: style
# functions and functions with args set with 'setFunctionArgs'. It functions and functions with args set with 'setFunctionArgs'. It
# has the same return type and semantics as builtins.functionArgs. has the same return type and semantics as builtins.functionArgs.
# setFunctionArgs : (a → b) → Map String Bool. setFunctionArgs : (a b) Map String Bool.
*/
functionArgs = f: f.__functionArgs or (builtins.functionArgs f); functionArgs = f: f.__functionArgs or (builtins.functionArgs f);
/* Check whether something is a function or something
annotated with function args.
*/
isFunction = f: builtins.isFunction f || isFunction = f: builtins.isFunction f ||
(f ? __functor && isFunction (f.__functor f)); (f ? __functor && isFunction (f.__functor f));
} }