From 5ff21bfc73f59efd3e61776964f7b7f1863a3136 Mon Sep 17 00:00:00 2001 From: hsjobeki Date: Sat, 24 Dec 2022 14:08:11 +0100 Subject: [PATCH] attrsets: fix and add some doc types --- lib/attrsets.nix | 61 ++++++++++++++++++++++++++++-------------------- lib/options.nix | 4 ++-- 2 files changed, 38 insertions(+), 27 deletions(-) diff --git a/lib/attrsets.nix b/lib/attrsets.nix index 4b663db2ce4a..9009feb87d90 100644 --- a/lib/attrsets.nix +++ b/lib/attrsets.nix @@ -16,6 +16,8 @@ rec { Example: x = { a = { b = 3; }; } + # ["a" "b"] is equivalent to x.a.b + # 6 is a default value to return if the path does not exist in attrset attrByPath ["a" "b"] 6 x => 3 attrByPath ["z" "z"] 6 x @@ -23,6 +25,7 @@ rec { Type: attrByPath :: [String] -> Any -> AttrSet -> Any + */ attrByPath = # A list of strings representing the attribute path to return from `set` @@ -96,7 +99,7 @@ rec { => error: cannot find attribute `z.z' Type: - getAttrFromPath :: [String] -> AttrSet -> Value + getAttrFromPath :: [String] -> AttrSet -> Any */ getAttrFromPath = # A list of strings representing the attribute path to get from `set` @@ -109,10 +112,7 @@ rec { /* Map each attribute in the given set and merge them into a new attribute set. Type: - concatMapAttrs :: - (String -> a -> AttrSet) - -> AttrSet - -> AttrSet + concatMapAttrs :: (String -> a -> AttrSet) -> AttrSet -> AttrSet Example: concatMapAttrs @@ -168,8 +168,7 @@ rec { ] { a.b.c = 0; } => { a = { b = { d = 1; }; }; x = { y = "xy"; }; } - Type: - updateManyAttrsByPath :: [AttrSet] -> AttrSet -> AttrSet + Type: updateManyAttrsByPath :: [{ path :: [String], update :: (Any -> Any) }] -> AttrSet -> AttrSet */ updateManyAttrsByPath = let # When recursing into attributes, instead of updating the `path` of each @@ -252,6 +251,7 @@ rec { Example: attrValues {c = 3; a = 1; b = 2;} => [1 2 3] + Type: attrValues :: AttrSet -> [Any] */ @@ -341,6 +341,7 @@ rec { Type: foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any + */ foldAttrs = # A function, given a value and a collector combines the two. @@ -394,7 +395,7 @@ rec { { a = 2; b = 20; } ] Type: - cartesianProductOfSets :: AttrSet -> [AttrSet] + cartesianProductOfSets :: AttrSet -> [AttrSet] */ cartesianProductOfSets = # Attribute set with attributes that are lists of values @@ -413,7 +414,7 @@ rec { => { name = "some"; value = 6; } Type: - nameValuePair :: String -> Any -> AttrSet + nameValuePair :: String -> Any -> { name :: String, value :: Any } */ nameValuePair = # Attribute name @@ -600,7 +601,7 @@ rec { => { } Type: - optionalAttrs :: Bool -> AttrSet + optionalAttrs :: Bool -> AttrSet -> AttrSet */ optionalAttrs = # Condition under which the `as` attribute set is returned. @@ -646,7 +647,7 @@ rec { => { a = ["x" "y"]; b = ["z"] } Type: - zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet + zipAttrsWith :: (String -> [ Any ] -> Any) -> [ AttrSet ] -> AttrSet */ zipAttrsWith = builtins.zipAttrsWith or (f: sets: zipAttrsWithNames (concatMap attrNames sets) f sets); @@ -737,7 +738,7 @@ rec { } Type: - recursiveUpdate :: AttrSet -> AttrSet -> AttrSet + recursiveUpdate :: AttrSet -> AttrSet -> AttrSet */ recursiveUpdate = # Left attribute set of the merge. @@ -795,6 +796,7 @@ rec { /* Turns a list of strings into a human-readable description of those strings represented as an attribute path. The result of this function is not intended to be machine-readable. + Create a new attribute set with `value` set at the nested attribute location specified in `attrPath`. Example: showAttrPath [ "foo" "10" "bar" ] @@ -831,11 +833,11 @@ rec { If the output does not exist, fallback to `.out` and then to the default. Example: - getOutput pkgs.openssl + getBin pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r" Type: - getOutput :: Derivation -> String + getBin :: Derivation -> String */ getBin = getOutput "bin"; @@ -844,11 +846,11 @@ rec { If the output does not exist, fallback to `.out` and then to the default. Example: - getOutput pkgs.openssl + getLib pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-lib" Type: - getOutput :: Derivation -> String + getLib :: Derivation -> String */ getLib = getOutput "lib"; @@ -857,11 +859,11 @@ rec { If the output does not exist, fallback to `.out` and then to the default. Example: - getOutput pkgs.openssl + getDev pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev" Type: - getOutput :: Derivation -> String + getDev :: Derivation -> String */ getDev = getOutput "dev"; @@ -870,15 +872,19 @@ rec { If the output does not exist, fallback to `.out` and then to the default. Example: - getOutput pkgs.openssl + getMan pkgs.openssl => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-man" Type: - getOutput :: Derivation -> String + getMan :: Derivation -> String */ getMan = getOutput "man"; - /* Pick the outputs of packages to place in `buildInputs` */ + /* Pick the outputs of packages to place in `buildInputs` + + Type: chooseDevOutputs :: [Derivation] -> [String] + + */ chooseDevOutputs = # List of packages to pick `dev` outputs from drvs: @@ -900,6 +906,7 @@ rec { Type: recurseIntoAttrs :: AttrSet -> AttrSet + */ recurseIntoAttrs = # An attribute set to scan for derivations. @@ -909,7 +916,7 @@ rec { /* Undo the effect of recurseIntoAttrs. Type: - recurseIntoAttrs :: AttrSet -> AttrSet + dontRecurseIntoAttrs :: AttrSet -> AttrSet */ dontRecurseIntoAttrs = # An attribute set to not scan for derivations. @@ -919,7 +926,10 @@ rec { /* `unionOfDisjoint x y` is equal to `x // y // z` where the attrnames in `z` are the intersection of the attrnames in `x` and `y`, and all values `assert` with an error message. This - operator is commutative, unlike (//). */ + operator is commutative, unlike (//). + + Type: unionOfDisjoint :: AttrSet -> AttrSet -> AttrSet + */ unionOfDisjoint = x: y: let intersection = builtins.intersectAttrs x y; @@ -930,9 +940,10 @@ rec { in (x // y) // mask; - # deprecated + # DEPRECATED zipWithNames = zipAttrsWithNames; - # deprecated + + # DEPRECATED zip = builtins.trace "lib.zip is deprecated, use lib.zipAttrsWith instead" zipAttrsWith; } diff --git a/lib/options.nix b/lib/options.nix index 0fd5b64a65d1..9425e803c056 100644 --- a/lib/options.nix +++ b/lib/options.nix @@ -104,8 +104,6 @@ rec { /* Creates an Option attribute set for an option that specifies the package a module should use for some purpose. - Type: mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> option - The package is specified as a list of strings representing its attribute path in nixpkgs. Because of this, you need to pass nixpkgs itself as the first argument. @@ -116,6 +114,8 @@ rec { You can omit the default path if the name of the option is also attribute path in nixpkgs. + Type: mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> option + Example: mkPackageOption pkgs "hello" { } => { _type = "option"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = "The hello package to use."; type = { ... }; }