lib: add type signature to some of the functions

This commit is contained in:
İlkecan Bozdoğan 2026-03-02 15:35:19 +00:00
parent 662217570e
commit 64a8ada54e
9 changed files with 372 additions and 37 deletions

View file

@ -201,7 +201,7 @@ rec {
# Type
```
attrsets.longestValidPathPrefix :: [String] -> Value -> [String]
longestValidPathPrefix :: [String] -> Value -> [String]
```
# Examples

View file

@ -167,7 +167,7 @@ rec {
```nix
trace { a.b.c = 3; } null
trace: { a = <CODE>; }
trace: { a = <thunk>; }
=> 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 = { ... }; }
```
:::

View file

@ -233,6 +233,12 @@ in
`drv`
: The derivation to wrap.
# Type
```
warnOnInstantiate :: string -> Derivation -> Derivation
```
# Examples
:::{.example}
## `lib.derivations.warnOnInstantiate` usage example

View file

@ -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

View file

@ -108,6 +108,12 @@ rec {
`f`
: 1\. Function argument
# Type
```
fix' :: (a -> a) -> a
```
*/
fix' =
f:

View file

@ -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

View file

@ -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;

View file

@ -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`

View file

@ -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