diff options
Diffstat (limited to 'nixpkgs/lib/trivial.nix')
| -rw-r--r-- | nixpkgs/lib/trivial.nix | 941 |
1 files changed, 727 insertions, 214 deletions
diff --git a/nixpkgs/lib/trivial.nix b/nixpkgs/lib/trivial.nix index c197822a4f8e..936ad207c03d 100644 --- a/nixpkgs/lib/trivial.nix +++ b/nixpkgs/lib/trivial.nix @@ -16,59 +16,114 @@ in { ## Simple (higher order) functions - /* The identity function - For when you need a function that does “nothing”. + /** + The identity function + For when you need a function that does “nothing”. - Type: id :: a -> a + + # Inputs + + `x` + + : The value to return + + # Type + + ``` + id :: a -> a + ``` */ - id = - # The value to return - x: x; + id = x: x; + + /** + The constant function + + Ignores the second argument. If called with only one argument, + constructs a function that always returns a static value. + + + # Inputs + + `x` + + : Value to return + + `y` + + : Value to ignore + + # Type + + ``` + const :: a -> b -> a + ``` - /* The constant function + # Examples + :::{.example} + ## `lib.trivial.const` usage example - Ignores the second argument. If called with only one argument, - constructs a function that always returns a static value. + ```nix + let f = const 5; in f 10 + => 5 + ``` - Type: const :: a -> b -> a - Example: - let f = const 5; in f 10 - => 5 + ::: */ const = - # Value to return x: - # Value to ignore y: x; - /* Pipes a value through a list of functions, left to right. + /** + Pipes a value through a list of functions, left to right. - Type: pipe :: a -> [<functions>] -> <return type of last function> - Example: - pipe 2 [ - (x: x + 2) # 2 + 2 = 4 - (x: x * 2) # 4 * 2 = 8 - ] - => 8 + # Inputs - # ideal to do text transformations - pipe [ "a/b" "a/c" ] [ + `value` - # create the cp command - (map (file: ''cp "${src}/${file}" $out\n'')) + : Value to start piping. - # concatenate all commands into one string - lib.concatStrings + `fns` - # make that string into a nix derivation - (pkgs.runCommand "copy-to-out" {}) + : List of functions to apply sequentially. - ] - => <drv which copies all files to $out> + # Type - The output type of each function has to be the input type - of the next function, and the last function returns the - final value. + ``` + pipe :: a -> [<functions>] -> <return type of last function> + ``` + + # Examples + :::{.example} + ## `lib.trivial.pipe` usage example + + ```nix + pipe 2 [ + (x: x + 2) # 2 + 2 = 4 + (x: x * 2) # 4 * 2 = 8 + ] + => 8 + + # ideal to do text transformations + pipe [ "a/b" "a/c" ] [ + + # create the cp command + (map (file: ''cp "${src}/${file}" $out\n'')) + + # concatenate all commands into one string + lib.concatStrings + + # make that string into a nix derivation + (pkgs.runCommand "copy-to-out" {}) + + ] + => <drv which copies all files to $out> + + The output type of each function has to be the input type + of the next function, and the last function returns the + final value. + ``` + + ::: */ pipe = builtins.foldl' (x: f: f x); @@ -79,71 +134,197 @@ in { ## Named versions corresponding to some builtin operators. - /* Concatenate two lists + /** + Concatenate two lists + + + # Inputs + + `x` + + : 1\. Function argument + + `y` + + : 2\. Function argument - Type: concat :: [a] -> [a] -> [a] + # Type - Example: - concat [ 1 2 ] [ 3 4 ] - => [ 1 2 3 4 ] + ``` + concat :: [a] -> [a] -> [a] + ``` + + # Examples + :::{.example} + ## `lib.trivial.concat` usage example + + ```nix + concat [ 1 2 ] [ 3 4 ] + => [ 1 2 3 4 ] + ``` + + ::: */ concat = x: y: x ++ y; - /* boolean “or” */ + /** + boolean “or” + + + # Inputs + + `x` + + : 1\. Function argument + + `y` + + : 2\. Function argument + */ or = x: y: x || y; - /* boolean “and” */ + /** + boolean “and” + + + # Inputs + + `x` + + : 1\. Function argument + + `y` + + : 2\. Function argument + */ and = x: y: x && y; - /* bitwise “not” */ + /** + bitwise “not” + */ bitNot = builtins.sub (-1); - /* Convert a boolean to a string. + /** + Convert a boolean to a string. + + This function uses the strings "true" and "false" to represent + boolean values. Calling `toString` on a bool instead returns "1" + and "" (sic!). + + + # Inputs + + `b` + + : 1\. Function argument - This function uses the strings "true" and "false" to represent - boolean values. Calling `toString` on a bool instead returns "1" - and "" (sic!). + # Type - Type: boolToString :: bool -> string + ``` + boolToString :: bool -> string + ``` */ boolToString = b: if b then "true" else "false"; - /* Merge two attribute sets shallowly, right side trumps left + /** + Merge two attribute sets shallowly, right side trumps left + + mergeAttrs :: attrs -> attrs -> attrs + + + # Inputs + + `x` + + : Left attribute set + + `y` + + : Right attribute set (higher precedence for equal keys) - mergeAttrs :: attrs -> attrs -> attrs - Example: - mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; } - => { a = 1; b = 3; c = 4; } + # Examples + :::{.example} + ## `lib.trivial.mergeAttrs` usage example + + ```nix + mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; } + => { a = 1; b = 3; c = 4; } + ``` + + ::: */ mergeAttrs = - # Left attribute set x: - # Right attribute set (higher precedence for equal keys) y: x // y; - /* Flip the order of the arguments of a binary function. + /** + Flip the order of the arguments of a binary function. + + + # Inputs + + `f` + + : 1\. Function argument + + `a` + + : 2\. Function argument - Type: flip :: (a -> b -> c) -> (b -> a -> c) + `b` - Example: - flip concat [1] [2] - => [ 2 1 ] + : 3\. Function argument + + # Type + + ``` + flip :: (a -> b -> c) -> (b -> a -> c) + ``` + + # Examples + :::{.example} + ## `lib.trivial.flip` usage example + + ```nix + flip concat [1] [2] + => [ 2 1 ] + ``` + + ::: */ flip = f: a: b: f b a; - /* Apply function if the supplied argument is non-null. + /** + Apply function if the supplied argument is non-null. + + + # Inputs - Example: - mapNullable (x: x+1) null - => null - mapNullable (x: x+1) 22 - => 23 + `f` + + : Function to call + + `a` + + : Argument to check for null before passing it to `f` + + + # Examples + :::{.example} + ## `lib.trivial.mapNullable` usage example + + ```nix + mapNullable (x: x+1) null + => null + mapNullable (x: x+1) 22 + => 23 + ``` + + ::: */ mapNullable = - # Function to call f: - # Argument to check for null before passing it to `f` a: if a == null then a else f a; # Pull in some builtins not included elsewhere. @@ -155,57 +336,84 @@ in { ## nixpkgs version strings - /* Returns the current full nixpkgs version number. */ + /** + Returns the current full nixpkgs version number. + */ version = release + versionSuffix; - /* Returns the current nixpkgs release number as string. */ + /** + Returns the current nixpkgs release number as string. + */ release = lib.strings.fileContents ./.version; - /* The latest release that is supported, at the time of release branch-off, - if applicable. + /** + The latest release that is supported, at the time of release branch-off, + if applicable. - Ideally, out-of-tree modules should be able to evaluate cleanly with all - supported Nixpkgs versions (master, release and old release until EOL). - So if possible, deprecation warnings should take effect only when all - out-of-tree expressions/libs/modules can upgrade to the new way without - losing support for supported Nixpkgs versions. + Ideally, out-of-tree modules should be able to evaluate cleanly with all + supported Nixpkgs versions (master, release and old release until EOL). + So if possible, deprecation warnings should take effect only when all + out-of-tree expressions/libs/modules can upgrade to the new way without + losing support for supported Nixpkgs versions. - This release number allows deprecation warnings to be implemented such that - they take effect as soon as the oldest release reaches end of life. */ + This release number allows deprecation warnings to be implemented such that + they take effect as soon as the oldest release reaches end of life. + */ oldestSupportedRelease = # Update on master only. Do not backport. 2311; - /* Whether a feature is supported in all supported releases (at the time of - release branch-off, if applicable). See `oldestSupportedRelease`. */ + /** + Whether a feature is supported in all supported releases (at the time of + release branch-off, if applicable). See `oldestSupportedRelease`. + + + # Inputs + + `release` + + : Release number of feature introduction as an integer, e.g. 2111 for 21.11. + Set it to the upcoming release, matching the nixpkgs/.version file. + */ isInOldestRelease = - /* Release number of feature introduction as an integer, e.g. 2111 for 21.11. - Set it to the upcoming release, matching the nixpkgs/.version file. - */ release: release <= lib.trivial.oldestSupportedRelease; - /* Returns the current nixpkgs release code name. + /** + Returns the current nixpkgs release code name. - On each release the first letter is bumped and a new animal is chosen - starting with that new letter. + On each release the first letter is bumped and a new animal is chosen + starting with that new letter. */ codeName = "Uakari"; - /* Returns the current nixpkgs version suffix as string. */ + /** + Returns the current nixpkgs version suffix as string. + */ versionSuffix = let suffixFile = ../.version-suffix; in if pathExists suffixFile then lib.strings.fileContents suffixFile else "pre-git"; - /* Attempts to return the the current revision of nixpkgs and - returns the supplied default value otherwise. + /** + Attempts to return the the current revision of nixpkgs and + returns the supplied default value otherwise. + + + # Inputs + + `default` - Type: revisionWithDefault :: string -> string + : Default value to return if revision can not be determined + + # Type + + ``` + revisionWithDefault :: string -> string + ``` */ revisionWithDefault = - # Default value to return if revision can not be determined default: let revisionFile = "${toString ./..}/.git-revision"; @@ -217,47 +425,115 @@ in { nixpkgsVersion = warn "lib.nixpkgsVersion is a deprecated alias of lib.version." version; - /* Determine whether the function is being called from inside a Nix - shell. + /** + Determine whether the function is being called from inside a Nix + shell. - Type: inNixShell :: bool + # Type + + ``` + inNixShell :: bool + ``` */ inNixShell = builtins.getEnv "IN_NIX_SHELL" != ""; - /* Determine whether the function is being called from inside pure-eval mode - by seeing whether `builtins` contains `currentSystem`. If not, we must be in - pure-eval mode. + /** + Determine whether the function is being called from inside pure-eval mode + by seeing whether `builtins` contains `currentSystem`. If not, we must be in + pure-eval mode. + + # Type - Type: inPureEvalMode :: bool + ``` + inPureEvalMode :: bool + ``` */ inPureEvalMode = ! builtins ? currentSystem; ## Integer operations - /* Return minimum of two numbers. */ + /** + Return minimum of two numbers. + + + # Inputs + + `x` + + : 1\. Function argument + + `y` + + : 2\. Function argument + */ min = x: y: if x < y then x else y; - /* Return maximum of two numbers. */ + /** + Return maximum of two numbers. + + + # Inputs + + `x` + + : 1\. Function argument + + `y` + + : 2\. Function argument + */ max = x: y: if x > y then x else y; - /* Integer modulus + /** + Integer modulus + + + # Inputs + + `base` + + : 1\. Function argument + + `int` + + : 2\. Function argument + - Example: - mod 11 10 - => 1 - mod 1 10 - => 1 + # Examples + :::{.example} + ## `lib.trivial.mod` usage example + + ```nix + mod 11 10 + => 1 + mod 1 10 + => 1 + ``` + + ::: */ 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 => 0 + a > b, compare a b => 1 + + + # Inputs + + `a` + + : 1\. Function argument + + `b` - a < b, compare a b => -1 - a == b, compare a b => 0 - a > b, compare a b => 1 + : 2\. Function argument */ compare = a: b: if a < b @@ -266,50 +542,100 @@ in { then 1 else 0; - /* Split type into two subtypes by predicate `p`, take all elements - of the first subtype to be less than all the elements of the - second subtype, compare elements of a single subtype with `yes` - and `no` respectively. + /** + Split type into two subtypes by predicate `p`, take all elements + of the first subtype to be less than all the elements of the + second subtype, compare elements of a single subtype with `yes` + and `no` respectively. + + + # Inputs + + `p` + + : Predicate + + `yes` + + : Comparison function if predicate holds for both values + + `no` - Type: (a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int) + : Comparison function if predicate holds for neither value - Example: - let cmp = splitByAndCompare (hasPrefix "foo") compare compare; in + `a` - cmp "a" "z" => -1 - cmp "fooa" "fooz" => -1 + : First value to compare - cmp "f" "a" => 1 - cmp "fooa" "a" => -1 - # while - compare "fooa" "a" => 1 + `b` + + : Second value to compare + + # Type + + ``` + (a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int) + ``` + + # Examples + :::{.example} + ## `lib.trivial.splitByAndCompare` usage example + + ```nix + let cmp = splitByAndCompare (hasPrefix "foo") compare compare; in + + cmp "a" "z" => -1 + cmp "fooa" "fooz" => -1 + + cmp "f" "a" => 1 + cmp "fooa" "a" => -1 + # while + compare "fooa" "a" => 1 + ``` + + ::: */ splitByAndCompare = - # Predicate - p: - # Comparison function if predicate holds for both values - yes: - # Comparison function if predicate holds for neither value - no: - # First value to compare - a: - # Second value to compare - b: + p: yes: no: a: b: if p a then if p b then yes a b else -1 else if p b then 1 else no a b; - /* Reads a JSON file. + /** + Reads a JSON file. - Type: importJSON :: path -> any + + # Inputs + + `path` + + : 1\. Function argument + + # Type + + ``` + importJSON :: path -> any + ``` */ importJSON = path: builtins.fromJSON (builtins.readFile path); - /* Reads a TOML file. + /** + Reads a TOML file. + + + # Inputs - Type: importTOML :: path -> any + `path` + + : 1\. Function argument + + # Type + + ``` + importTOML :: path -> any + ``` */ importTOML = path: builtins.fromTOML (builtins.readFile path); @@ -329,7 +655,7 @@ in { # TODO: figure out a clever way to integrate location information from # something like __unsafeGetAttrPos. - /* + /** Print a warning before returning the second argument. This function behaves like `builtins.trace`, but requires a string message and formats it as a warning, including the `warning: ` prefix. @@ -337,28 +663,80 @@ in { To get a call stack trace and abort evaluation, set the environment variable `NIX_ABORT_ON_WARN=true` and set the Nix options `--option pure-eval false --show-trace` - Type: string -> a -> a + # Inputs + + `msg` + + : Warning message to print. + + `val` + + : Value to return as-is. + + # Type + + ``` + string -> a -> a + ``` */ warn = if lib.elem (builtins.getEnv "NIX_ABORT_ON_WARN") ["1" "true" "yes"] then msg: builtins.trace "[1;31mwarning: ${msg}[0m" (abort "NIX_ABORT_ON_WARN=true; warnings are treated as unrecoverable errors.") else msg: builtins.trace "[1;31mwarning: ${msg}[0m"; - /* + /** Like warn, but only warn when the first argument is `true`. - Type: bool -> string -> a -> a + + # Inputs + + `cond` + + : 1\. Function argument + + `msg` + + : 2\. Function argument + + `val` + + : Value to return as-is. + + # Type + + ``` + bool -> string -> a -> a + ``` */ warnIf = cond: msg: if cond then warn msg else x: x; - /* + /** Like warnIf, but negated (warn if the first argument is `false`). - Type: bool -> string -> a -> a + + # Inputs + + `cond` + + : 1\. Function argument + + `msg` + + : 2\. Function argument + + `val` + + : Value to return as-is. + + # Type + + ``` + bool -> string -> a -> a + ``` */ warnIfNot = cond: msg: if cond then x: x else warn msg; - /* + /** Like the `assert b; e` expression, but with a custom error message and without the semicolon. @@ -369,33 +747,95 @@ in { Calls can be juxtaposed using function application, as `(r: r) a = a`, so `(r: r) (r: r) a = a`, and so forth. - Type: bool -> string -> a -> a - Example: + # Inputs + + `cond` + + : 1\. Function argument - throwIfNot (lib.isList overlays) "The overlays argument to nixpkgs must be a list." - lib.foldr (x: throwIfNot (lib.isFunction x) "All overlays passed to nixpkgs must be functions.") (r: r) overlays - pkgs + `msg` + : 2\. Function argument + + # Type + + ``` + bool -> string -> a -> a + ``` + + # Examples + :::{.example} + ## `lib.trivial.throwIfNot` usage example + + ```nix + throwIfNot (lib.isList overlays) "The overlays argument to nixpkgs must be a list." + lib.foldr (x: throwIfNot (lib.isFunction x) "All overlays passed to nixpkgs must be functions.") (r: r) overlays + pkgs + ``` + + ::: */ throwIfNot = cond: msg: if cond then x: x else throw msg; - /* + /** Like throwIfNot, but negated (throw if the first argument is `true`). - Type: bool -> string -> a -> a + + # Inputs + + `cond` + + : 1\. Function argument + + `msg` + + : 2\. Function argument + + # Type + + ``` + bool -> string -> a -> a + ``` */ throwIf = cond: msg: if cond then throw msg else x: x; - /* Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise. + /** + Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise. + + + # Inputs + + `msg` - Example: - let colorVariants = ["bright" "dark" "black"] - in checkListOfEnum "color variants" [ "standard" "light" "dark" ] colorVariants; - => - error: color variants: bright, black unexpected; valid ones: standard, light, dark + : 1\. Function argument - Type: String -> List ComparableVal -> List ComparableVal -> a -> a + `valid` + + : 2\. Function argument + + `given` + + : 3\. Function argument + + # Type + + ``` + String -> List ComparableVal -> List ComparableVal -> a -> a + ``` + + # Examples + :::{.example} + ## `lib.trivial.checkListOfEnum` usage example + + ```nix + let colorVariants = ["bright" "dark" "black"] + in checkListOfEnum "color variants" [ "standard" "light" "dark" ] colorVariants; + => + error: color variants: bright, black unexpected; valid ones: standard, light, dark + ``` + + ::: */ checkListOfEnum = msg: valid: given: let @@ -410,15 +850,27 @@ in { ## Function annotations - /* Add metadata about expected function arguments to a function. - The metadata should match the format given by - builtins.functionArgs, i.e. a set from expected argument to a bool - representing whether that argument has a default or not. - setFunctionArgs : (a → b) → Map String Bool → (a → b) + /** + Add metadata about expected function arguments to a function. + The metadata should match the format given by + builtins.functionArgs, i.e. a set from expected argument to a bool + representing whether that argument has a default or not. + setFunctionArgs : (a → b) → Map String Bool → (a → b) - 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. + 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. + + + # Inputs + + `f` + + : 1\. Function argument + + `args` + + : 2\. Function argument */ setFunctionArgs = f: args: { # TODO: Should we add call-time "type" checking like built in? @@ -426,84 +878,133 @@ in { __functionArgs = args; }; - /* Extract the expected function arguments from a function. - This works both with nix-native { a, b ? foo, ... }: style - functions and functions with args set with 'setFunctionArgs'. It - has the same return type and semantics as builtins.functionArgs. - setFunctionArgs : (a → b) → Map String Bool. + /** + Extract the expected function arguments from a function. + This works both with nix-native { a, b ? foo, ... }: style + functions and functions with args set with 'setFunctionArgs'. It + has the same return type and semantics as builtins.functionArgs. + setFunctionArgs : (a → b) → Map String Bool. + + + # Inputs + + `f` + + : 1\. Function argument */ functionArgs = f: if f ? __functor then f.__functionArgs or (functionArgs (f.__functor f)) else builtins.functionArgs f; - /* Check whether something is a function or something - annotated with function args. + /** + Check whether something is a function or something + annotated with function args. + + + # Inputs + + `f` + + : 1\. Function argument */ isFunction = f: builtins.isFunction f || (f ? __functor && isFunction (f.__functor f)); - /* + /** `mirrorFunctionArgs f g` creates a new function `g'` with the same behavior as `g` (`g' x == g x`) but its function arguments mirroring `f` (`lib.functionArgs g' == lib.functionArgs f`). - Type: - mirrorFunctionArgs :: (a -> b) -> (a -> c) -> (a -> c) - - Example: - addab = {a, b}: a + b - addab { a = 2; b = 4; } - => 6 - lib.functionArgs addab - => { a = false; b = false; } - addab1 = attrs: addab attrs + 1 - addab1 { a = 2; b = 4; } - => 7 - lib.functionArgs addab1 - => { } - addab1' = lib.mirrorFunctionArgs addab addab1 - addab1' { a = 2; b = 4; } - => 7 - lib.functionArgs addab1' - => { a = false; b = false; } + + # Inputs + + `f` + + : Function to provide the argument metadata + + `g` + + : Function to set the argument metadata to + + # Type + + ``` + mirrorFunctionArgs :: (a -> b) -> (a -> c) -> (a -> c) + ``` + + # Examples + :::{.example} + ## `lib.trivial.mirrorFunctionArgs` usage example + + ```nix + addab = {a, b}: a + b + addab { a = 2; b = 4; } + => 6 + lib.functionArgs addab + => { a = false; b = false; } + addab1 = attrs: addab attrs + 1 + addab1 { a = 2; b = 4; } + => 7 + lib.functionArgs addab1 + => { } + addab1' = lib.mirrorFunctionArgs addab addab1 + addab1' { a = 2; b = 4; } + => 7 + lib.functionArgs addab1' + => { a = false; b = false; } + ``` + + ::: */ mirrorFunctionArgs = - # Function to provide the argument metadata f: let fArgs = functionArgs f; in - # Function to set the argument metadata to g: setFunctionArgs g fArgs; - /* + /** Turns any non-callable values into constant functions. Returns callable values as is. - Example: - nix-repl> lib.toFunction 1 2 - 1 + # Inputs + + `v` + + : Any value + + + # Examples + :::{.example} + ## `lib.trivial.toFunction` usage example + + ```nix + nix-repl> lib.toFunction 1 2 + 1 - nix-repl> lib.toFunction (x: x + 1) 2 - 3 + nix-repl> lib.toFunction (x: x + 1) 2 + 3 + ``` + + ::: */ toFunction = - # Any value v: if isFunction v then v else k: v; - /* Convert the given positive integer to a string of its hexadecimal - representation. For example: + /** + Convert the given positive integer to a string of its hexadecimal + representation. For example: - toHexString 0 => "0" + toHexString 0 => "0" - toHexString 16 => "10" + toHexString 16 => "10" - toHexString 250 => "FA" + toHexString 250 => "FA" */ toHexString = let hexDigits = { @@ -520,14 +1021,26 @@ in { else hexDigits.${toString d}; in i: lib.concatMapStrings toHexDigit (toBaseDigits 16 i); - /* `toBaseDigits base i` converts the positive integer i to a list of its - digits in the given base. For example: + /** + `toBaseDigits base i` converts the positive integer i to a list of its + digits in the given base. For example: + + toBaseDigits 10 123 => [ 1 2 3 ] + + toBaseDigits 2 6 => [ 1 1 0 ] + + toBaseDigits 16 250 => [ 15 10 ] + + + # Inputs + + `base` - toBaseDigits 10 123 => [ 1 2 3 ] + : 1\. Function argument - toBaseDigits 2 6 => [ 1 1 0 ] + `i` - toBaseDigits 16 250 => [ 15 10 ] + : 2\. Function argument */ toBaseDigits = base: i: let |