From f835f77e02018c77b48fc7f4911f3fee97f9d777 Mon Sep 17 00:00:00 2001 From: Graham Christensen Date: Tue, 2 Oct 2018 16:06:33 -0400 Subject: nixpkgs: Start documenting library functions in XML Covers assert functions and about half of the attrsets functions. Some internal consistency around IDs could be improved. --- doc/Makefile | 2 +- doc/functions.xml | 2 +- doc/functions/library.xml | 15 + doc/functions/library/asserts.xml | 113 +++++ doc/functions/library/attrsets.xml | 938 +++++++++++++++++++++++++++++++++++++ 5 files changed, 1068 insertions(+), 2 deletions(-) create mode 100644 doc/functions/library.xml create mode 100644 doc/functions/library/asserts.xml create mode 100644 doc/functions/library/attrsets.xml (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile index 173e1c0b19ee..65a37eb05a3a 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -69,7 +69,7 @@ highlightjs: cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/ -manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml +manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml **/**/*.xml xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml .version: diff --git a/doc/functions.xml b/doc/functions.xml index 88011061ae6e..4193bb49f77a 100644 --- a/doc/functions.xml +++ b/doc/functions.xml @@ -7,7 +7,7 @@ The nixpkgs repository has several utility functions to manipulate Nix expressions. - + diff --git a/doc/functions/library.xml b/doc/functions/library.xml new file mode 100644 index 000000000000..901423c52a18 --- /dev/null +++ b/doc/functions/library.xml @@ -0,0 +1,15 @@ +
+ Nixpkgs Library Functions + + + Nixpkgs provides a standard library at pkgs.lib, or + through import <nixpkgs/lib>. + + + + + +
diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml new file mode 100644 index 000000000000..1f42078c8cf3 --- /dev/null +++ b/doc/functions/library/asserts.xml @@ -0,0 +1,113 @@ +
+ Assert functions + +
+ <function>lib.asserts.assertMsg</function> + + assertMsg :: Bool -> String -> Bool + + + + Print a trace message if pred is false. + + + + Intended to be used to augment asserts with helpful error messages. + + + + + + pred + + + + Condition under which the msg should + not be printed. + + + + + + msg + + + + Message to print. + + + + + + + Printing when the predicate is false + trace: foo is not bar, silly +stderr> assert failed +]]> + +
+ +
+ <function>lib.asserts.assertOneOf</function> + + assertOneOf :: String -> String -> + StringList -> Bool + + + + Specialized asserts.assertMsg for checking if + val is one of the elements of xs. + Useful for checking enums. + + + + + + name + + + + The name of the variable the user entered val into, + for inclusion in the error message. + + + + + + val + + + + The value of what the user provided, to be compared against the values in + xs. + + + + + + xs + + + + The list of valid values. + + + + + + + Ensuring a user provided a possible value + false +stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl" + ]]> + +
+
diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml new file mode 100644 index 000000000000..7ad3f949a024 --- /dev/null +++ b/doc/functions/library/attrsets.xml @@ -0,0 +1,938 @@ +
+ Attribute-Set Functions + +
+ <function>lib.attrset.attrByPath</function> + + attrByPath :: [String] -> Any -> AttrSet + + + + Return an attribute from within nested attribute sets. + + + + + + attrPath + + + + A list of strings representing the path through the nested attribute set + set. + + + + + + default + + + + Default value if attrPath does not resolve to an + existing value. + + + + + + set + + + + The nested attributeset to select values from. + + + + + + + Extracting a value from a nested attribute set + 3 +]]> + + + + No value at the path, instead using the default + 0 +]]> + +
+ +
+ <function>lib.attrsets.hasAttrByPath</function> + + hasAttrByPath :: [String] -> AttrSet -> Bool + + + + Determine if an attribute exists within a nested attribute set. + + + + + + attrPath + + + + A list of strings representing the path through the nested attribute set + set. + + + + + + set + + + + The nested attributeset to check. + + + + + + + A nested value does exist inside a set + true +]]> + +
+ +
+ <function>lib.attrsets.setAttrByPath</function> + + setAttrByPath :: [String] -> Any -> AttrSet + + + + Create a new attribute set with value set at the nested + attribute location specified in attrPath. + + + + + + attrPath + + + + A list of strings representing the path through the nested attribute set. + + + + + + value + + + + The value to set at the location described by + attrPath. + + + + + + + Creating a new nested attribute set + { a = { b = 3; }; } +]]> + +
+ +
+ <function>lib.attrsets.getAttrFromPath</function> + + getAttrFromPath :: [String] -> AttrSet -> Value + + + + Like except + without a default, and it will throw if the value doesn't exist. + + + + + + attrPath + + + + A list of strings representing the path through the nested attribute set + set. + + + + + + set + + + + The nested attribute set to find the value in. + + + + + + + Succesfully getting a value from an attribute set + 3 +]]> + + + + Throwing after failing to get a value from an attribute set + error: cannot find attribute `x.y' +]]> + +
+ +
+ <function>lib.attrsets.attrVals</function> + + attrVals :: [String] -> AttrSet -> [Any] + + + + Return the specified attributes from a set. All values must exist. + + + + + + nameList + + + + The list of attributes to fetch from set. Each + attribute name must exist on the attrbitue set. + + + + + + set + + + + The set to get attribute values from. + + + + + + + Getting several values from an attribute set + [ 1 2 3 ] +]]> + + + + Getting missing values from an attribute set + + +
+ +
+ <function>lib.attrsets.attrValues</function> + + attrValues :: AttrSet -> [Any] + + + + Get all the attribute values from an attribute set. + + + + Provides a backwards-compatible interface of + builtins.attrValues for Nix version older than 1.8. + + + + + + attrs + + + + The attribute set. + + + + + + + + [ 1 2 3 ] +]]> + +
+ +
+ <function>lib.attrsets.catAttrs</function> + + catAttrs :: String -> AttrSet -> [Any] + + + + Collect each attribute named `attr' from the list of attribute sets, + sets. Sets that don't contain the named attribute are + ignored. + + + + Provides a backwards-compatible interface of + builtins.catAttrs for Nix version older than 1.9. + + + + + + attr + + + + Attribute name to select from each attribute set in + sets. + + + + + + sets + + + + The list of attribute sets to select attr from. + + + + + + + Collect an attribute from a list of attribute sets. + + Attribute sets which don't have the attribute are ignored. + + [ 1 2 ] + ]]> + +
+ +
+ <function>lib.attrsets.filterAttrs</function> + + filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet + + + + Filter an attribute set by removing all attributes for which the given + predicate return false. + + + + + + pred + + + + String -> Any -> Bool + + + Predicate which returns true to include an attribute, or returns false to + exclude it. + + + + + name + + + + The attribute's name + + + + + + value + + + + The attribute's value + + + + + + Returns true to include the attribute, + false to exclude the attribute. + + + + + + set + + + + The attribute set to filter + + + + + + + Filtering an attributeset + { foo = 1; } +]]> + +
+ +
+ <function>lib.attrsets.filterAttrsRecursive</function> + + filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet + + + + Filter an attribute set recursively by removing all attributes for which the + given predicate return false. + + + + + + pred + + + + String -> Any -> Bool + + + Predicate which returns true to include an attribute, or returns false to + exclude it. + + + + + name + + + + The attribute's name + + + + + + value + + + + The attribute's value + + + + + + Returns true to include the attribute, + false to exclude the attribute. + + + + + + set + + + + The attribute set to filter + + + + + + + Recursively filtering an attribute set + { + levelA = { + example = "hi"; + levelB = { + hello = "there"; + this-one-is-present = { }; + }; + }; + } + ]]> + +
+ +
+ <function>lib.attrsets.foldAttrs</function> + + foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any + + + + Apply fold function to values grouped by key. + + + + + + op + + + + Any -> Any -> Any + + + Given a value val and a collector + col, combine the two. + + + + + val + + + + An attribute's value + + + + + + col + + + + + The result of previous op calls with other values + and nul. + + + + + + + + + nul + + + + The null-value, the starting value. + + + + + + list_of_attrs + + + + A list of attribute sets to fold together by key. + + + + + + + Combining an attribute of lists in to one attribute set + { a = [ 2 3 ]; b = [ 7 6 ]; } +]]> + +
+ +
+ <function>lib.attrsets.collect</function> + + collect :: (Any -> Bool) -> AttrSet -> [Any] + + + + Recursively collect sets that verify a given predicate named + pred from the set attrs. The recursion + stops when pred returns true. + + + + + + pred + + + + Any -> Bool + + + Given an attribute's value, determine if recursion should stop. + + + + + value + + + + The attribute set value. + + + + + + + + + attrs + + + + The attribute set to recursively collect. + + + + + + + Collecting all lists from an attribute set + [["b"] [1]] +]]> + + + + Collecting all attribute-sets which contain the <literal>outPath</literal> attribute name. + [{ outPath = "a/"; } { outPath = "b/"; }] +]]> + +
+ +
+ <function>lib.attrsets.nameValuePair</function> + + nameValuePair :: String -> Any -> AttrSet + + + + Utility function that creates a {name, value} pair as + expected by builtins.listToAttrs. + + + + + + name + + + + The attribute name. + + + + + + value + + + + The attribute value. + + + + + + + Creating a name value pair + { name = "some"; value = 6; } +]]> + +
+ +
+ <function>lib.attrsets.mapAttrs</function> + + + + + + Apply a function to each element in an attribute set, creating a new + attribute set. + + + + Provides a backwards-compatible interface of + builtins.mapAttrs for Nix version older than 2.1. + + + + + + fn + + + + String -> Any -> Any + + + Given an attribute's name and value, return a new value. + + + + + name + + + + The name of the attribute. + + + + + + value + + + + The attribute's value. + + + + + + + + + + Modifying each value of an attribute set + { x = "x-foo"; y = "y-bar"; } +]]> + +
+ +
+ <function>lib.attrsets.mapAttrs'</function> + + mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet + + + + Like mapAttrs, but allows the name of each attribute to + be changed in addition to the value. The applied function should return both + the new name and value as a nameValuePair. + + + + + + fn + + + + String -> Any -> { name = String; value = Any } + + + Given an attribute's name and value, return a new + name + value pair. + + + + + name + + + + The name of the attribute. + + + + + + value + + + + The attribute's value. + + + + + + + + + set + + + + The attribute set to map over. + + + + + + + Change the name and value of each attribute of an attribute set + { foo_x = "bar-a"; foo_y = "bar-b"; } + + ]]> + +
+ +
+ <function>lib.attrsets.mapAttrsToList</function> + + mapAttrsToList :: (String -> Any -> Any) -> + AttrSet -> Any + + + + Call fn for each attribute in the given + set and return the result in a list. + + + + + + fn + + + + String -> Any -> Any + + + Given an attribute's name and value, return a new value. + + + + + name + + + + The name of the attribute. + + + + + + value + + + + The attribute's value. + + + + + + + + + set + + + + The attribute set to map over. + + + + + + + Combine attribute values and names in to a list + [ "x=a" "y=b" ] +]]> + +
+ +
+ <function>lib.attrsets.mapAttrsRecursive</function> + + mapAttrsRecursive :: ([String] > Any -> Any) -> AttrSet -> AttrSet + + + + Like mapAttrs, except that it recursively applies + itself to attribute sets. Also, the first argument of the argument function + is a list of the names of the containing attributes. + +
+
-- cgit 1.4.1