diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index 873f30b06..8d12da9b1 100644 --- a/doc/manual/expressions/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -21,7 +21,8 @@ available as builtins.derivation. - abort s + + abort s Abort Nix expression evaluation, print error message s. @@ -29,8 +30,10 @@ available as builtins.derivation. - builtins.add - e1 e2 + + builtins.add + e1 e2 + Return the sum of the numbers e1 and @@ -39,8 +42,9 @@ available as builtins.derivation. - builtins.all - pred list + + builtins.all + pred list Return true if the function pred returns true @@ -50,8 +54,9 @@ available as builtins.derivation. - builtins.any - pred list + + builtins.any + pred list Return true if the function pred returns true @@ -61,8 +66,9 @@ available as builtins.derivation. - builtins.attrNames - set + + builtins.attrNames + set Return the names of the attributes in the set set in an alphabetically sorted list. For instance, @@ -72,8 +78,9 @@ available as builtins.derivation. - builtins.attrValues - set + + builtins.attrValues + set Return the values of the attributes in the set set in the order corresponding to the @@ -82,7 +89,8 @@ available as builtins.derivation. - baseNameOf s + + baseNameOf s Return the base name of the string s, that is, everything following @@ -92,8 +100,9 @@ available as builtins.derivation. - builtins.bitAnd - e1 e2 + + builtins.bitAnd + e1 e2 Return the bitwise AND of the integers e1 and @@ -102,8 +111,9 @@ available as builtins.derivation. - builtins.bitOr - e1 e2 + + builtins.bitOr + e1 e2 Return the bitwise OR of the integers e1 and @@ -112,8 +122,9 @@ available as builtins.derivation. - builtins.bitXor - e1 e2 + + builtins.bitXor + e1 e2 Return the bitwise XOR of the integers e1 and @@ -122,7 +133,8 @@ available as builtins.derivation. - builtins + + builtins The set builtins contains all the built-in functions and values. You can use @@ -139,8 +151,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - builtins.compareVersions - s1 s2 + + builtins.compareVersions + s1 s2 Compare two strings representing versions and return -1 if version @@ -156,8 +169,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - builtins.splitVersion - s + + builtins.splitVersion + s Split a string representing a version into its components, by the same version splitting logic underlying the @@ -167,16 +181,18 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - builtins.concatLists - lists + + builtins.concatLists + lists Concatenate a list of lists into a single list. - builtins.concatStringsSep - separator list + + builtins.concatStringsSep + separator list Concatenate a list of strings with a separator between each element, e.g. concatStringsSep "/" @@ -184,8 +200,8 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - builtins.currentSystem + + builtins.currentSystem The built-in value currentSystem evaluates to the Nix platform identifier for the Nix installation @@ -218,8 +234,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" --> - builtins.deepSeq - e1 e2 + + builtins.deepSeq + e1 e2 This is like seq e1 @@ -231,8 +248,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - derivation - attrs + + derivation + attrs derivation is described in . @@ -240,7 +258,8 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - dirOf s + + dirOf s Return the directory part of the string s, that is, everything before the final @@ -250,8 +269,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - builtins.div - e1 e2 + + builtins.div + e1 e2 Return the quotient of the numbers e1 and @@ -259,8 +279,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - builtins.elem - x xs + + builtins.elem + x xs Return true if a value equal to x occurs in the list @@ -270,8 +291,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - builtins.elemAt - xs n + + builtins.elemAt + xs n Return element n from the list xs. Elements are counted @@ -281,8 +303,9 @@ if builtins ? getEnv then builtins.getEnv "PATH" else "" - builtins.fetchurl - url + + builtins.fetchurl + url Download the specified URL and return the path of the downloaded file. This function is not available if - fetchTarball - url + + fetchTarball + url Download the specified URL, unpack it and return the path of the unpacked tree. The file must be a tape archive @@ -346,7 +370,7 @@ stdenv.mkDerivation { … } - + builtins.fetchGit args @@ -546,7 +570,8 @@ stdenv.mkDerivation { - builtins.foldl’ + + builtins.foldl’ op nul list Reduce a list by applying a binary operator, from @@ -559,7 +584,8 @@ stdenv.mkDerivation { - builtins.functionArgs + + builtins.functionArgs f @@ -577,7 +603,8 @@ stdenv.mkDerivation { - builtins.fromJSON e + + builtins.fromJSON e Convert a JSON string to a Nix value. For example, @@ -592,8 +619,9 @@ builtins.fromJSON ''{"x": [1, 2, 3], "y": null}'' - builtins.genList - generator length + + builtins.genList + generator length Generate list of size length, with each element @@ -610,8 +638,9 @@ builtins.genList (x: x * x) 5 - builtins.getAttr - s set + + builtins.getAttr + s set getAttr returns the attribute named s from @@ -623,8 +652,9 @@ builtins.genList (x: x * x) 5 - builtins.getEnv - s + + builtins.getEnv + s getEnv returns the value of the environment variable s, or an empty @@ -641,8 +671,9 @@ builtins.genList (x: x * x) 5 - builtins.hasAttr - s set + + builtins.hasAttr + s set hasAttr returns true if set has an @@ -655,8 +686,9 @@ builtins.genList (x: x * x) 5 - builtins.hashString - type s + + builtins.hashString + type s Return a base-16 representation of the cryptographic hash of string s. The @@ -667,8 +699,9 @@ builtins.genList (x: x * x) 5 - builtins.head - list + + builtins.head + list Return the first element of a list; abort evaluation if the argument isn’t a list or is an empty list. You @@ -678,8 +711,9 @@ builtins.genList (x: x * x) 5 - import - path + + import + path Load, parse and return the Nix expression in the file path. If path @@ -733,8 +767,9 @@ x: x + 456 - builtins.intersectAttrs - e1 e2 + + builtins.intersectAttrs + e1 e2 Return a set consisting of the attributes in the set e2 that also exist in the set @@ -743,8 +778,9 @@ x: x + 456 - builtins.isAttrs - e + + builtins.isAttrs + e Return true if e evaluates to a set, and @@ -753,8 +789,9 @@ x: x + 456 - builtins.isList - e + + builtins.isList + e Return true if e evaluates to a list, and @@ -763,7 +800,7 @@ x: x + 456 - builtins.isFunction + builtins.isFunction e Return true if @@ -773,8 +810,9 @@ x: x + 456 - builtins.isString - e + + builtins.isString + e Return true if e evaluates to a string, and @@ -783,8 +821,9 @@ x: x + 456 - builtins.isInt - e + + builtins.isInt + e Return true if e evaluates to an int, and @@ -793,8 +832,9 @@ x: x + 456 - builtins.isFloat - e + + builtins.isFloat + e Return true if e evaluates to a float, and @@ -803,8 +843,9 @@ x: x + 456 - builtins.isBool - e + + builtins.isBool + e Return true if e evaluates to a bool, and @@ -813,8 +854,9 @@ x: x + 456 - isNull - e + + isNull + e Return true if e evaluates to null, @@ -828,8 +870,9 @@ x: x + 456 - builtins.length - e + + builtins.length + e Return the length of the list e. @@ -837,8 +880,9 @@ x: x + 456 - builtins.lessThan - e1 e2 + + builtins.lessThan + e1 e2 Return true if the number e1 is less than the number @@ -850,8 +894,9 @@ x: x + 456 - builtins.listToAttrs - e + + builtins.listToAttrs + e Construct a set from a list specifying the names and values of each attribute. Each element of the list should be @@ -877,8 +922,9 @@ builtins.listToAttrs - map - f list + + map + f list Apply the function f to each element in the list list. For @@ -893,14 +939,15 @@ map (x: "foo" + x) [ "bar" "bla" "abc" ] - builtins.match - regex str + + builtins.match + regex str - Returns a list if the extended - POSIX regular expression regex - matches str precisely, otherwise returns - null. Each item in the list is a regex group. + Returns a list if the extended + POSIX regular expression regex + matches str precisely, otherwise returns + null. Each item in the list is a regex group. builtins.match "ab" "abc" @@ -926,11 +973,12 @@ builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO " Evaluates to [ "foo" ]. - + - builtins.mul - e1 e2 + + builtins.mul + e1 e2 Return the product of the numbers e1 and @@ -939,8 +987,9 @@ Evaluates to [ "foo" ]. - builtins.parseDrvName - s + + builtins.parseDrvName + s Split the string s into a package name and version. The package name is everything up to @@ -953,7 +1002,7 @@ Evaluates to [ "foo" ]. - + builtins.path args @@ -1023,8 +1072,9 @@ Evaluates to [ "foo" ]. - builtins.pathExists - path + + builtins.pathExists + path Return true if the path path exists, and @@ -1047,8 +1097,9 @@ in config.someSetting - builtins.readDir - path + + builtins.readDir + path Return the contents of the directory path as a set mapping directory entries @@ -1069,8 +1120,9 @@ in config.someSetting - builtins.readFile - path + + builtins.readFile + path Return the contents of the file path as a string. @@ -1078,8 +1130,9 @@ in config.someSetting - removeAttrs - set list + + removeAttrs + set list Remove the attributes listed in list from @@ -1094,8 +1147,9 @@ removeAttrs { x = 1; y = 2; z = 3; } [ "a" "x" "z" ] - builtins.replaceStrings - from to s + + builtins.replaceStrings + from to s Given string s, replace every occurrence of the strings in from @@ -1111,8 +1165,9 @@ builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" - builtins.seq - e1 e2 + + builtins.seq + e1 e2 Evaluate e1, then evaluate and return e2. This ensures @@ -1122,8 +1177,9 @@ builtins.replaceStrings ["oo" "a"] ["a" "i"] "foobar" - builtins.sort - comparator list + + builtins.sort + comparator list Return list in sorted order. It repeatedly calls the function @@ -1145,15 +1201,16 @@ builtins.sort builtins.lessThan [ 483 249 526 147 42 77 ] - builtins.split - regex str + + builtins.split + regex str - Returns a list composed of non matched strings interleaved - with the lists of the extended - POSIX regular expression regex matches - of str. Each item in the lists of matched - sequences is a regex group. + Returns a list composed of non matched strings interleaved + with the lists of the extended + POSIX regular expression regex matches + of str. Each item in the lists of matched + sequences is a regex group. builtins.split "(a)b" "abc" @@ -1179,11 +1236,12 @@ builtins.split "([[:upper:]]+)" " FOO " Evaluates to [ " " [ "FOO" ] " " ]. - + - builtins.stringLength - e + + builtins.stringLength + e Return the length of the string e. If e is @@ -1192,8 +1250,9 @@ Evaluates to [ " " [ "FOO" ] " " ]. - builtins.sub - e1 e2 + + builtins.sub + e1 e2 Return the difference between the numbers e1 and @@ -1202,9 +1261,10 @@ Evaluates to [ " " [ "FOO" ] " " ]. - builtins.substring - start len - s + + builtins.substring + start len + s Return the substring of s from character position @@ -1227,8 +1287,9 @@ builtins.substring 0 3 "nixos" - builtins.tail - list + + builtins.tail + list Return the second to last elements of a list; abort evaluation if the argument isn’t a list or is an empty @@ -1237,8 +1298,9 @@ builtins.substring 0 3 "nixos" - throw - s + + throw + s Throw an error message s. This usually aborts Nix expression @@ -1251,9 +1313,10 @@ builtins.substring 0 3 "nixos" - builtins.toFile - name s + + builtins.toFile + name + s Store the string s in a file in the Nix store and return its path. The file has suffix @@ -1329,7 +1392,8 @@ in foo - builtins.toJSON e + + builtins.toJSON e Return a string containing a JSON representation of e. Strings, integers, floats, booleans, @@ -1342,7 +1406,8 @@ in foo - builtins.toPath s + + builtins.toPath s Convert the string value s into a path value. The string @@ -1355,7 +1420,8 @@ in foo - toString e + + toString e Convert the expression e to a string. @@ -1374,7 +1440,8 @@ in foo - builtins.toXML e + + builtins.toXML e Return a string containing an XML representation of e. The main application for @@ -1489,8 +1556,9 @@ stdenv.mkDerivation (rec { - builtins.trace - e1 e2 + + builtins.trace + e1 e2 Evaluate e1 and print its abstract syntax representation on standard error. Then return @@ -1499,8 +1567,9 @@ stdenv.mkDerivation (rec { - builtins.tryEval - e + + builtins.tryEval + e Try to evaluate e. Return a set containing the attributes success @@ -1513,8 +1582,9 @@ stdenv.mkDerivation (rec { - builtins.typeOf - e + + builtins.typeOf + e Return a string representing the type of the value e, namely "int",