diff --git a/lib/attrsets.nix b/lib/attrsets.nix index 0e79a3b5a39b..a69fc49e5dca 100644 --- a/lib/attrsets.nix +++ b/lib/attrsets.nix @@ -201,7 +201,7 @@ rec { # Type ``` - attrsets.longestValidPathPrefix :: [String] -> Value -> [String] + longestValidPathPrefix :: [String] -> Value -> [String] ``` # Examples diff --git a/lib/debug.nix b/lib/debug.nix index 775db5a32997..79b1d61dfcb8 100644 --- a/lib/debug.nix +++ b/lib/debug.nix @@ -167,7 +167,7 @@ rec { ```nix trace { a.b.c = 3; } null - trace: { a = ; } + trace: { a = ; } => null traceSeq { a.b.c = 3; } null trace: { a = { b = { c = 3; }; }; } @@ -257,6 +257,23 @@ rec { `v` : Value to trace + + # Type + + ``` + traceValSeqFn :: (a -> b) -> a -> a + ``` + + # Examples + :::{.example} + ## `lib.debug.traceValSeqFn` usage example + + ```nix + traceValSeqFn (v: v // { d = "foo";}) { a.b.c = 3; } + trace: { a = { b = { c = 3; }; }; d = "foo"; } + => { a = { ... }; } + + ::: */ traceValSeqFn = f: v: traceValFn f (builtins.deepSeq v v); @@ -268,6 +285,24 @@ rec { `v` : Value to trace + + # Type + + ``` + traceValSeq :: a -> a + ``` + + # Examples + :::{.example} + ## `lib.debug.traceValSeq` usage example + + ```nix + traceValSeq { a.b.c = 3; } + trace: { a = { b = { c = 3; }; }; } + => { a = { ... }; } + ``` + + ::: */ traceValSeq = traceValSeqFn id; @@ -288,6 +323,24 @@ rec { `v` : Value to trace + + # Type + + ``` + traceValSeqNFn :: (a -> b) -> int -> a -> a + ``` + + # Examples + :::{.example} + ## `lib.debug.traceValSeqNFn` usage example + + ```nix + traceValSeqNFn (v: v // { d = "foo";}) 2 { a.b.c = 3; } + trace: { a = { b = {…}; }; d = "foo"; } + => { a = { ... }; } + ``` + + ::: */ traceValSeqNFn = f: depth: v: @@ -305,6 +358,24 @@ rec { `v` : Value to trace + + # Type + + ``` + traceValSeqN :: int -> a -> a + ``` + + # Examples + :::{.example} + ## `lib.debug.traceValSeqN` usage example + + ```nix + traceValSeqN 2 { a.b.c = 3; } + trace: { a = { b = {…}; }; } + => { a = { ... }; } + ``` + + ::: */ traceValSeqN = traceValSeqNFn id; @@ -333,6 +404,12 @@ rec { : 4\. Function argument + # Type + + ``` + traceFnSeqN :: int -> string -> (a -> b) -> a -> b + ``` + # Examples :::{.example} ## `lib.debug.traceFnSeqN` usage example @@ -340,7 +417,7 @@ rec { ```nix traceFnSeqN 2 "id" (x: x) { a.b.c = 3; } trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; } - => { a.b.c = 3; } + => { a = { ... }; } ``` ::: diff --git a/lib/derivations.nix b/lib/derivations.nix index b092bd3b6f98..f207134708be 100644 --- a/lib/derivations.nix +++ b/lib/derivations.nix @@ -233,6 +233,12 @@ in `drv` : The derivation to wrap. + # Type + + ``` + warnOnInstantiate :: string -> Derivation -> Derivation + ``` + # Examples :::{.example} ## `lib.derivations.warnOnInstantiate` usage example diff --git a/lib/filesystem.nix b/lib/filesystem.nix index 98a8862d60b8..144fee73738b 100644 --- a/lib/filesystem.nix +++ b/lib/filesystem.nix @@ -302,16 +302,6 @@ in - Other files are ignored, including symbolic links to directories and to regular `.nix` files; this is because nixlang code cannot distinguish the type of a link's target. - # Type - - ``` - packagesFromDirectoryRecursive :: { - callPackage :: Path -> {} -> a, - newScope? :: AttrSet -> scope, - directory :: Path, - } -> AttrSet - ``` - # Inputs `callPackage` @@ -326,6 +316,16 @@ in `directory` : The directory to read package files from. + # Type + + ``` + packagesFromDirectoryRecursive :: { + callPackage :: Path -> {} -> a, + newScope? :: AttrSet -> scope, + directory :: Path, + } -> AttrSet + ``` + # Examples :::{.example} ## Basic use of `lib.packagesFromDirectoryRecursive` @@ -450,12 +450,6 @@ in /** Append `/default.nix` if the passed path is a directory. - # Type - - ``` - resolveDefaultNix :: (Path | String) -> (Path | String) - ``` - # Inputs A single argument which can be a [path](https://nix.dev/manual/nix/stable/language/types#type-path) value or a string containing an absolute path. @@ -466,6 +460,12 @@ in Furthermore, if the input is a string that ends with `/`, `default.nix` is appended to it. Otherwise, the input is returned unchanged. + # Type + + ``` + resolveDefaultNix :: (Path | String) -> (Path | String) + ``` + # Examples :::{.example} ## `lib.filesystem.resolveDefaultNix` usage example diff --git a/lib/fixed-points.nix b/lib/fixed-points.nix index 6d50a00fc4a1..a29ed105d4a6 100644 --- a/lib/fixed-points.nix +++ b/lib/fixed-points.nix @@ -108,6 +108,12 @@ rec { `f` : 1\. Function argument + + # Type + + ``` + fix' :: (a -> a) -> a + ``` */ fix' = f: diff --git a/lib/lists.nix b/lib/lists.nix index 41eba34f93c5..5fa31dd29ae8 100644 --- a/lib/lists.nix +++ b/lib/lists.nix @@ -423,6 +423,12 @@ rec { : 1\. Function argument + # Type + + ``` + flatten :: [a | [a | [a | ...]]] -> [a] + ``` + # Examples :::{.example} ## `lib.lists.flatten` usage example @@ -823,6 +829,12 @@ rec { : 1\. Function argument + # Type + + ``` + toList :: (a | [a]) -> [a] + ``` + # Examples :::{.example} ## `lib.lists.toList` usage example @@ -962,6 +974,12 @@ rec { : 4\. Function argument + # Type + + ``` + groupBy' :: (b -> a -> b) -> b -> (a -> string) -> [a] -> Map string b + ``` + # Examples :::{.example} ## `lib.lists.groupBy'` usage example @@ -1128,6 +1146,12 @@ rec { : 3\. Function argument + # Type + + ``` + listDfs :: bool -> (a -> a -> bool) -> [a] -> attrs + ``` + # Examples :::{.example} ## `lib.lists.listDfs` usage example @@ -1193,6 +1217,12 @@ rec { : 2\. Function argument + # Type + + ``` + toposort :: (a -> a -> bool) -> [a] -> attrs + ``` + # Examples :::{.example} ## `lib.lists.toposort` usage example @@ -1364,6 +1394,12 @@ rec { : The second list + # Type + + ``` + compareLists :: (a -> a -> int) -> [a] -> [a] -> int + ``` + # Examples :::{.example} ## `lib.lists.compareLists` usage examples @@ -1403,6 +1439,12 @@ rec { : 1\. Function argument + # Type + + ``` + naturalSort :: [str] -> [str] + ``` + # Examples :::{.example} ## `lib.lists.naturalSort` usage example @@ -1940,6 +1982,12 @@ rec { : Second list + # Type + + ``` + intersectLists :: [a] -> [a] -> [a] + ``` + # Examples :::{.example} ## `lib.lists.intersectLists` usage example @@ -1968,6 +2016,12 @@ rec { : Second list + # Type + + ``` + subtractLists :: [a] -> [a] -> [a] + ``` + # Examples :::{.example} ## `lib.lists.subtractLists` usage example @@ -1994,6 +2048,12 @@ rec { `b` : 2\. Function argument + + # Type + + ``` + mutuallyExclusive :: [a] -> [a] -> bool + ``` */ mutuallyExclusive = a: b: length a == 0 || !(any (x: elem x a) b); @@ -2007,6 +2067,12 @@ rec { : Attribute set with attributes that are lists + # Type + + ``` + concatAttrValues :: (Map string a) -> [a] + ``` + # Examples :::{.example} ## `lib.concatAttrValues` usage example diff --git a/lib/meta.nix b/lib/meta.nix index 62b40344c46b..02dc3744b19d 100644 --- a/lib/meta.nix +++ b/lib/meta.nix @@ -39,6 +39,12 @@ rec { : 2\. Function argument + # Type + + ``` + addMetaAttrs :: attrs -> Derivation -> Derivation + ``` + # Examples :::{.example} ## `lib.meta.addMetaAttrs` usage example @@ -66,6 +72,12 @@ rec { `drv` : 1\. Function argument + + # Type + + ``` + dontDistribute :: Derivation -> Derivation + ``` */ dontDistribute = drv: addMetaAttrs { hydraPlatforms = [ ]; } drv; @@ -85,6 +97,12 @@ rec { `drv` : 2\. Function argument + + # Type + + ``` + setName :: string -> Derivation -> Derivation + ``` */ setName = name: drv: drv // { inherit name; }; @@ -101,6 +119,12 @@ rec { : 2\. Function argument + # Type + + ``` + updateName :: (string -> string) -> Derivation -> Derivation + ``` + # Examples :::{.example} ## `lib.meta.updateName` usage example @@ -122,6 +146,12 @@ rec { `suffix` : 1\. Function argument + + # Type + + ``` + appendToName :: string -> Derivation -> Derivation + ``` */ appendToName = suffix: @@ -145,6 +175,12 @@ rec { `set` : 2\. Function argument + + # Type + + ``` + mapDerivationAttrset :: (Derivation -> a) -> attrs -> attrs + ``` */ mapDerivationAttrset = f: set: lib.mapAttrs (name: pkg: if lib.isDerivation pkg then (f pkg) else pkg) set; @@ -164,6 +200,12 @@ rec { `drv` : 2\. Function argument + + # Type + + ``` + setPrio :: int -> Derivation -> Derivation + ``` */ setPrio = priority: addMetaAttrs { inherit priority; }; @@ -176,6 +218,12 @@ rec { `drv` : 1\. Function argument + + # Type + + ``` + lowPrio :: Derivation -> Derivation + ``` */ lowPrio = setPrio 10; @@ -187,6 +235,12 @@ rec { `set` : 1\. Function argument + + # Type + + ``` + lowPrioSet :: (Map string Derivation) -> (Map string Derivation) + ``` */ lowPrioSet = set: mapDerivationAttrset lowPrio set; @@ -199,6 +253,12 @@ rec { `drv` : 1\. Function argument + + # Type + + ``` + hiPrio :: Derivation -> Derivation + ``` */ hiPrio = setPrio (-10); @@ -210,6 +270,12 @@ rec { `set` : 1\. Function argument + + # Type + + ``` + hiPrioSet :: (Map string Derivation) -> (Map string Derivation) + ``` */ hiPrioSet = set: mapDerivationAttrset hiPrio set; diff --git a/lib/trivial.nix b/lib/trivial.nix index f351fb572fbc..404e90c7554a 100644 --- a/lib/trivial.nix +++ b/lib/trivial.nix @@ -200,6 +200,12 @@ in `y` : 2\. Function argument + + # Type + + ``` + or :: bool -> bool -> bool + ``` */ "or" = x: y: x || y; @@ -215,6 +221,12 @@ in `y` : 2\. Function argument + + # Type + + ``` + and :: bool -> bool -> bool + ``` */ and = x: y: x && y; @@ -230,6 +242,12 @@ in `y` : 2\. Function argument + + # Type + + ``` + xor :: bool -> bool -> bool + ``` */ # We explicitly invert the arguments purely as a type assertion. # This is invariant under XOR, so it does not affect the result. @@ -237,6 +255,12 @@ in /** bitwise “not” + + # Type + + ``` + bitNot :: number -> number + ``` */ bitNot = builtins.sub (-1); @@ -284,12 +308,6 @@ in /** Merge two attribute sets shallowly, right side trumps left - # Type - - ``` - mergeAttrs :: attrs -> attrs -> attrs - ``` - # Inputs `x` @@ -300,6 +318,12 @@ in : Right attribute set (higher precedence for equal keys) + # Type + + ``` + mergeAttrs :: attrs -> attrs -> attrs + ``` + # Examples :::{.example} ## `lib.trivial.mergeAttrs` usage example @@ -364,6 +388,12 @@ in : 2\. Function argument + # Type + + ``` + defaultTo :: a -> Nullable b -> (a | b) + ``` + # Examples :::{.example} ## `lib.trivial.defaultTo` usage example @@ -394,6 +424,12 @@ in : Argument to check for null before passing it to `f` + # Type + + ``` + mapNullable :: (a -> b) -> Nullable a -> Nullable b + ``` + # Examples :::{.example} ## `lib.trivial.mapNullable` usage example @@ -547,6 +583,12 @@ in `y` : 2\. Function argument + + # Type + + ``` + min :: number -> number -> number + ``` */ min = x: y: if x < y then x else y; @@ -562,6 +604,12 @@ in `y` : 2\. Function argument + + # Type + + ``` + max :: number -> number -> number + ``` */ max = x: y: if x > y then x else y; @@ -578,6 +626,12 @@ in : 2\. Function argument + # Type + + ``` + mod :: int -> int -> int + ``` + # Examples :::{.example} ## `lib.trivial.mod` usage example @@ -611,6 +665,12 @@ in `b` : 2\. Function argument + + # Type + + ``` + compare :: a -> a -> int + ``` */ compare = a: b: @@ -1000,12 +1060,6 @@ in function of the `{ a, b ? foo, ... }:` format, but some facilities like `callPackage` expect to be able to query expected arguments. - # Type - - ``` - setFunctionArgs : (a -> b) -> Map String Bool -> (a -> b) - ``` - # Inputs `f` @@ -1015,6 +1069,12 @@ in `args` : 2\. Function argument + + # Type + + ``` + setFunctionArgs : (a -> b) -> (Map String Bool) -> (a -> b) + ``` */ setFunctionArgs = f: args: { # TODO: Should we add call-time "type" checking like built in? @@ -1028,17 +1088,17 @@ in functions and functions with args set with `setFunctionArgs`. It has the same return type and semantics as `builtins.functionArgs`. - # Type - - ``` - functionArgs : (a -> b) -> Map String Bool - ``` - # Inputs `f` : 1\. Function argument + + # Type + + ``` + functionArgs : (a -> b) -> Map String Bool + ``` */ functionArgs = f: @@ -1056,6 +1116,12 @@ in `f` : 1\. Function argument + + # Type + + ``` + isFunction : a -> bool + ``` */ isFunction = f: builtins.isFunction f || (f ? __functor && isFunction (f.__functor f)); @@ -1178,6 +1244,12 @@ in Convert the given positive integer to a string of its hexadecimal representation. + # Type + + ``` + toHexString :: int -> string + ``` + # Examples :::{.example} ## `lib.trivial.toHexString` usage example @@ -1219,6 +1291,12 @@ in : 2\. Function argument + # Type + + ``` + toBaseDigits :: int -> int -> [int] + ``` + # Examples :::{.example} ## `lib.trivial.toBaseDigits` diff --git a/lib/versions.nix b/lib/versions.nix index 0073c5669743..ed0d5b7dc667 100644 --- a/lib/versions.nix +++ b/lib/versions.nix @@ -8,6 +8,12 @@ rec { /** Break a version string into its component parts. + # Type + + ``` + splitVersion :: string -> [string] + ``` + # Examples :::{.example} ## `splitVersion` usage example @@ -30,6 +36,12 @@ rec { : 1\. Function argument + # Type + + ``` + major :: string -> string + ``` + # Examples :::{.example} ## `major` usage example @@ -52,6 +64,12 @@ rec { : 1\. Function argument + # Type + + ``` + minor :: string -> string + ``` + # Examples :::{.example} ## `minor` usage example @@ -74,6 +92,12 @@ rec { : 1\. Function argument + # Type + + ``` + patch :: string -> string + ``` + # Examples :::{.example} ## `patch` usage example @@ -97,6 +121,12 @@ rec { : 1\. Function argument + # Type + + ``` + mmajorMinor :: string -> string + ``` + # Examples :::{.example} ## `majorMinor` usage example @@ -123,6 +153,12 @@ rec { : 2\. Function argument + # Type + + ``` + pad :: int -> string -> string + ``` + # Examples :::{.example} ## `pad` usage example