diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile | 8 | ||||
| -rw-r--r-- | doc/default.nix | 5 | ||||
| -rw-r--r-- | doc/functions/library/asserts.xml | 4 | ||||
| -rw-r--r-- | doc/functions/library/attrsets.xml | 32 | ||||
| -rw-r--r-- | doc/lib-function-locations.nix | 85 | ||||
| -rw-r--r-- | doc/shell.nix | 2 |
7 files changed, 133 insertions, 4 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index d0ba103fa9f1..cb07135e6858 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -4,3 +4,4 @@ out manual-full.xml highlightjs +functions/library/locations.xml diff --git a/doc/Makefile b/doc/Makefile index 65a37eb05a3a..c6aed62a9396 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -19,7 +19,7 @@ fix-misc-xml: .PHONY: clean clean: - rm -f ${MD_TARGETS} .version manual-full.xml + rm -f ${MD_TARGETS} .version manual-full.xml functions/library/locations.xml rm -rf ./out/ ./highlightjs .PHONY: validate @@ -69,13 +69,17 @@ highlightjs: cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/ -manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml **/**/*.xml +manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml *.xml **/*.xml **/**/*.xml xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml .version: nix-instantiate --eval \ -E '(import ../lib).version' > .version +functions/library/locations.xml: + nix-build ./lib-function-locations.nix \ + --out-link ./functions/library/locations.xml + %.section.xml: %.section.md pandoc $^ -w docbook+smart \ -f markdown+smart \ diff --git a/doc/default.nix b/doc/default.nix index 4c04128052bc..98b4b92be524 100644 --- a/doc/default.nix +++ b/doc/default.nix @@ -1,6 +1,7 @@ +{ pkgs ? (import ./.. { }), nixpkgs ? { }}: let - pkgs = import ./.. { }; lib = pkgs.lib; + locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; }; in pkgs.stdenv.mkDerivation { name = "nixpkgs-manual"; @@ -29,6 +30,8 @@ pkgs.stdenv.mkDerivation { ]; postPatch = '' + rm -rf ./functions/library/locations.xml + ln -s ${locationsXml} ./functions/library/locations.xml echo ${lib.version} > .version ''; diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml index 1f42078c8cf3..437850e408bc 100644 --- a/doc/functions/library/asserts.xml +++ b/doc/functions/library/asserts.xml @@ -10,6 +10,8 @@ <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" /> + <para> Print a trace message if <literal>pred</literal> is false. </para> @@ -59,6 +61,8 @@ stderr> assert failed StringList -> Bool</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" /> + <para> Specialized <function>asserts.assertMsg</function> for checking if <varname>val</varname> is one of the elements of <varname>xs</varname>. diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml index 7ad3f949a024..6f23e267bab2 100644 --- a/doc/functions/library/attrsets.xml +++ b/doc/functions/library/attrsets.xml @@ -10,6 +10,8 @@ <subtitle><literal>attrByPath :: [String] -> Any -> AttrSet</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.attrByPath" /> + <para> Return an attribute from within nested attribute sets. </para> @@ -73,6 +75,8 @@ lib.attrsets.attrByPath [ "a" "b" ] 0 {} <subtitle><literal>hasAttrByPath :: [String] -> AttrSet -> Bool</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.hasAttrByPath" /> + <para> Determine if an attribute exists within a nested attribute set. </para> @@ -118,6 +122,8 @@ lib.attrsets.hasAttrByPath <subtitle><literal>setAttrByPath :: [String] -> Any -> AttrSet</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.setAttrByPath" /> + <para> Create a new attribute set with <varname>value</varname> set at the nested attribute location specified in <varname>attrPath</varname>. @@ -162,6 +168,8 @@ lib.attrsets.setAttrByPath [ "a" "b" ] 3 <subtitle><literal>getAttrFromPath :: [String] -> AttrSet -> Value</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.getAttrFromPath" /> + <para> Like <xref linkend="function-library-lib.attrsets.attrByPath" /> except without a default, and it will throw if the value doesn't exist. @@ -214,6 +222,8 @@ lib.attrsets.getAttrFromPath [ "x" "y" ] { } <subtitle><literal>attrVals :: [String] -> AttrSet -> [Any]</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.attrVals" /> + <para> Return the specified attributes from a set. All values must exist. </para> @@ -265,6 +275,8 @@ error: attribute 'd' missing <subtitle><literal>attrValues :: AttrSet -> [Any]</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.attrValues" /> + <para> Get all the attribute values from an attribute set. </para> @@ -302,6 +314,8 @@ lib.attrsets.attrValues { a = 1; b = 2; c = 3; } <subtitle><literal>catAttrs :: String -> AttrSet -> [Any]</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.catAttrs" /> + <para> Collect each attribute named `attr' from the list of attribute sets, <varname>sets</varname>. Sets that don't contain the named attribute are @@ -355,6 +369,8 @@ catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}] <subtitle><literal>filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrs" /> + <para> Filter an attribute set by removing all attributes for which the given predicate return false. @@ -428,6 +444,8 @@ filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; } <subtitle><literal>filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrsRecursive" /> + <para> Filter an attribute set recursively by removing all attributes for which the given predicate return false. @@ -523,6 +541,8 @@ lib.attrsets.filterAttrsRecursive <subtitle><literal>foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.foldAttrs" /> + <para> Apply fold function to values grouped by key. </para> @@ -609,6 +629,8 @@ lib.attrsets.foldAttrs <subtitle><literal>collect :: (Any -> Bool) -> AttrSet -> [Any]</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.collect" /> + <para> Recursively collect sets that verify a given predicate named <varname>pred</varname> from the set <varname>attrs</varname>. The recursion @@ -677,6 +699,8 @@ collect (x: x ? outPath) <subtitle><literal>nameValuePair :: String -> Any -> AttrSet</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.nameValuePair" /> + <para> Utility function that creates a <literal>{name, value}</literal> pair as expected by <function>builtins.listToAttrs</function>. @@ -720,6 +744,8 @@ nameValuePair "some" 6 <subtitle><literal></literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs" /> + <para> Apply a function to each element in an attribute set, creating a new attribute set. @@ -785,6 +811,8 @@ lib.attrsets.mapAttrs <subtitle><literal>mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs-prime" /> + <para> Like <function>mapAttrs</function>, but allows the name of each attribute to be changed in addition to the value. The applied function should return both @@ -860,6 +888,8 @@ lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name) AttrSet -> Any</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsToList" /> + <para> Call <varname>fn</varname> for each attribute in the given <varname>set</varname> and return the result in a list. @@ -929,6 +959,8 @@ lib.attrsets.mapAttrsToList (name: value: "${name}=${value}") <subtitle><literal>mapAttrsRecursive :: ([String] > Any -> Any) -> AttrSet -> AttrSet</literal> </subtitle> + <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsRecursive" /> + <para> Like <function>mapAttrs</function>, except that it recursively applies itself to attribute sets. Also, the first argument of the argument function diff --git a/doc/lib-function-locations.nix b/doc/lib-function-locations.nix new file mode 100644 index 000000000000..ae7036e46264 --- /dev/null +++ b/doc/lib-function-locations.nix @@ -0,0 +1,85 @@ +{ pkgs ? (import ./.. { }), nixpkgs ? { }}: +let + revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master"); + + libDefPos = set: + builtins.map + (name: { + name = name; + location = builtins.unsafeGetAttrPos name set; + }) + (builtins.attrNames set); + + libset = toplib: + builtins.map + (subsetname: { + subsetname = subsetname; + functions = libDefPos toplib."${subsetname}"; + }) + (builtins.filter + (name: builtins.isAttrs toplib."${name}") + (builtins.attrNames toplib)); + + nixpkgsLib = pkgs.lib; + + flattenedLibSubset = { subsetname, functions }: + builtins.map + (fn: { + name = "lib.${subsetname}.${fn.name}"; + value = fn.location; + }) + functions; + + locatedlibsets = libs: builtins.map flattenedLibSubset (libset libs); + removeFilenamePrefix = prefix: filename: + let + prefixLen = (builtins.stringLength prefix) + 1; # +1 to remove the leading / + filenameLen = builtins.stringLength filename; + substr = builtins.substring prefixLen filenameLen filename; + in substr; + + removeNixpkgs = removeFilenamePrefix (builtins.toString pkgs.path); + + liblocations = + builtins.filter + (elem: elem.value != null) + (nixpkgsLib.lists.flatten + (locatedlibsets nixpkgsLib)); + + fnLocationRelative = { name, value }: + { + inherit name; + value = value // { file = removeNixpkgs value.file; }; + }; + + relativeLocs = (builtins.map fnLocationRelative liblocations); + sanitizeId = builtins.replaceStrings + [ "'" ] + [ "-prime" ]; + + urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}"; + xmlstrings = (nixpkgsLib.strings.concatMapStrings + ({ name, value }: + '' + <section><title>${name}</title> + <para xml:id="${sanitizeId name}"> + Located at + <link + xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link> + in <literal><nixpkgs></literal>. + </para> + </section> + '') + relativeLocs); + +in pkgs.writeText + "locations.xml" + '' + <section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + version="5"> + <title>All the locations for every lib function</title> + <para>This file is only for inclusion by other files.</para> + ${xmlstrings} + </section> + '' diff --git a/doc/shell.nix b/doc/shell.nix index 24fe20e81050..8ac2019f9d66 100644 --- a/doc/shell.nix +++ b/doc/shell.nix @@ -1,5 +1,5 @@ { pkgs ? import ../. {} }: -(import ./default.nix).overrideAttrs (x: { +(import ./default.nix {}).overrideAttrs (x: { buildInputs = x.buildInputs ++ [ pkgs.xmloscopy pkgs.ruby ]; }) |