Unverified Commit df4aa144 authored by Johannes Kirschbauer's avatar Johannes Kirschbauer Committed by GitHub
Browse files

lib: add type signature to some of the functions and normalize existing ones (#495873)

parents 5051decf 6acae46c

lib/asserts.nix

+3 −3
Original line number Diff line number Diff line
@@ -70,7 +70,7 @@ rec { 
    # Type



    ```

    assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool

    assertOneOf :: String -> ComparableVal -> [ComparableVal] -> Bool

    ```



    # Examples
@@ -115,7 +115,7 @@ rec { 
    # Type



    ```

    assertEachOneOf :: String -> List ComparableVal -> List ComparableVal -> Bool

    assertEachOneOf :: String -> [ComparableVal] -> [ComparableVal] -> Bool

    ```



    # Examples
@@ -164,7 +164,7 @@ rec { 
    # Type



    ```

    checkAssertWarn :: [ { assertion :: Bool; message :: String } ] -> [ String ] -> Any -> Any

    checkAssertWarn :: [{ assertion :: Bool; message :: String; }] -> [String] -> a -> a

    ```



    # Examples

lib/attrsets.nix

+27 −28
Original line number Diff line number Diff line
@@ -4,9 +4,8 @@ 
{ lib }:



let

  inherit (builtins) head length typeOf;

  inherit (lib.asserts) assertMsg;

  inherit (lib.trivial) oldestSupportedReleaseIsAtLeast mergeAttrs;

  inherit (builtins) head length;

  inherit (lib.trivial) mergeAttrs;

  inherit (lib.strings)

    concatStringsSep

    concatMapStringsSep
@@ -201,7 +200,7 @@ rec { 
    # Type



    ```

    attrsets.longestValidPathPrefix :: [String] -> Value -> [String]

    longestValidPathPrefix :: [String] -> AttrSet -> [String]

    ```



    # Examples
@@ -352,7 +351,7 @@ rec { 
    # Type



    ```

    concatMapAttrs :: (String -> a -> AttrSet) -> AttrSet -> AttrSet

    concatMapAttrs :: (String -> Any -> AttrSet) -> AttrSet -> AttrSet

    ```



    # Examples
@@ -514,7 +513,7 @@ rec { 
    # Type



    ```

    attrVals :: [String] -> AttrSet -> [Any]

    attrVals :: [String] -> { [String] :: a } -> [a]

    ```



    # Examples
@@ -537,7 +536,7 @@ rec { 
    # Type



    ```

    attrValues :: AttrSet -> [Any]

    attrValues :: { [String] :: a } -> [a]

    ```



    # Examples
@@ -570,7 +569,7 @@ rec { 
    # Type



    ```

    getAttrs :: [String] -> AttrSet -> AttrSet

    getAttrs :: [String] -> { [String] :: a } -> { [String] :: a }

    ```



    # Examples
@@ -603,7 +602,7 @@ rec { 
    # Type



    ```

    catAttrs :: String -> [AttrSet] -> [Any]

    catAttrs :: String -> [{ [String] :: a }] -> [a]

    ```



    # Examples
@@ -646,7 +645,7 @@ rec { 
    # Type



    ```

    filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet

    filterAttrs :: (String -> a -> Bool) -> { [String] :: a } -> { [String] :: a }

    ```



    # Examples
@@ -737,7 +736,7 @@ rec { 
    # Type



    ```

    foldlAttrs :: ( a -> String -> b -> a ) -> a -> { ... :: b } -> a

    foldlAttrs :: ( a -> String -> b -> a ) -> a -> { [String] :: b } -> a

    ```



    # Examples
@@ -812,7 +811,7 @@ rec { 
    # Type



    ```

    foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any

    foldAttrs :: (a -> b -> b) -> b -> [{ [String] :: a }] -> { [String] :: b }

    ```



    # Examples
@@ -850,7 +849,7 @@ rec { 
    # Type



    ```

    collect :: (AttrSet -> Bool) -> AttrSet -> [x]

    collect :: (AttrSet -> Bool) -> AttrSet -> [Any]

    ```



    # Examples
@@ -889,7 +888,7 @@ rec { 
    # Type



    ```

    cartesianProduct :: AttrSet -> [AttrSet]

    cartesianProduct :: { [String] :: [a] } -> [{ [String] :: a }]

    ```



    # Examples
@@ -934,7 +933,7 @@ rec { 
    # Type



    ```

    mapCartesianProduct :: (AttrSet -> a) -> AttrSet -> [a]

    mapCartesianProduct :: ({ [String] :: a } -> b) -> { [String] :: a } -> [b]

    ```



    # Examples
@@ -966,7 +965,7 @@ rec { 
    # Type



    ```

    nameValuePair :: String -> Any -> { name :: String; value :: Any; }

    nameValuePair :: String -> a -> { name :: String; value :: a; }

    ```



    # Examples
@@ -998,7 +997,7 @@ rec { 
    # Type



    ```

    mapAttrs :: (String -> Any -> Any) -> AttrSet -> AttrSet

    mapAttrs :: (String -> a -> b) -> { [String] :: a } -> { [String] :: b }

    ```



    # Examples
@@ -1033,7 +1032,7 @@ rec { 
    # Type



    ```

    mapAttrs' :: (String -> Any -> { name :: String; value :: Any; }) -> AttrSet -> AttrSet

    mapAttrs' :: (String -> a -> { name :: String; value :: b; }) -> { [String] :: a } -> { [String] :: b }

    ```



    # Examples
@@ -1067,7 +1066,7 @@ rec { 
    # Type



    ```

    mapAttrsToList :: (String -> a -> b) -> AttrSet -> [b]

    mapAttrsToList :: (String -> a -> b) -> { [String] :: a } -> [b]

    ```



    # Examples
@@ -1113,7 +1112,7 @@ rec { 
    # Type



    ```

    attrsToList :: AttrSet -> [ { name :: String; value :: Any; } ]

    attrsToList :: { [String] :: a } -> [{ name :: String; value :: a; }]

    ```



    # Examples
@@ -1327,7 +1326,7 @@ rec { 
    # Type



    ```

    genAttrs :: [ String ] -> (String -> Any) -> AttrSet

    genAttrs :: [String] -> (String -> a) -> { [String] :: a }

    ```



    # Examples
@@ -1364,7 +1363,7 @@ rec { 
    # Type



    ```

    genAttrs' :: [ Any ] -> (Any -> { name :: String; value :: Any; }) -> AttrSet

    genAttrs' :: [a] -> (a -> { name :: String; value :: b; }) -> { [String] :: b }

    ```



    # Examples
@@ -1498,7 +1497,7 @@ rec { 
    # Type



    ```

    zipAttrsWithNames :: [ String ] -> (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet

    zipAttrsWithNames :: [String] -> (String -> [a] -> b) -> [{ [String] :: a }] -> { [String] :: b }

    ```



    # Examples
@@ -1533,7 +1532,7 @@ rec { 
    # Type



    ```

    zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet

    zipAttrsWith :: (String -> [a] -> b) -> [{ [String] :: a }] -> { [String] :: b }

    ```



    # Examples
@@ -1558,7 +1557,7 @@ rec { 
    # Type



    ```

    zipAttrs :: [ AttrSet ] -> AttrSet

    zipAttrs :: [{ [String] :: a }] -> { [String] :: [a] }

    ```



    # Examples
@@ -1589,7 +1588,7 @@ rec { 
    # Type



    ```

    mergeAttrsList :: [ Attrs ] -> Attrs

    mergeAttrsList :: [AttrSet] -> AttrSet

    ```



    # Examples
@@ -1609,7 +1608,7 @@ rec { 
    list:

    let

      # `binaryMerge start end` merges the elements at indices `index` of `list` such that `start <= index < end`

      # Type: Int -> Int -> Attrs

      # Type: Int -> Int -> AttrSet

      binaryMerge =

        start: end:

        # assert start < end; # Invariant

lib/customisation.nix

+35 −23
Original line number Diff line number Diff line
@@ -20,7 +20,6 @@ let 
    take

    length

    filterAttrs

    optionalString

    flip

    head

    pipe
@@ -626,7 +625,7 @@ rec { 
    # Type



    ```

    makeScope :: (AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a) -> (AttrSet -> AttrSet) -> scope

    makeScope :: (AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a) -> (AttrSet -> AttrSet) -> Scope

    ```

  */

  makeScope =
@@ -689,19 +688,19 @@ rec { 


    ```

    makeScopeWithSplicing' ::

      { splicePackages :: Splice -> AttrSet

      , newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a

      { splicePackages :: Splice -> AttrSet;

        newScope :: AttrSet -> ((AttrSet -> a) | Path) -> AttrSet -> a;

      }

      -> { otherSplices :: Splice, keep :: AttrSet -> AttrSet, extra :: AttrSet -> AttrSet }

      -> { otherSplices :: Splice; keep :: AttrSet -> AttrSet; extra :: AttrSet -> AttrSet; }

      -> AttrSet



    Splice ::

      { pkgsBuildBuild :: AttrSet

      , pkgsBuildHost :: AttrSet

      , pkgsBuildTarget :: AttrSet

      , pkgsHostHost :: AttrSet

      , pkgsHostTarget :: AttrSet

      , pkgsTargetTarget :: AttrSet

    Splice :: {

      pkgsBuildBuild :: AttrSet;

      pkgsBuildHost :: AttrSet;

      pkgsBuildTarget :: AttrSet;

      pkgsHostHost :: AttrSet;

      pkgsHostTarget :: AttrSet;

      pkgsTargetTarget :: AttrSet;

    }

    ```

  */
@@ -806,17 +805,16 @@ rec { 
    ```

    extendMkDerivation ::

      {

        constructDrv :: ((FixedPointArgs | AttrSet) -> a)

        excludeDrvArgNames :: [ String ],

        excludeFunctionArgNames :: [ String ]

        extendDrvArgs :: (AttrSet -> AttrSet -> AttrSet)

        inheritFunctionArgs :: Bool,

        transformDrv :: a -> a,

        constructDrv :: (FixedPointArgs | AttrSet) -> Derivation;

        excludeDrvArgNames :: [String];

        excludeFunctionArgNames :: [String];

        extendDrvArgs :: AttrSet -> AttrSet -> AttrSet;

        inheritFunctionArgs :: Bool;

        transformDrv :: Derivation -> Derivation;

      }

      -> (FixedPointArgs | AttrSet) -> a

      -> ((FixedPointArgs | AttrSet) -> Derivation)



    FixedPointArgs = AttrSet -> AttrSet

    a = Derivation when defining a build helper

    FixedPointArgs :: AttrSet -> AttrSet

    ```



    # Examples
@@ -998,7 +996,21 @@ rec { 
    # Type



    ```

    mapCrossIndex :: (a -> b) -> AttrSet -> AttrSet

    mapCrossIndex :: (a -> b) -> {

      buildBuild :: a;

      buildHost :: a;

      buildTarget :: a;

      hostHost :: a;

      hostTarget :: a;

      targetTarget :: a;

    } -> {

      buildBuild :: b;

      buildHost :: b;

      buildTarget :: b;

      hostHost :: b;

      hostTarget :: b;

      targetTarget :: b;

    }

    ```



    # Examples

lib/debug.nix

+82 −5
Original line number Diff line number Diff line
@@ -60,7 +60,7 @@ rec { 
    # Type



    ```

    traceIf :: bool -> string -> a -> a

    traceIf :: Bool -> String -> a -> a

    ```



    # Examples
@@ -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 = { ... }; }

    ```



    :::
@@ -389,7 +466,7 @@ rec { 


    ```

    runTests :: {

      tests = [ String ];

      tests :: [String];

      ${testName} :: {

        expr :: a;

        expected :: a;
@@ -489,7 +566,7 @@ rec { 
      ];

    }

    ->

    null

    Null

    ```



    # Examples

lib/deprecated/misc.nix

+0 −6
Original line number Diff line number Diff line
@@ -6,26 +6,20 @@ let 
    any

    attrByPath

    attrNames

    compare

    concat

    concatMap

    elem

    filter

    foldl

    foldr

    genericClosure

    head

    imap1

    init

    isAttrs

    isFunction

    isInt

    isList

    lists

    listToAttrs

    mapAttrs

    mergeAttrs

    meta

    nameValuePair

    tail

    toList