hsjobeki/noogle
1
1
Fork 0
mirror of https://github.com/hsjobeki/noogle.git synced 2024-12-20 20:31:32 +03:00
Code Issues Projects Releases Wiki Activity
334a8271aa
noogle/models/data.json

2554 lines
111 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[
{
"category": "./lib/customisation.nix",
"name": "overrideDerivation",
"fn_type": null,
"description": [
"`overrideDerivation drv f' takes a derivation (i.e., the result\nof a call to the builtin function `derivation') and returns a new\nderivation in which the attributes of the original are overridden\naccording to the function `f'. The function `f' is called with\nthe original derivation attributes.",
"`overrideDerivation' allows certain \"ad-hoc\" customisation\nscenarios (e.g. in ~/.config/nixpkgs/config.nix). For instance,\nif you want to \"patch\" the derivation returned by a package\nfunction in Nixpkgs to build another version than what the\nfunction itself provides, you can do something like this:",
"mySed = overrideDerivation pkgs.gnused (oldAttrs: {\nname = \"sed-4.2.2-pre\";\nsrc = fetchurl {\nurl = ftp://alpha.gnu.org/gnu/sed/sed-4.2.2-pre.tar.bz2;\nsha256 = \"11nq06d131y4wmf3drm0yk502d2xc6n5qy82cg88rb9nqd2lj41k\";\n};\npatches = [];\n});",
"For another application, see build-support/vm, where this\nfunction is used to build arbitrary derivations inside a QEMU\nvirtual machine."
],
"example": null
},
{
"category": "./lib/customisation.nix",
"name": "makeOverridable",
"fn_type": null,
"description": [
"`makeOverridable` takes a function from attribute set to attribute set and\ninjects `override` attribute which can be used to override arguments of\nthe function.",
"nix-repl> x = {a, b}: { result = a + b; }",
"nix-repl> y = lib.makeOverridable x { a = 1; b = 2; }",
"nix-repl> y\n{ override = «lambda»; overrideDerivation = «lambda»; result = 3; }",
"nix-repl> y.override { a = 10; }\n{ override = «lambda»; overrideDerivation = «lambda»; result = 12; }",
"Please refer to \"Nixpkgs Contributors Guide\" section\n\"<pkg>.overrideDerivation\" to learn about `overrideDerivation` and caveats\nrelated to its use."
],
"example": null
},
{
"category": "./lib/customisation.nix",
"name": "callPackageWith",
"fn_type": null,
"description": [
"Call the package function in the file `fn' with the required\narguments automatically. The function is called with the\narguments `args', but any missing arguments are obtained from\n`autoArgs'. This function is intended to be partially\nparameterised, e.g.,",
"callPackage = callPackageWith pkgs;\npkgs = {\nlibfoo = callPackage ./foo.nix { };\nlibbar = callPackage ./bar.nix { };\n};",
"If the `libbar' function expects an argument named `libfoo', it is\nautomatically passed as an argument. Overrides or missing\narguments can be supplied in `args', e.g.",
"libbar = callPackage ./bar.nix {\nlibfoo = null;\nenableX11 = true;\n};"
],
"example": null
},
{
"category": "./lib/customisation.nix",
"name": "callPackagesWith",
"fn_type": null,
"description": [
"Like callPackage, but for a function that returns an attribute\nset of derivations. The override function is added to the\nindividual attributes."
],
"example": null
},
{
"category": "./lib/customisation.nix",
"name": "extendDerivation",
"fn_type": null,
"description": [
"Add attributes to each output of a derivation without changing\nthe derivation itself and check a given condition when evaluating."
],
"example": null
},
{
"category": "./lib/customisation.nix",
"name": "hydraJob",
"fn_type": null,
"description": [
"Strip a derivation of all non-essential attributes, returning\nonly those needed by hydra-eval-jobs. Also strictly evaluate the\nresult to ensure that there are no thunks kept alive to prevent\ngarbage collection."
],
"example": null
},
{
"category": "./lib/customisation.nix",
"name": "makeScope",
"fn_type": null,
"description": [
"Make a set of packages with a common scope. All packages called\nwith the provided `callPackage' will be evaluated with the same\narguments. Any package in the set may depend on any other. The\n`overrideScope'` function allows subsequent modification of the package\nset in a consistent way, i.e. all packages in the set will be\ncalled with the overridden packages. The package sets may be\nhierarchical: the packages in the set are called with the scope\nprovided by `newScope' and the set provides a `newScope' attribute\nwhich can form the parent scope for later package sets."
],
"example": null
},
{
"category": "./lib/customisation.nix",
"name": "makeScopeWithSplicing",
"fn_type": null,
"description": [
"Like the above, but aims to support cross compilation. It's still ugly, but\nhopefully it helps a little bit."
],
"example": null
},
{
"category": "./lib/lists.nix",
"name": "singleton",
"fn_type": "singleton :: a -> [a]",
"description": [
"Create a list consisting of a single element. `singleton x` is\nsometimes more convenient with respect to indentation than `[x]`\nwhen x spans multiple lines."
],
"example": "\nsingleton \"foo\"\n=> [ \"foo\" ]\n"
},
{
"category": "./lib/lists.nix",
"name": "forEach",
"fn_type": "forEach :: [a] -> (a -> b) -> [b]",
"description": [
"Apply the function to each element in the list. Same as `map`, but arguments\nflipped."
],
"example": "\nforEach [ 1 2 ] (x:\ntoString x\n)\n=> [ \"1\" \"2\" ]\n"
},
{
"category": "./lib/lists.nix",
"name": "foldr",
"fn_type": "foldr :: (a -> b -> b) -> b -> [a] -> b",
"description": [
"“right fold” a binary function `op` between successive elements of\n`list` with `nul` as the starting value, i.e.,\n`foldr op nul [x_1 x_2 ... x_n] == op x_1 (op x_2 ... (op x_n nul))`."
],
"example": "\nconcat = foldr (a: b: a + b) \"z\"\nconcat [ \"a\" \"b\" \"c\" ]\n=> \"abcz\"\n# different types\nstrange = foldr (int: str: toString (int + 1) + str) \"a\"\nstrange [ 1 2 3 4 ]\n=> \"2345a\"\n"
},
{
"category": "./lib/lists.nix",
"name": "fold",
"fn_type": null,
"description": ["`fold` is an alias of `foldr` for historic reasons"],
"example": null
},
{
"category": "./lib/lists.nix",
"name": "foldl",
"fn_type": "foldl :: (b -> a -> b) -> b -> [a] -> b",
"description": [
"“left fold”, like `foldr`, but from the left:\n`foldl op nul [x_1 x_2 ... x_n] == op (... (op (op nul x_1) x_2) ... x_n)`."
],
"example": "\nlconcat = foldl (a: b: a + b) \"z\"\nlconcat [ \"a\" \"b\" \"c\" ]\n=> \"zabc\"\n# different types\nlstrange = foldl (str: int: str + toString (int + 1)) \"a\"\nlstrange [ 1 2 3 4 ]\n=> \"a2345\"\n"
},
{
"category": "./lib/lists.nix",
"name": "foldl'",
"fn_type": "foldl' :: (b -> a -> b) -> b -> [a] -> b",
"description": [
"Strict version of `foldl`.",
"The difference is that evaluation is forced upon access. Usually used\nwith small whole results (in contrast with lazily-generated list or large\nlists where only a part is consumed.)"
],
"example": null
},
{
"category": "./lib/lists.nix",
"name": "imap0",
"fn_type": "imap0 :: (int -> a -> b) -> [a] -> [b]",
"description": ["Map with index starting from 0"],
"example": "\nimap0 (i: v: \"${v}-${toString i}\") [\"a\" \"b\"]\n=> [ \"a-0\" \"b-1\" ]\n"
},
{
"category": "./lib/lists.nix",
"name": "imap1",
"fn_type": "imap1 :: (int -> a -> b) -> [a] -> [b]",
"description": ["Map with index starting from 1"],
"example": "\nimap1 (i: v: \"${v}-${toString i}\") [\"a\" \"b\"]\n=> [ \"a-1\" \"b-2\" ]\n"
},
{
"category": "./lib/lists.nix",
"name": "concatMap",
"fn_type": "concatMap :: (a -> [b]) -> [a] -> [b]",
"description": ["Map and concatenate the result."],
"example": "\nconcatMap (x: [x] ++ [\"z\"]) [\"a\" \"b\"]\n=> [ \"a\" \"z\" \"b\" \"z\" ]\n"
},
{
"category": "./lib/lists.nix",
"name": "flatten",
"fn_type": null,
"description": [
"Flatten the argument into a single list; that is, nested lists are\nspliced into the top-level lists."
],
"example": "\nflatten [1 [2 [3] 4] 5]\n=> [1 2 3 4 5]\nflatten 1\n=> [1]\n"
},
{
"category": "./lib/lists.nix",
"name": "remove",
"fn_type": "remove :: a -> [a] -> [a]",
"description": [
"Remove elements equal to 'e' from a list. Useful for buildInputs."
],
"example": "\nremove 3 [ 1 3 4 3 ]\n=> [ 1 4 ]\n"
},
{
"category": "./lib/lists.nix",
"name": "findSingle",
"fn_type": "findSingle :: (a -> bool) -> a -> a -> [a] -> a",
"description": [
"Find the sole element in the list matching the specified\npredicate, returns `default` if no such element exists, or\n`multiple` if there are multiple matching elements."
],
"example": "\nfindSingle (x: x == 3) \"none\" \"multiple\" [ 1 3 3 ]\n=> \"multiple\"\nfindSingle (x: x == 3) \"none\" \"multiple\" [ 1 3 ]\n=> 3\nfindSingle (x: x == 3) \"none\" \"multiple\" [ 1 9 ]\n=> \"none\"\n"
},
{
"category": "./lib/lists.nix",
"name": "findFirst",
"fn_type": "findFirst :: (a -> bool) -> a -> [a] -> a",
"description": [
"Find the first element in the list matching the specified\npredicate or return `default` if no such element exists."
],
"example": "\nfindFirst (x: x > 3) 7 [ 1 6 4 ]\n=> 6\nfindFirst (x: x > 9) 7 [ 1 6 4 ]\n=> 7\n"
},
{
"category": "./lib/lists.nix",
"name": "any",
"fn_type": "any :: (a -> bool) -> [a] -> bool",
"description": [
"Return true if function `pred` returns true for at least one\nelement of `list`."
],
"example": "\nany isString [ 1 \"a\" { } ]\n=> true\nany isString [ 1 { } ]\n=> false\n"
},
{
"category": "./lib/lists.nix",
"name": "all",
"fn_type": "all :: (a -> bool) -> [a] -> bool",
"description": [
"Return true if function `pred` returns true for all elements of\n`list`."
],
"example": "\nall (x: x < 3) [ 1 2 ]\n=> true\nall (x: x < 3) [ 1 2 3 ]\n=> false\n"
},
{
"category": "./lib/lists.nix",
"name": "count",
"fn_type": "count :: (a -> bool) -> [a] -> int",
"description": [
"Count how many elements of `list` match the supplied predicate\nfunction."
],
"example": "\ncount (x: x == 3) [ 3 2 3 4 6 ]\n=> 2\n"
},
{
"category": "./lib/lists.nix",
"name": "optional",
"fn_type": "optional :: bool -> a -> [a]",
"description": [
"Return a singleton list or an empty list, depending on a boolean\nvalue. Useful when building lists with optional elements\n(e.g. `++ optional (system == \"i686-linux\") firefox')."
],
"example": "\noptional true \"foo\"\n=> [ \"foo\" ]\noptional false \"foo\"\n=> [ ]\n"
},
{
"category": "./lib/lists.nix",
"name": "optionals",
"fn_type": "optionals :: bool -> [a] -> [a]",
"description": [
"Return a list or an empty list, depending on a boolean value."
],
"example": "\noptionals true [ 2 3 ]\n=> [ 2 3 ]\noptionals false [ 2 3 ]\n=> [ ]\n"
},
{
"category": "./lib/lists.nix",
"name": "toList",
"fn_type": null,
"description": [
"If argument is a list, return it; else, wrap it in a singleton\nlist. If you're using this, you should almost certainly\nreconsider if there isn't a more \"well-typed\" approach."
],
"example": "\ntoList [ 1 2 ]\n=> [ 1 2 ]\ntoList \"hi\"\n=> [ \"hi \"]\n"
},
{
"category": "./lib/lists.nix",
"name": "range",
"fn_type": "range :: int -> int -> [int]",
"description": [
"Return a list of integers from `first' up to and including `last'."
],
"example": "\nrange 2 4\n=> [ 2 3 4 ]\nrange 3 2\n=> [ ]\n"
},
{
"category": "./lib/lists.nix",
"name": "partition",
"fn_type": "(a -> bool) -> [a] -> { right :: [a], wrong :: [a] }",
"description": [
"Splits the elements of a list in two lists, `right` and\n`wrong`, depending on the evaluation of a predicate."
],
"example": "\npartition (x: x > 2) [ 5 1 2 3 4 ]\n=> { right = [ 5 3 4 ]; wrong = [ 1 2 ]; }\n"
},
{
"category": "./lib/lists.nix",
"name": "groupBy'",
"fn_type": null,
"description": [
"Splits the elements of a list into many lists, using the return value of a predicate.\nPredicate should return a string which becomes keys of attrset `groupBy' returns.",
"`groupBy'` allows to customise the combining function and initial value"
],
"example": "\ngroupBy (x: boolToString (x > 2)) [ 5 1 2 3 4 ]\n=> { true = [ 5 3 4 ]; false = [ 1 2 ]; }\ngroupBy (x: x.name) [ {name = \"icewm\"; script = \"icewm &\";}\n{name = \"xfce\"; script = \"xfce4-session &\";}\n{name = \"icewm\"; script = \"icewmbg &\";}\n{name = \"mate\"; script = \"gnome-session &\";}\n]\n=> { icewm = [ { name = \"icewm\"; script = \"icewm &\"; }\n{ name = \"icewm\"; script = \"icewmbg &\"; } ];\nmate = [ { name = \"mate\"; script = \"gnome-session &\"; } ];\nxfce = [ { name = \"xfce\"; script = \"xfce4-session &\"; } ];\n}\n\ngroupBy' builtins.add 0 (x: boolToString (x > 2)) [ 5 1 2 3 4 ]\n=> { true = 12; false = 3; }\n"
},
{
"category": "./lib/lists.nix",
"name": "zipListsWith",
"fn_type": "zipListsWith :: (a -> b -> c) -> [a] -> [b] -> [c]",
"description": [
"Merges two lists of the same size together. If the sizes aren't the same\nthe merging stops at the shortest. How both lists are merged is defined\nby the first argument."
],
"example": "\nzipListsWith (a: b: a + b) [\"h\" \"l\"] [\"e\" \"o\"]\n=> [\"he\" \"lo\"]\n"
},
{
"category": "./lib/lists.nix",
"name": "zipLists",
"fn_type": "zipLists :: [a] -> [b] -> [{ fst :: a, snd :: b}]",
"description": [
"Merges two lists of the same size together. If the sizes aren't the same\nthe merging stops at the shortest."
],
"example": "\nzipLists [ 1 2 ] [ \"a\" \"b\" ]\n=> [ { fst = 1; snd = \"a\"; } { fst = 2; snd = \"b\"; } ]\n"
},
{
"category": "./lib/lists.nix",
"name": "reverseList",
"fn_type": "reverseList :: [a] -> [a]",
"description": ["Reverse the order of the elements of a list."],
"example": "\n\nreverseList [ \"b\" \"o\" \"j\" ]\n=> [ \"j\" \"o\" \"b\" ]\n"
},
{
"category": "./lib/lists.nix",
"name": "listDfs",
"fn_type": null,
"description": [
"Depth-First Search (DFS) for lists `list != []`.",
"`before a b == true` means that `b` depends on `a` (there's an\nedge from `b` to `a`)."
],
"example": "\nlistDfs true hasPrefix [ \"/home/user\" \"other\" \"/\" \"/home\" ]\n== { minimal = \"/\"; # minimal element\nvisited = [ \"/home/user\" ]; # seen elements (in reverse order)\nrest = [ \"/home\" \"other\" ]; # everything else\n}\n\nlistDfs true hasPrefix [ \"/home/user\" \"other\" \"/\" \"/home\" \"/\" ]\n== { cycle = \"/\"; # cycle encountered at this element\nloops = [ \"/\" ]; # and continues to these elements\nvisited = [ \"/\" \"/home/user\" ]; # elements leading to the cycle (in reverse order)\nrest = [ \"/home\" \"other\" ]; # everything else\n"
},
{
"category": "./lib/lists.nix",
"name": "toposort",
"fn_type": null,
"description": [
"Sort a list based on a partial ordering using DFS. This\nimplementation is O(N^2), if your ordering is linear, use `sort`\ninstead.",
"`before a b == true` means that `b` should be after `a`\nin the result."
],
"example": "\n\ntoposort hasPrefix [ \"/home/user\" \"other\" \"/\" \"/home\" ]\n== { result = [ \"/\" \"/home\" \"/home/user\" \"other\" ]; }\n\ntoposort hasPrefix [ \"/home/user\" \"other\" \"/\" \"/home\" \"/\" ]\n== { cycle = [ \"/home/user\" \"/\" \"/\" ]; # path leading to a cycle\nloops = [ \"/\" ]; } # loops back to these elements\n\ntoposort hasPrefix [ \"other\" \"/home/user\" \"/home\" \"/\" ]\n== { result = [ \"other\" \"/\" \"/home\" \"/home/user\" ]; }\n\ntoposort (a: b: a < b) [ 3 2 1 ] == { result = [ 1 2 3 ]; }\n"
},
{
"category": "./lib/lists.nix",
"name": "sort",
"fn_type": null,
"description": [
"Sort a list based on a comparator function which compares two\nelements and returns true if the first argument is strictly below\nthe second argument. The returned list is sorted in an increasing\norder. The implementation does a quick-sort."
],
"example": "\nsort (a: b: a < b) [ 5 3 7 ]\n=> [ 3 5 7 ]\n"
},
{
"category": "./lib/lists.nix",
"name": "compareLists",
"fn_type": null,
"description": ["Compare two lists element-by-element."],
"example": "\ncompareLists compare [] []\n=> 0\ncompareLists compare [] [ \"a\" ]\n=> -1\ncompareLists compare [ \"a\" ] []\n=> 1\ncompareLists compare [ \"a\" \"b\" ] [ \"a\" \"c\" ]\n=> -1\n"
},
{
"category": "./lib/lists.nix",
"name": "naturalSort",
"fn_type": null,
"description": [
"Sort list using \"Natural sorting\".\nNumeric portions of strings are sorted in numeric order."
],
"example": "\nnaturalSort [\"disk11\" \"disk8\" \"disk100\" \"disk9\"]\n=> [\"disk8\" \"disk9\" \"disk11\" \"disk100\"]\nnaturalSort [\"10.46.133.149\" \"10.5.16.62\" \"10.54.16.25\"]\n=> [\"10.5.16.62\" \"10.46.133.149\" \"10.54.16.25\"]\nnaturalSort [\"v0.2\" \"v0.15\" \"v0.0.9\"]\n=> [ \"v0.0.9\" \"v0.2\" \"v0.15\" ]\n"
},
{
"category": "./lib/lists.nix",
"name": "take",
"fn_type": "take :: int -> [a] -> [a]",
"description": ["Return the first (at most) N elements of a list."],
"example": "\ntake 2 [ \"a\" \"b\" \"c\" \"d\" ]\n=> [ \"a\" \"b\" ]\ntake 2 [ ]\n=> [ ]\n"
},
{
"category": "./lib/lists.nix",
"name": "drop",
"fn_type": "drop :: int -> [a] -> [a]",
"description": ["Remove the first (at most) N elements of a list."],
"example": "\ndrop 2 [ \"a\" \"b\" \"c\" \"d\" ]\n=> [ \"c\" \"d\" ]\ndrop 2 [ ]\n=> [ ]\n"
},
{
"category": "./lib/lists.nix",
"name": "sublist",
"fn_type": "sublist :: int -> int -> [a] -> [a]",
"description": [
"Return a list consisting of at most `count` elements of `list`,\nstarting at index `start`."
],
"example": "\nsublist 1 3 [ \"a\" \"b\" \"c\" \"d\" \"e\" ]\n=> [ \"b\" \"c\" \"d\" ]\nsublist 1 3 [ ]\n=> [ ]\n"
},
{
"category": "./lib/lists.nix",
"name": "last",
"fn_type": "last :: [a] -> a",
"description": [
"Return the last element of a list.",
"This function throws an error if the list is empty."
],
"example": "\nlast [ 1 2 3 ]\n=> 3\n"
},
{
"category": "./lib/lists.nix",
"name": "init",
"fn_type": "init :: [a] -> [a]",
"description": [
"Return all elements but the last.",
"This function throws an error if the list is empty."
],
"example": "\ninit [ 1 2 3 ]\n=> [ 1 2 ]\n"
},
{
"category": "./lib/lists.nix",
"name": "crossLists",
"fn_type": null,
"description": [
"Return the image of the cross product of some lists by a function."
],
"example": "\ncrossLists (x:y: \"${toString x}${toString y}\") [[1 2] [3 4]]\n=> [ \"13\" \"14\" \"23\" \"24\" ]\n"
},
{
"category": "./lib/lists.nix",
"name": "unique",
"fn_type": "unique :: [a] -> [a]",
"description": [
"Remove duplicate elements from the list. O(n^2) complexity."
],
"example": "\nunique [ 3 2 3 4 ]\n=> [ 3 2 4 ]\n"
},
{
"category": "./lib/lists.nix",
"name": "intersectLists",
"fn_type": null,
"description": ["Intersects list 'e' and another list. O(nm) complexity."],
"example": "\nintersectLists [ 1 2 3 ] [ 6 3 2 ]\n=> [ 3 2 ]\n"
},
{
"category": "./lib/lists.nix",
"name": "subtractLists",
"fn_type": null,
"description": ["Subtracts list 'e' from another list. O(nm) complexity."],
"example": "\nsubtractLists [ 3 2 ] [ 1 2 3 4 5 3 ]\n=> [ 1 4 5 ]\n"
},
{
"category": "./lib/lists.nix",
"name": "mutuallyExclusive",
"fn_type": null,
"description": [
"Test if two lists have no common element.\nIt should be slightly more efficient than (intersectLists a b == [])"
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "evalModules",
"fn_type": null,
"description": [
"Evaluate a set of modules. The result is a set with the attributes:",
"‘options’: The nested set of all option declarations,",
"‘config’: The nested set of all option values.",
"‘type’: A module system type representing the module set as a submodule,\nto be extended by configuration from the containing module set.",
"This is also available as the module argument ‘moduleType’.",
"‘extendModules’: A function similar to ‘evalModules’ but building on top\nof the module set. Its arguments, ‘modules’ and ‘specialArgs’ are\nadded to the existing values.",
"Using ‘extendModules’ a few times has no performance impact as long\nas you only reference the final ‘options’ and ‘config’.\nIf you do reference multiple ‘config’ (or ‘options’) from before and\nafter ‘extendModules’, performance is the same as with multiple\n‘evalModules’ invocations, because the new modules' ability to\noverride existing configuration fundamentally requires a new\nfixpoint to be constructed.",
"This is also available as a module argument.",
"‘_module’: A portion of the configuration tree which is elided from\n‘config’. It contains some values that are mostly internal to the\nmodule system implementation.",
"!!! Please think twice before adding to this argument list! The more\nthat is specified here instead of in the modules themselves the harder\nit is to transparently move a set of modules to be a submodule of another\nconfig (as the proper arguments need to be replicated at each call to\nevalModules) and the less declarative the module set is."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "collectStructuredModules",
"fn_type": null,
"description": [
"Collects all modules recursively into the form",
"{\ndisabled = [ <list of disabled modules> ];\n# All modules of the main module list\nmodules = [\n{\nkey = <key1>;\nmodule = <module for key1>;\n# All modules imported by the module for key1\nmodules = [\n{\nkey = <key1-1>;\nmodule = <module for key1-1>;\n# All modules imported by the module for key1-1\nmodules = [ ... ];\n}\n...\n];\n}\n...\n];\n}"
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "setDefaultModuleLocation",
"fn_type": null,
"description": [
"Wrap a module with a default location for reporting errors."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "unifyModuleSyntax",
"fn_type": null,
"description": [
"Massage a module into canonical form, that is, a set consisting\nof ‘options’, ‘config’ and ‘imports’ attributes."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mergeModules",
"fn_type": null,
"description": [
"Merge a list of modules. This will recurse over the option\ndeclarations in all modules, combining them into a single set.\nAt the same time, for each option declaration, it will merge the\ncorresponding option definitions in all machines, returning them\nin the ‘value’ attribute of each option.",
"This returns a set like\n{\n# A recursive set of options along with their final values\nmatchedOptions = {\nfoo = { _type = \"option\"; value = \"option value of foo\"; ... };\nbar.baz = { _type = \"option\"; value = \"option value of bar.baz\"; ... };\n...\n};\n# A list of definitions that weren't matched by any option\nunmatchedDefns = [\n{ file = \"file.nix\"; prefix = [ \"qux\" ]; value = \"qux\"; }\n...\n];\n}"
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "byName",
"fn_type": null,
"description": [
"byName is like foldAttrs, but will look for attributes to merge in the\nspecified attribute name.",
"byName \"foo\" (module: value: [\"module.hidden=${module.hidden},value=${value}\"])\n[\n{\nhidden=\"baz\";\nfoo={qux=\"bar\"; gla=\"flop\";};\n}\n{\nhidden=\"fli\";\nfoo={qux=\"gne\"; gli=\"flip\";};\n}\n]\n===>\n{\ngla = [ \"module.hidden=baz,value=flop\" ];\ngli = [ \"module.hidden=fli,value=flip\" ];\nqux = [ \"module.hidden=baz,value=bar\" \"module.hidden=fli,value=gne\" ];\n}"
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mergeOptionDecls",
"fn_type": null,
"description": [
"Merge multiple option declarations into a single declaration. In\ngeneral, there should be only one declaration of each option.\nThe exception is the ‘options’ attribute, which specifies\nsub-options. These can be specified multiple times to allow one\nmodule to add sub-options to an option declared somewhere else\n(e.g. multiple modules define sub-options for ‘fileSystems’).",
"'loc' is the list of attribute names where the option is located.",
"'opts' is a list of modules. Each module has an options attribute which\ncorrespond to the definition of 'loc' in 'opt.file'."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "evalOptionValue",
"fn_type": null,
"description": [
"Merge all the definitions of an option to produce the final\nconfig value."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "pushDownProperties",
"fn_type": null,
"description": [
"Given a config set, expand mkMerge properties, and push down the\nother properties into the children. The result is a list of\nconfig sets that do not have properties at top-level. For\nexample,",
"mkMerge [ { boot = set1; } (mkIf cond { boot = set2; services = set3; }) ]",
"is transformed into",
"[ { boot = set1; } { boot = mkIf cond set2; services = mkIf cond set3; } ].",
"This transform is the critical step that allows mkIf conditions\nto refer to the full configuration without creating an infinite\nrecursion."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "dischargeProperties",
"fn_type": null,
"description": [
"Given a config value, expand mkMerge properties, and discharge\nany mkIf conditions. That is, this is the place where mkIf\nconditions are actually evaluated. The result is a list of\nconfig values. For example, ‘mkIf false x’ yields ‘[]’,\n‘mkIf true x’ yields ‘[x]’, and",
"mkMerge [ 1 (mkIf true 2) (mkIf true (mkIf false 3)) ]",
"yields ‘[ 1 2 ]’."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "filterOverrides",
"fn_type": null,
"description": [
"Given a list of config values, process the mkOverride properties,\nthat is, return the values that have the highest (that is,\nnumerically lowest) priority, and strip the mkOverride\nproperties. For example,",
"[ { file = \"/1\"; value = mkOverride 10 \"a\"; }\n{ file = \"/2\"; value = mkOverride 20 \"b\"; }\n{ file = \"/3\"; value = \"z\"; }\n{ file = \"/4\"; value = mkOverride 10 \"d\"; }\n]",
"yields",
"[ { file = \"/1\"; value = \"a\"; }\n{ file = \"/4\"; value = \"d\"; }\n]",
"Note that \"z\" has the default priority 100."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "sortProperties",
"fn_type": null,
"description": [
"Sort a list of properties. The sort priority of a property is\n1000 by default, but can be overridden by wrapping the property\nusing mkOrder."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mkIf",
"fn_type": null,
"description": ["Properties."],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "fixMergeModules",
"fn_type": null,
"description": ["Compatibility."],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mkRemovedOptionModule",
"fn_type": null,
"description": [
"Return a module that causes a warning to be shown if the\nspecified option is defined. For example,",
"mkRemovedOptionModule [ \"boot\" \"loader\" \"grub\" \"bootDevice\" ] \"<replacement instructions>\"",
"causes a assertion if the user defines boot.loader.grub.bootDevice.",
"replacementInstructions is a string that provides instructions on\nhow to achieve the same functionality without the removed option,\nor alternatively a reasoning why the functionality is not needed.\nreplacementInstructions SHOULD be provided!"
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mkRenamedOptionModule",
"fn_type": null,
"description": [
"Return a module that causes a warning to be shown if the\nspecified \"from\" option is defined; the defined value is however\nforwarded to the \"to\" option. This can be used to rename options\nwhile providing backward compatibility. For example,",
"mkRenamedOptionModule [ \"boot\" \"copyKernels\" ] [ \"boot\" \"loader\" \"grub\" \"copyKernels\" ]",
"forwards any definitions of boot.copyKernels to\nboot.loader.grub.copyKernels while printing a warning.",
"This also copies over the priority from the aliased option to the\nnon-aliased option."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mkMergedOptionModule",
"fn_type": null,
"description": [
"Return a module that causes a warning to be shown if any of the \"from\"\noption is defined; the defined values can be used in the \"mergeFn\" to set\nthe \"to\" value.\nThis function can be used to merge multiple options into one that has a\ndifferent type.",
"\"mergeFn\" takes the module \"config\" as a parameter and must return a value\nof \"to\" option type.",
"mkMergedOptionModule\n[ [ \"a\" \"b\" \"c\" ]\n[ \"d\" \"e\" \"f\" ] ]\n[ \"x\" \"y\" \"z\" ]\n(config:\nlet value = p: getAttrFromPath p config;\nin\nif (value [ \"a\" \"b\" \"c\" ]) == true then \"foo\"\nelse if (value [ \"d\" \"e\" \"f\" ]) == true then \"bar\"\nelse \"baz\")",
"- options.a.b.c is a removed boolean option\n- options.d.e.f is a removed boolean option\n- options.x.y.z is a new str option that combines a.b.c and d.e.f\nfunctionality",
"This show a warning if any a.b.c or d.e.f is set, and set the value of\nx.y.z to the result of the merge function"
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mkChangedOptionModule",
"fn_type": null,
"description": [
"Single \"from\" version of mkMergedOptionModule.\nReturn a module that causes a warning to be shown if the \"from\" option is\ndefined; the defined value can be used in the \"mergeFn\" to set the \"to\"\nvalue.\nThis function can be used to change an option into another that has a\ndifferent type.",
"\"mergeFn\" takes the module \"config\" as a parameter and must return a value of\n\"to\" option type.",
"mkChangedOptionModule [ \"a\" \"b\" \"c\" ] [ \"x\" \"y\" \"z\" ]\n(config:\nlet value = getAttrFromPath [ \"a\" \"b\" \"c\" ] config;\nin\nif value > 100 then \"high\"\nelse \"normal\")",
"- options.a.b.c is a removed int option\n- options.x.y.z is a new str option that supersedes a.b.c",
"This show a warning if a.b.c is set, and set the value of x.y.z to the\nresult of the change function"
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mkAliasOptionModule",
"fn_type": null,
"description": [
"Like ‘mkRenamedOptionModule’, but doesn't show a warning."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "mkDerivedConfig",
"fn_type": null,
"description": [
"mkDerivedConfig : Option a -> (a -> Definition b) -> Definition b",
"Create config definitions with the same priority as the definition of another option.\nThis should be used for option definitions where one option sets the value of another as a convenience.\nFor instance a config file could be set with a `text` or `source` option, where text translates to a `source`\nvalue using `mkDerivedConfig options.text (pkgs.writeText \"filename.conf\")`.",
"It takes care of setting the right priority using `mkOverride`."
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "importJSON",
"fn_type": null,
"description": [
"Use this function to import a JSON file as NixOS configuration.",
"modules.importJSON :: path -> attrs"
],
"example": null
},
{
"category": "./lib/modules.nix",
"name": "importTOML",
"fn_type": null,
"description": [
"Use this function to import a TOML file as NixOS configuration.",
"modules.importTOML :: path -> attrs"
],
"example": null
},
{
"category": "./lib/versions.nix",
"name": "splitVersion",
"fn_type": null,
"description": ["Break a version string into its component parts."],
"example": "\nsplitVersion \"1.2.3\"\n=> [\"1\" \"2\" \"3\"]\n"
},
{
"category": "./lib/versions.nix",
"name": "major",
"fn_type": null,
"description": ["Get the major version string from a string."],
"example": "\nmajor \"1.2.3\"\n=> \"1\"\n"
},
{
"category": "./lib/versions.nix",
"name": "minor",
"fn_type": null,
"description": ["Get the minor version string from a string."],
"example": "\nminor \"1.2.3\"\n=> \"2\"\n"
},
{
"category": "./lib/versions.nix",
"name": "patch",
"fn_type": null,
"description": ["Get the patch version string from a string."],
"example": "\npatch \"1.2.3\"\n=> \"3\"\n"
},
{
"category": "./lib/versions.nix",
"name": "majorMinor",
"fn_type": null,
"description": [
"Get string of the first two parts (major and minor)\nof a version string."
],
"example": "\nmajorMinor \"1.2.3\"\n=> \"1.2\"\n"
},
{
"category": "./lib/asserts.nix",
"name": "assertMsg",
"fn_type": "assertMsg :: Bool -> String -> Bool",
"description": [
"Throw if pred is false, else return pred.\nIntended to be used to augment asserts with helpful error messages."
],
"example": "\nassertMsg false \"nope\"\nstderr> error: nope\n\nassert assertMsg (\"foo\" == \"bar\") \"foo is not bar, silly\"; \"\"\nstderr> error: foo is not bar, silly\n\n"
},
{
"category": "./lib/asserts.nix",
"name": "assertOneOf",
"fn_type": "assertOneOf :: String -> ComparableVal -> List ComparableVal -> Bool",
"description": [
"Specialized `assertMsg` for checking if val is one of the elements\nof a list. Useful for checking enums."
],
"example": "\nlet sslLibrary = \"libressl\";\nin assertOneOf \"sslLibrary\" sslLibrary [ \"openssl\" \"bearssl\" ]\nstderr> error: sslLibrary must be one of [\nstderr> \"openssl\"\nstderr> \"bearssl\"\nstderr> ], but is: \"libressl\"\n\n"
},
{
"category": "./lib/options.nix",
"name": "isOption",
"fn_type": "isOption :: a -> bool",
"description": ["Returns true when the given argument is an option"],
"example": "\nisOption 1 // => false\nisOption (mkOption {}) // => true\n"
},
{
"category": "./lib/options.nix",
"name": "mkOption",
"fn_type": null,
"description": [
"Creates an Option attribute set. mkOption accepts an attribute set with the following keys:",
"All keys default to `null` when not given."
],
"example": "\nmkOption { } // => { _type = \"option\"; }\nmkOption { default = \"foo\"; } // => { _type = \"option\"; default = \"foo\"; }\n"
},
{
"category": "./lib/options.nix",
"name": "mkEnableOption",
"fn_type": null,
"description": [
"Creates an Option attribute set for a boolean value option i.e an\noption to be toggled on or off:"
],
"example": "\nmkEnableOption \"foo\"\n=> { _type = \"option\"; default = false; description = \"Whether to enable foo.\"; example = true; type = { ... }; }\n"
},
{
"category": "./lib/options.nix",
"name": "mkPackageOption",
"fn_type": "mkPackageOption :: pkgs -> string -> { default :: [string], example :: null | string | [string] } -> optionThe 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.The second argument is the name of the option, used in the description \"The <name> package to use.\".You can also pass an example value, either a literal string or a package's attribute path.You can omit the default path if the name of the option is also attribute path in nixpkgs.",
"description": [
"Creates an Option attribute set for an option that specifies the\npackage a module should use for some purpose."
],
"example": "\nmkPackageOption pkgs \"hello\" { }\n=> { _type = \"option\"; default = «derivation /nix/store/3r2vg51hlxj3cx5vscp0vkv60bqxkaq0-hello-2.10.drv»; defaultText = { ... }; description = \"The hello package to use.\"; type = { ... }; }\n\n\nmkPackageOption pkgs \"GHC\" {\ndefault = [ \"ghc\" ];\nexample = \"pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])\";\n}\n=> { _type = \"option\"; default = «derivation /nix/store/jxx55cxsjrf8kyh3fp2ya17q99w7541r-ghc-8.10.7.drv»; defaultText = { ... }; description = \"The GHC package to use.\"; example = { ... }; type = { ... }; }\n"
},
{
"category": "./lib/options.nix",
"name": "mkSinkUndeclaredOptions",
"fn_type": null,
"description": [
"This option accepts anything, but it does not produce any result.",
"This is useful for sharing a module across different module sets\nwithout having to implement similar features as long as the\nvalues of the options are not accessed."
],
"example": null
},
{
"category": "./lib/options.nix",
"name": "mergeEqualOption",
"fn_type": null,
"description": [
"\"Merge\" option definitions by checking that they all have the same value."
],
"example": null
},
{
"category": "./lib/options.nix",
"name": "getValues",
"fn_type": "getValues :: [ { value :: a } ] -> [a]",
"description": ["Extracts values of all \"value\" keys of the given list."],
"example": "\ngetValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]\ngetValues [ ] // => [ ]\n"
},
{
"category": "./lib/options.nix",
"name": "getFiles",
"fn_type": "getFiles :: [ { file :: a } ] -> [a]",
"description": ["Extracts values of all \"file\" keys of the given list"],
"example": "\ngetFiles [ { file = \"file1\"; } { file = \"file2\"; } ] // => [ \"file1\" \"file2\" ]\ngetFiles [ ] // => [ ]\n"
},
{
"category": "./lib/options.nix",
"name": "scrubOptionValue",
"fn_type": null,
"description": [
"This function recursively removes all derivation attributes from\n`x` except for the `name` attribute.",
"This is to make the generation of `options.xml` much more\nefficient: the XML representation of derivations is very large\n(on the order of megabytes) and is not actually used by the\nmanual generator."
],
"example": null
},
{
"category": "./lib/options.nix",
"name": "literalExpression",
"fn_type": null,
"description": [
"For use in the `defaultText` and `example` option attributes. Causes the\ngiven string to be rendered verbatim in the documentation as Nix code. This\nis necessary for complex values, e.g. functions, or values that depend on\nother values or packages."
],
"example": null
},
{
"category": "./lib/options.nix",
"name": "literalDocBook",
"fn_type": null,
"description": [
"For use in the `defaultText` and `example` option attributes. Causes the\ngiven DocBook text to be inserted verbatim in the documentation, for when\na `literalExpression` would be too hard to read."
],
"example": null
},
{
"category": "./lib/options.nix",
"name": "mdDoc",
"fn_type": null,
"description": [
"Transition marker for documentation that's already migrated to markdown\nsyntax."
],
"example": null
},
{
"category": "./lib/options.nix",
"name": "literalMD",
"fn_type": null,
"description": [
"For use in the `defaultText` and `example` option attributes. Causes the\ngiven MD text to be inserted verbatim in the documentation, for when\na `literalExpression` would be too hard to read."
],
"example": null
},
{
"category": "./lib/options.nix",
"name": "showOption",
"fn_type": null,
"description": [
"Convert an option, described as a list of the option parts in to a\nsafe, human readable version."
],
"example": "\n(showOption [\"foo\" \"bar\" \"baz\"]) == \"foo.bar.baz\"\n(showOption [\"foo\" \"bar.baz\" \"tux\"]) == \"foo.bar.baz.tux\"\n\nPlaceholders will not be quoted as they are not actual values:\n(showOption [\"foo\" \"*\" \"bar\"]) == \"foo.*.bar\"\n(showOption [\"foo\" \"<name>\" \"bar\"]) == \"foo.<name>.bar\"\n\nUnlike attributes, options can also start with numbers:\n(showOption [\"windowManager\" \"2bwm\" \"enable\"]) == \"windowManager.2bwm.enable\"\n"
},
{
"category": "./lib/attrsets.nix",
"name": "attrByPath",
"fn_type": null,
"description": ["Return an attribute from nested attribute sets."],
"example": "\nx = { a = { b = 3; }; }\nattrByPath [\"a\" \"b\"] 6 x\n=> 3\nattrByPath [\"z\" \"z\"] 6 x\n=> 6\n"
},
{
"category": "./lib/attrsets.nix",
"name": "hasAttrByPath",
"fn_type": null,
"description": ["Return if an attribute from nested attribute set exists."],
"example": "\nx = { a = { b = 3; }; }\nhasAttrByPath [\"a\" \"b\"] x\n=> true\nhasAttrByPath [\"z\" \"z\"] x\n=> false\n"
},
{
"category": "./lib/attrsets.nix",
"name": "setAttrByPath",
"fn_type": null,
"description": [
"Return nested attribute set in which an attribute is set."
],
"example": "\nsetAttrByPath [\"a\" \"b\"] 3\n=> { a = { b = 3; }; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "getAttrFromPath",
"fn_type": null,
"description": [
"Like `attrByPath' without a default value. If it doesn't find the\npath it will throw."
],
"example": "\nx = { a = { b = 3; }; }\ngetAttrFromPath [\"a\" \"b\"] x\n=> 3\ngetAttrFromPath [\"z\" \"z\"] x\n=> error: cannot find attribute `z.z'\n"
},
{
"category": "./lib/attrsets.nix",
"name": "updateManyAttrsByPath",
"fn_type": null,
"description": [
"Update or set specific paths of an attribute set.",
"Takes a list of updates to apply and an attribute set to apply them to,\nand returns the attribute set with the updates applied. Updates are\nrepresented as { path = ...; update = ...; } values, where `path` is a\nlist of strings representing the attribute path that should be updated,\nand `update` is a function that takes the old value at that attribute path\nas an argument and returns the new\nvalue it should be.",
"Properties:\n- Updates to deeper attribute paths are applied before updates to more\nshallow attribute paths\n- Multiple updates to the same attribute path are applied in the order\nthey appear in the update list\n- If any but the last `path` element leads into a value that is not an\nattribute set, an error is thrown\n- If there is an update for an attribute path that doesn't exist,\naccessing the argument in the update function causes an error, but\nintermediate attribute sets are implicitly created as needed"
],
"example": "\nupdateManyAttrsByPath [\n{\npath = [ \"a\" \"b\" ];\nupdate = old: { d = old.c; };\n}\n{\npath = [ \"a\" \"b\" \"c\" ];\nupdate = old: old + 1;\n}\n{\npath = [ \"x\" \"y\" ];\nupdate = old: \"xy\";\n}\n] { a.b.c = 0; }\n=> { a = { b = { d = 1; }; }; x = { y = \"xy\"; }; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "attrVals",
"fn_type": null,
"description": ["Return the specified attributes from a set."],
"example": "\nattrVals [\"a\" \"b\" \"c\"] as\n=> [as.a as.b as.c]\n"
},
{
"category": "./lib/attrsets.nix",
"name": "attrValues",
"fn_type": null,
"description": [
"Return the values of all attributes in the given set, sorted by\nattribute name."
],
"example": "\nattrValues {c = 3; a = 1; b = 2;}\n=> [1 2 3]\n"
},
{
"category": "./lib/attrsets.nix",
"name": "getAttrs",
"fn_type": null,
"description": [
"Given a set of attribute names, return the set of the corresponding\nattributes from the given set."
],
"example": "\ngetAttrs [ \"a\" \"b\" ] { a = 1; b = 2; c = 3; }\n=> { a = 1; b = 2; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "catAttrs",
"fn_type": null,
"description": [
"Collect each attribute named `attr' from a list of attribute\nsets. Sets that don't contain the named attribute are ignored."
],
"example": "\ncatAttrs \"a\" [{a = 1;} {b = 0;} {a = 2;}]\n=> [1 2]\n"
},
{
"category": "./lib/attrsets.nix",
"name": "filterAttrs",
"fn_type": null,
"description": [
"Filter an attribute set by removing all attributes for which the\ngiven predicate return false."
],
"example": "\nfilterAttrs (n: v: n == \"foo\") { foo = 1; bar = 2; }\n=> { foo = 1; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "filterAttrsRecursive",
"fn_type": null,
"description": [
"Filter an attribute set recursively by removing all attributes for\nwhich the given predicate return false."
],
"example": "\nfilterAttrsRecursive (n: v: v != null) { foo = { bar = null; }; }\n=> { foo = {}; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "foldAttrs",
"fn_type": null,
"description": ["Apply fold functions to values grouped by key."],
"example": "\nfoldAttrs (item: acc: [item] ++ acc) [] [{ a = 2; } { a = 3; }]\n=> { a = [ 2 3 ]; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "collect",
"fn_type": "collect ::(AttrSet -> Bool) -> AttrSet -> [x]",
"description": [
"Recursively collect sets that verify a given predicate named `pred'\nfrom the set `attrs'. The recursion is stopped when the predicate is\nverified."
],
"example": "\ncollect isList { a = { b = [\"b\"]; }; c = [1]; }\n=> [[\"b\"] [1]]\n\ncollect (x: x ? outPath)\n{ a = { outPath = \"a/\"; }; b = { outPath = \"b/\"; }; }\n=> [{ outPath = \"a/\"; } { outPath = \"b/\"; }]\n"
},
{
"category": "./lib/attrsets.nix",
"name": "cartesianProductOfSets",
"fn_type": null,
"description": [
"Return the cartesian product of attribute set value combinations."
],
"example": "\ncartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; }\n=> [\n{ a = 1; b = 10; }\n{ a = 1; b = 20; }\n{ a = 2; b = 10; }\n{ a = 2; b = 20; }\n]\n"
},
{
"category": "./lib/attrsets.nix",
"name": "nameValuePair",
"fn_type": null,
"description": [
"Utility function that creates a {name, value} pair as expected by\nbuiltins.listToAttrs."
],
"example": "\nnameValuePair \"some\" 6\n=> { name = \"some\"; value = 6; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "mapAttrs",
"fn_type": null,
"description": [
"Apply a function to each element in an attribute set. The\nfunction takes two arguments --- the attribute name and its value\n--- and returns the new value for the attribute. The result is a\nnew attribute set."
],
"example": "\nmapAttrs (name: value: name + \"-\" + value)\n{ x = \"foo\"; y = \"bar\"; }\n=> { x = \"x-foo\"; y = \"y-bar\"; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "mapAttrs'",
"fn_type": null,
"description": [
"Like `mapAttrs', but allows the name of each attribute to be\nchanged in addition to the value. The applied function should\nreturn both the new name and value as a `nameValuePair'."
],
"example": "\nmapAttrs' (name: value: nameValuePair (\"foo_\" + name) (\"bar-\" + value))\n{ x = \"a\"; y = \"b\"; }\n=> { foo_x = \"bar-a\"; foo_y = \"bar-b\"; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "mapAttrsToList",
"fn_type": "mapAttrsToList ::(String -> a -> b) -> AttrSet -> [b]",
"description": [
"Call a function for each attribute in the given set and return\nthe result in a list."
],
"example": "\nmapAttrsToList (name: value: name + value)\n{ x = \"a\"; y = \"b\"; }\n=> [ \"xa\" \"yb\" ]\n"
},
{
"category": "./lib/attrsets.nix",
"name": "mapAttrsRecursive",
"fn_type": "mapAttrsRecursive ::([String] -> a -> b) -> AttrSet -> AttrSet",
"description": [
"Like `mapAttrs', except that it recursively applies itself to\nattribute sets. Also, the first argument of the argument\nfunction is a *list* of the names of the containing attributes."
],
"example": "\nmapAttrsRecursive (path: value: concatStringsSep \"-\" (path ++ [value]))\n{ n = { a = \"A\"; m = { b = \"B\"; c = \"C\"; }; }; d = \"D\"; }\n=> { n = { a = \"n-a-A\"; m = { b = \"n-m-b-B\"; c = \"n-m-c-C\"; }; }; d = \"d-D\"; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "mapAttrsRecursiveCond",
"fn_type": "mapAttrsRecursiveCond ::(AttrSet -> Bool) -> ([String] -> a -> b) -> AttrSet -> AttrSet",
"description": [
"Like `mapAttrsRecursive', but it takes an additional predicate\nfunction that tells it whether to recurse into an attribute\nset. If it returns false, `mapAttrsRecursiveCond' does not\nrecurse, but does apply the map function. If it returns true, it\ndoes recurse, and does not apply the map function."
],
"example": "\n# To prevent recursing into derivations (which are attribute\n# sets with the attribute \"type\" equal to \"derivation\"):\nmapAttrsRecursiveCond\n(as: !(as ? \"type\" && as.type == \"derivation\"))\n(x: ... do something ...)\nattrs\n"
},
{
"category": "./lib/attrsets.nix",
"name": "genAttrs",
"fn_type": null,
"description": [
"Generate an attribute set by mapping a function over a list of\nattribute names."
],
"example": "\ngenAttrs [ \"foo\" \"bar\" ] (name: \"x_\" + name)\n=> { foo = \"x_foo\"; bar = \"x_bar\"; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "isDerivation",
"fn_type": null,
"description": [
"Check whether the argument is a derivation. Any set with\n{ type = \"derivation\"; } counts as a derivation."
],
"example": "\nnixpkgs = import <nixpkgs> {}\nisDerivation nixpkgs.ruby\n=> true\nisDerivation \"foobar\"\n=> false\n"
},
{
"category": "./lib/attrsets.nix",
"name": "toDerivation",
"fn_type": null,
"description": ["Converts a store path to a fake derivation."],
"example": null
},
{
"category": "./lib/attrsets.nix",
"name": "optionalAttrs",
"fn_type": null,
"description": [
"If `cond' is true, return the attribute set `as',\notherwise an empty attribute set."
],
"example": "\noptionalAttrs (true) { my = \"set\"; }\n=> { my = \"set\"; }\noptionalAttrs (false) { my = \"set\"; }\n=> { }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "zipAttrsWithNames",
"fn_type": null,
"description": [
"Merge sets of attributes and use the function f to merge attributes\nvalues."
],
"example": "\nzipAttrsWithNames [\"a\"] (name: vs: vs) [{a = \"x\";} {a = \"y\"; b = \"z\";}]\n=> { a = [\"x\" \"y\"]; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "zipAttrsWith",
"fn_type": null,
"description": [
"Implementation note: Common names appear multiple times in the list of\nnames, hopefully this does not affect the system because the maximal\nlaziness avoid computing twice the same expression and listToAttrs does\nnot care about duplicated attribute names."
],
"example": "\nzipAttrsWith (name: values: values) [{a = \"x\";} {a = \"y\"; b = \"z\";}]\n=> { a = [\"x\" \"y\"]; b = [\"z\"] }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "zipAttrs",
"fn_type": null,
"description": [
"Like `zipAttrsWith' with `(name: values: values)' as the function."
],
"example": "\nzipAttrs [{a = \"x\";} {a = \"y\"; b = \"z\";}]\n=> { a = [\"x\" \"y\"]; b = [\"z\"] }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "recursiveUpdateUntil",
"fn_type": null,
"description": [
"Does the same as the update operator '//' except that attributes are\nmerged until the given predicate is verified. The predicate should\naccept 3 arguments which are the path to reach the attribute, a part of\nthe first attribute set and a part of the second attribute set. When\nthe predicate is verified, the value of the first attribute set is\nreplaced by the value of the second attribute set."
],
"example": "\nrecursiveUpdateUntil (path: l: r: path == [\"foo\"]) {\n# first attribute set\nfoo.bar = 1;\nfoo.baz = 2;\nbar = 3;\n} {\n#second attribute set\nfoo.bar = 1;\nfoo.quz = 2;\nbaz = 4;\n}\n\nreturns: {\nfoo.bar = 1; # 'foo.*' from the second set\nfoo.quz = 2; #\nbar = 3; # 'bar' from the first set\nbaz = 4; # 'baz' from the second set\n}\n"
},
{
"category": "./lib/attrsets.nix",
"name": "recursiveUpdate",
"fn_type": null,
"description": [
"A recursive variant of the update operator ‘//’. The recursion\nstops when one of the attribute values is not an attribute set,\nin which case the right hand side value takes precedence over the\nleft hand side value."
],
"example": "\nrecursiveUpdate {\nboot.loader.grub.enable = true;\nboot.loader.grub.device = \"/dev/hda\";\n} {\nboot.loader.grub.device = \"\";\n}\n\nreturns: {\nboot.loader.grub.enable = true;\nboot.loader.grub.device = \"\";\n}\n"
},
{
"category": "./lib/attrsets.nix",
"name": "matchAttrs",
"fn_type": null,
"description": [
"Returns true if the pattern is contained in the set. False otherwise."
],
"example": "\nmatchAttrs { cpu = {}; } { cpu = { bits = 64; }; }\n=> true\n"
},
{
"category": "./lib/attrsets.nix",
"name": "overrideExisting",
"fn_type": null,
"description": [
"Override only the attributes that are already present in the old set\nuseful for deep-overriding."
],
"example": "\noverrideExisting {} { a = 1; }\n=> {}\noverrideExisting { b = 2; } { a = 1; }\n=> { b = 2; }\noverrideExisting { a = 3; b = 2; } { a = 1; }\n=> { a = 1; b = 2; }\n"
},
{
"category": "./lib/attrsets.nix",
"name": "showAttrPath",
"fn_type": null,
"description": [
"Turns a list of strings into a human-readable description of those\nstrings represented as an attribute path. The result of this function is\nnot intended to be machine-readable."
],
"example": "\nshowAttrPath [ \"foo\" \"10\" \"bar\" ]\n=> \"foo.\\\"10\\\".bar\"\nshowAttrPath []\n=> \"<root attribute path>\"\n"
},
{
"category": "./lib/attrsets.nix",
"name": "getOutput",
"fn_type": null,
"description": [
"Get a package output.\nIf no output is found, fallback to `.out` and then to the default."
],
"example": "\ngetOutput \"dev\" pkgs.openssl\n=> \"/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev\"\n"
},
{
"category": "./lib/attrsets.nix",
"name": "chooseDevOutputs",
"fn_type": null,
"description": ["Pick the outputs of packages to place in buildInputs"],
"example": null
},
{
"category": "./lib/attrsets.nix",
"name": "recurseIntoAttrs",
"fn_type": null,
"description": [
"Make various Nix tools consider the contents of the resulting\nattribute set when looking for what to build, find, etc.",
"This function only affects a single attribute set; it does not\napply itself recursively for nested attribute sets."
],
"example": null
},
{
"category": "./lib/attrsets.nix",
"name": "dontRecurseIntoAttrs",
"fn_type": null,
"description": ["Undo the effect of recurseIntoAttrs."],
"example": null
},
{
"category": "./lib/attrsets.nix",
"name": "unionOfDisjoint",
"fn_type": null,
"description": [
"`unionOfDisjoint x y` is equal to `x // y // z` where the\nattrnames in `z` are the intersection of the attrnames in `x` and\n`y`, and all values `assert` with an error message. This\noperator is commutative, unlike (//)."
],
"example": null
},
{
"category": "./lib/attrsets.nix",
"name": "zipWithNames",
"fn_type": null,
"description": ["** deprecated stuff **"],
"example": null
},
{
"category": "./lib/deprecated.nix",
"name": "imap",
"fn_type": null,
"description": [
"deprecated:",
"For historical reasons, imap has an index starting at 1.",
"But for consistency with the rest of the library we want an index\nstarting at zero."
],
"example": null
},
{
"category": "./lib/filesystem.nix",
"name": "haskellPathsInDir",
"fn_type": "Path -> Map String Path",
"description": [
"A map of all haskell packages defined in the given path,\nidentified by having a cabal file with the same name as the\ndirectory itself."
],
"example": null
},
{
"category": "./lib/filesystem.nix",
"name": "locateDominatingFile",
"fn_type": "RegExp -> Path -> Nullable { path : Path; matches : [ MatchResults ]; }",
"description": [
"Find the first directory containing a file matching 'pattern'\nupward from a given 'file'.\nReturns 'null' if no directories contain a file matching 'pattern'."
],
"example": null
},
{
"category": "./lib/filesystem.nix",
"name": "listFilesRecursive",
"fn_type": "Path -> [ Path ]",
"description": [
"Given a directory, return a flattened list of all files within it recursively."
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "mkValueStringDefault",
"fn_type": null,
"description": [
"Convert a value to a sensible default string representation.\n* The builtin `toString` function has some strange defaults,\n* suitable for bash scripts but not much else."
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "mkKeyValueDefault",
"fn_type": null,
"description": [
"Generate a line of key k and value v, separated by\n* character sep. If sep appears in k, it is escaped.\n* Helper for synaxes with different separators.\n*\n* mkValueString specifies how values should be formatted.\n*\n* mkKeyValueDefault {} \":\" \"f:oo\" \"bar\"\n* > \"f\\:oo:bar\""
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "toKeyValue",
"fn_type": null,
"description": [
"Generate a key-value-style config file from an attrset.\n*\n* mkKeyValue is the same as in toINI."
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "toINI",
"fn_type": null,
"description": [
"Generate an INI-style config file from an\n* attrset of sections to an attrset of key-value pairs.\n*\n* generators.toINI {} {\n* foo = { hi = \"${pkgs.hello}\"; ciao = \"bar\"; };\n* baz = { \"also, integers\" = 42; };\n* }\n*\n*> [baz]\n*> also, integers=42\n*>\n*> [foo]\n*> ciao=bar\n*> hi=/nix/store/y93qql1p5ggfnaqjjqhxcw0vqw95rlz0-hello-2.10\n*\n* The mk* configuration attributes can generically change\n* the way sections and key-value strings are generated.\n*\n* For more examples see the test cases in ./tests/misc.nix."
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "toINIWithGlobalSection",
"fn_type": null,
"description": [
"Generate an INI-style config file from an attrset\n* specifying the global section (no header), and an\n* attrset of sections to an attrset of key-value pairs.\n*\n* generators.toINIWithGlobalSection {} {\n* globalSection = {\n* someGlobalKey = \"hi\";\n* };\n* sections = {\n* foo = { hi = \"${pkgs.hello}\"; ciao = \"bar\"; };\n* baz = { \"also, integers\" = 42; };\n* }\n*\n*> someGlobalKey=hi\n*>\n*> [baz]\n*> also, integers=42\n*>\n*> [foo]\n*> ciao=bar\n*> hi=/nix/store/y93qql1p5ggfnaqjjqhxcw0vqw95rlz0-hello-2.10\n*\n* The mk* configuration attributes can generically change\n* the way sections and key-value strings are generated.\n*\n* For more examples see the test cases in ./tests/misc.nix.\n*\n* If you don’t need a global section, you can also use\n* `generators.toINI` directly, which only takes\n* the part in `sections`."
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "toGitINI",
"fn_type": null,
"description": [
"Generate a git-config file from an attrset.\n*\n* It has two major differences from the regular INI format:\n*\n* 1. values are indented with tabs\n* 2. sections can have sub-sections\n*\n* generators.toGitINI {\n* url.\"ssh://git@github.com/\".insteadOf = \"https://github.com\";\n* user.name = \"edolstra\";\n* }\n*\n*> [url \"ssh://git@github.com/\"]\n*> insteadOf = https://github.com/\n*>\n*> [user]\n*> name = edolstra"
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "toJSON",
"fn_type": null,
"description": [
"Generates JSON from an arbitrary (non-function) value.\n* For more information see the documentation of the builtin."
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "toYAML",
"fn_type": null,
"description": [
"YAML has been a strict superset of JSON since 1.2, so we\n* use toJSON. Before it only had a few differences referring\n* to implicit typing rules, so it should work with older\n* parsers as well."
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "toPretty",
"fn_type": null,
"description": [
"Pretty print a value, akin to `builtins.trace`.\n* Should probably be a builtin as well."
],
"example": null
},
{
"category": "./lib/generators.nix",
"name": "toDhall",
"fn_type": null,
"description": [
"Translate a simple Nix expression to Dhall notation.\n* Note that integers are translated to Integer and never\n* the Natural type."
],
"example": null
},
{
"category": "./lib/strings.nix",
"name": "concatStrings",
"fn_type": "concatStrings :: [string] -> string",
"description": ["Concatenate a list of strings."],
"example": "\nconcatStrings [\"foo\" \"bar\"]\n=> \"foobar\"\n"
},
{
"category": "./lib/strings.nix",
"name": "concatMapStrings",
"fn_type": "concatMapStrings :: (a -> string) -> [a] -> string",
"description": [
"Map a function over a list and concatenate the resulting strings."
],
"example": "\nconcatMapStrings (x: \"a\" + x) [\"foo\" \"bar\"]\n=> \"afooabar\"\n"
},
{
"category": "./lib/strings.nix",
"name": "concatImapStrings",
"fn_type": "concatImapStrings :: (int -> a -> string) -> [a] -> string",
"description": [
"Like `concatMapStrings` except that the f functions also gets the\nposition as a parameter."
],
"example": "\nconcatImapStrings (pos: x: \"${toString pos}-${x}\") [\"foo\" \"bar\"]\n=> \"1-foo2-bar\"\n"
},
{
"category": "./lib/strings.nix",
"name": "intersperse",
"fn_type": "intersperse :: a -> [a] -> [a]",
"description": ["Place an element between each element of a list"],
"example": "\nintersperse \"/\" [\"usr\" \"local\" \"bin\"]\n=> [\"usr\" \"/\" \"local\" \"/\" \"bin\"].\n"
},
{
"category": "./lib/strings.nix",
"name": "concatStringsSep",
"fn_type": "concatStringsSep :: string -> [string] -> string",
"description": [
"Concatenate a list of strings with a separator between each element"
],
"example": "\nconcatStringsSep \"/\" [\"usr\" \"local\" \"bin\"]\n=> \"usr/local/bin\"\n"
},
{
"category": "./lib/strings.nix",
"name": "concatMapStringsSep",
"fn_type": "concatMapStringsSep :: string -> (a -> string) -> [a] -> string",
"description": [
"Maps a function over a list of strings and then concatenates the\nresult with the specified separator interspersed between\nelements."
],
"example": "\nconcatMapStringsSep \"-\" (x: toUpper x) [\"foo\" \"bar\" \"baz\"]\n=> \"FOO-BAR-BAZ\"\n"
},
{
"category": "./lib/strings.nix",
"name": "concatImapStringsSep",
"fn_type": "concatIMapStringsSep :: string -> (int -> a -> string) -> [a] -> string",
"description": [
"Same as `concatMapStringsSep`, but the mapping function\nadditionally receives the position of its argument."
],
"example": "\nconcatImapStringsSep \"-\" (pos: x: toString (x / pos)) [ 6 6 6 ]\n=> \"6-3-2\"\n"
},
{
"category": "./lib/strings.nix",
"name": "makeSearchPath",
"fn_type": "makeSearchPath :: string -> [string] -> string",
"description": [
"Construct a Unix-style, colon-separated search path consisting of\nthe given `subDir` appended to each of the given paths."
],
"example": "\nmakeSearchPath \"bin\" [\"/root\" \"/usr\" \"/usr/local\"]\n=> \"/root/bin:/usr/bin:/usr/local/bin\"\nmakeSearchPath \"bin\" [\"\"]\n=> \"/bin\"\n"
},
{
"category": "./lib/strings.nix",
"name": "makeSearchPathOutput",
"fn_type": "string -> string -> [package] -> string",
"description": [
"Construct a Unix-style search path by appending the given\n`subDir` to the specified `output` of each of the packages. If no\noutput by the given name is found, fallback to `.out` and then to\nthe default."
],
"example": "\nmakeSearchPathOutput \"dev\" \"bin\" [ pkgs.openssl pkgs.zlib ]\n=> \"/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev/bin:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/bin\"\n"
},
{
"category": "./lib/strings.nix",
"name": "makeLibraryPath",
"fn_type": null,
"description": [
"Construct a library search path (such as RPATH) containing the\nlibraries for a set of packages"
],
"example": "\nmakeLibraryPath [ \"/usr\" \"/usr/local\" ]\n=> \"/usr/lib:/usr/local/lib\"\npkgs = import <nixpkgs> { }\nmakeLibraryPath [ pkgs.openssl pkgs.zlib ]\n=> \"/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r/lib:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/lib\"\n"
},
{
"category": "./lib/strings.nix",
"name": "makeBinPath",
"fn_type": null,
"description": [
"Construct a binary search path (such as $PATH) containing the\nbinaries for a set of packages."
],
"example": "\nmakeBinPath [\"/root\" \"/usr\" \"/usr/local\"]\n=> \"/root/bin:/usr/bin:/usr/local/bin\"\n"
},
{
"category": "./lib/strings.nix",
"name": "normalizePath",
"fn_type": "normalizePath :: string -> string",
"description": ["Normalize path, removing extranous /s"],
"example": "\nnormalizePath \"/a//b///c/\"\n=> \"/a/b/c/\"\n"
},
{
"category": "./lib/strings.nix",
"name": "optionalString",
"fn_type": "optionalString :: bool -> string -> string",
"description": [
"Depending on the boolean `cond', return either the given string\nor the empty string. Useful to concatenate against a bigger string."
],
"example": "\noptionalString true \"some-string\"\n=> \"some-string\"\noptionalString false \"some-string\"\n=> \"\"\n"
},
{
"category": "./lib/strings.nix",
"name": "hasPrefix",
"fn_type": "hasPrefix :: string -> string -> bool",
"description": ["Determine whether a string has given prefix."],
"example": "\nhasPrefix \"foo\" \"foobar\"\n=> true\nhasPrefix \"foo\" \"barfoo\"\n=> false\n"
},
{
"category": "./lib/strings.nix",
"name": "hasSuffix",
"fn_type": "hasSuffix :: string -> string -> bool",
"description": ["Determine whether a string has given suffix."],
"example": "\nhasSuffix \"foo\" \"foobar\"\n=> false\nhasSuffix \"foo\" \"barfoo\"\n=> true\n"
},
{
"category": "./lib/strings.nix",
"name": "hasInfix",
"fn_type": "hasInfix :: string -> string -> bool",
"description": ["Determine whether a string contains the given infix"],
"example": "\nhasInfix \"bc\" \"abcd\"\n=> true\nhasInfix \"ab\" \"abcd\"\n=> true\nhasInfix \"cd\" \"abcd\"\n=> true\nhasInfix \"foo\" \"abcd\"\n=> false\n"
},
{
"category": "./lib/strings.nix",
"name": "stringToCharacters",
"fn_type": "stringToCharacters :: string -> [string]",
"description": [
"Convert a string to a list of characters (i.e. singleton strings).\nThis allows you to, e.g., map a function over each character. However,\nnote that this will likely be horribly inefficient; Nix is not a\ngeneral purpose programming language. Complex string manipulations\nshould, if appropriate, be done in a derivation.\nAlso note that Nix treats strings as a list of bytes and thus doesn't\nhandle unicode."
],
"example": "\nstringToCharacters \"\"\n=> [ ]\nstringToCharacters \"abc\"\n=> [ \"a\" \"b\" \"c\" ]\nstringToCharacters \"💩\"\n=> [ \"<22>\" \"<22>\" \"<22>\" \"<22>\" ]\n"
},
{
"category": "./lib/strings.nix",
"name": "stringAsChars",
"fn_type": "stringAsChars :: (string -> string) -> string -> string",
"description": [
"Manipulate a string character by character and replace them by\nstrings before concatenating the results."
],
"example": "\nstringAsChars (x: if x == \"a\" then \"i\" else x) \"nax\"\n=> \"nix\"\n"
},
{
"category": "./lib/strings.nix",
"name": "charToInt",
"fn_type": "charToInt :: string -> int",
"description": ["Convert char to ascii value, must be in printable range"],
"example": "\ncharToInt \"A\"\n=> 65\ncharToInt \"(\"\n=> 40\n"
},
{
"category": "./lib/strings.nix",
"name": "escape",
"fn_type": "escape :: [string] -> string -> string",
"description": [
"Escape occurrence of the elements of `list` in `string` by\nprefixing it with a backslash."
],
"example": "\nescape [\"(\" \")\"] \"(foo)\"\n=> \"\\\\(foo\\\\)\"\n"
},
{
"category": "./lib/strings.nix",
"name": "escapeC",
"fn_type": "escapeC = [string] -> string -> string",
"description": [
"Escape occurence of the element of `list` in `string` by\nconverting to its ASCII value and prefixing it with \\\\x.\nOnly works for printable ascii characters."
],
"example": "\nescapeC [\" \"] \"foo bar\"\n=> \"foo\\\\x20bar\"\n"
},
{
"category": "./lib/strings.nix",
"name": "escapeShellArg",
"fn_type": "escapeShellArg :: string -> string",
"description": ["Quote string to be used safely within the Bourne shell."],
"example": "\nescapeShellArg \"esc'ape\\nme\"\n=> \"'esc'\\\\''ape\\nme'\"\n"
},
{
"category": "./lib/strings.nix",
"name": "escapeShellArgs",
"fn_type": "escapeShellArgs :: [string] -> string",
"description": [
"Quote all arguments to be safely passed to the Bourne shell."
],
"example": "\nescapeShellArgs [\"one\" \"two three\" \"four'five\"]\n=> \"'one' 'two three' 'four'\\\\''five'\"\n"
},
{
"category": "./lib/strings.nix",
"name": "isValidPosixName",
"fn_type": "string -> bool",
"description": [
"Test whether the given name is a valid POSIX shell variable name."
],
"example": "\nisValidPosixName \"foo_bar000\"\n=> true\nisValidPosixName \"0-bad.jpg\"\n=> false\n"
},
{
"category": "./lib/strings.nix",
"name": "toShellVar",
"fn_type": "string -> (string | listOf string | attrsOf string) -> string",
"description": [
"Translate a Nix value into a shell variable declaration, with proper escaping.",
"The value can be a string (mapped to a regular variable), a list of strings\n(mapped to a Bash-style array) or an attribute set of strings (mapped to a\nBash-style associative array). Note that \"string\" includes string-coercible\nvalues like paths or derivations.",
"Strings are translated into POSIX sh-compatible code; lists and attribute sets\nassume a shell that understands Bash syntax (e.g. Bash or ZSH)."
],
"example": "\n''\n${toShellVar \"foo\" \"some string\"}\n[[ \"$foo\" == \"some string\" ]]\n''\n"
},
{
"category": "./lib/strings.nix",
"name": "toShellVars",
"fn_type": "attrsOf (string | listOf string | attrsOf string) -> string",
"description": [
"Translate an attribute set into corresponding shell variable declarations\nusing `toShellVar`."
],
"example": "\nlet\nfoo = \"value\";\nbar = foo;\nin ''\n${toShellVars { inherit foo bar; }}\n[[ \"$foo\" == \"$bar\" ]]\n''\n"
},
{
"category": "./lib/strings.nix",
"name": "escapeNixString",
"fn_type": "string -> string",
"description": [
"Turn a string into a Nix expression representing that string"
],
"example": "\nescapeNixString \"hello\\${}\\n\"\n=> \"\\\"hello\\\\\\${}\\\\n\\\"\"\n"
},
{
"category": "./lib/strings.nix",
"name": "escapeRegex",
"fn_type": "string -> string",
"description": ["Turn a string into an exact regular expression"],
"example": "\nescapeRegex \"[^a-z]*\"\n=> \"\\\\[\\\\^a-z]\\\\*\"\n"
},
{
"category": "./lib/strings.nix",
"name": "escapeNixIdentifier",
"fn_type": "string -> string",
"description": [
"Quotes a string if it can't be used as an identifier directly."
],
"example": "\nescapeNixIdentifier \"hello\"\n=> \"hello\"\nescapeNixIdentifier \"0abc\"\n=> \"\\\"0abc\\\"\"\n"
},
{
"category": "./lib/strings.nix",
"name": "escapeXML",
"fn_type": "string -> string",
"description": [
"Escapes a string such that it is safe to include verbatim in an XML\ndocument."
],
"example": "\nescapeXML ''\"test\" 'test' < & >''\n=> \"&quot;test&quot; &apos;test&apos; &lt; &amp; &gt;\"\n"
},
{
"category": "./lib/strings.nix",
"name": "toLower",
"fn_type": "toLower :: string -> string",
"description": ["Converts an ASCII string to lower-case."],
"example": "\ntoLower \"HOME\"\n=> \"home\"\n"
},
{
"category": "./lib/strings.nix",
"name": "toUpper",
"fn_type": "toUpper :: string -> string",
"description": ["Converts an ASCII string to upper-case."],
"example": "\ntoUpper \"home\"\n=> \"HOME\"\n"
},
{
"category": "./lib/strings.nix",
"name": "addContextFrom",
"fn_type": null,
"description": [
"Appends string context from another string. This is an implementation\ndetail of Nix.",
"Strings in Nix carry an invisible `context` which is a list of strings\nrepresenting store paths. If the string is later used in a derivation\nattribute, the derivation will properly populate the inputDrvs and\ninputSrcs."
],
"example": "\npkgs = import <nixpkgs> { };\naddContextFrom pkgs.coreutils \"bar\"\n=> \"bar\"\n"
},
{
"category": "./lib/strings.nix",
"name": "splitString",
"fn_type": null,
"description": [
"Cut a string with a separator and produces a list of strings which\nwere separated by this separator."
],
"example": "\nsplitString \".\" \"foo.bar.baz\"\n=> [ \"foo\" \"bar\" \"baz\" ]\nsplitString \"/\" \"/usr/local/bin\"\n=> [ \"\" \"usr\" \"local\" \"bin\" ]\n"
},
{
"category": "./lib/strings.nix",
"name": "removePrefix",
"fn_type": "string -> string -> string",
"description": [
"Return a string without the specified prefix, if the prefix matches."
],
"example": "\nremovePrefix \"foo.\" \"foo.bar.baz\"\n=> \"bar.baz\"\nremovePrefix \"xxx\" \"foo.bar.baz\"\n=> \"foo.bar.baz\"\n"
},
{
"category": "./lib/strings.nix",
"name": "removeSuffix",
"fn_type": "string -> string -> string",
"description": [
"Return a string without the specified suffix, if the suffix matches."
],
"example": "\nremoveSuffix \"front\" \"homefront\"\n=> \"home\"\nremoveSuffix \"xxx\" \"homefront\"\n=> \"homefront\"\n"
},
{
"category": "./lib/strings.nix",
"name": "versionOlder",
"fn_type": null,
"description": [
"Return true if string v1 denotes a version older than v2."
],
"example": "\nversionOlder \"1.1\" \"1.2\"\n=> true\nversionOlder \"1.1\" \"1.1\"\n=> false\n"
},
{
"category": "./lib/strings.nix",
"name": "versionAtLeast",
"fn_type": null,
"description": [
"Return true if string v1 denotes a version equal to or newer than v2."
],
"example": "\nversionAtLeast \"1.1\" \"1.0\"\n=> true\nversionAtLeast \"1.1\" \"1.1\"\n=> true\nversionAtLeast \"1.1\" \"1.2\"\n=> false\n"
},
{
"category": "./lib/strings.nix",
"name": "getName",
"fn_type": null,
"description": [
"This function takes an argument that's either a derivation or a\nderivation's \"name\" attribute and extracts the name part from that\nargument."
],
"example": "\ngetName \"youtube-dl-2016.01.01\"\n=> \"youtube-dl\"\ngetName pkgs.youtube-dl\n=> \"youtube-dl\"\n"
},
{
"category": "./lib/strings.nix",
"name": "getVersion",
"fn_type": null,
"description": [
"This function takes an argument that's either a derivation or a\nderivation's \"name\" attribute and extracts the version part from that\nargument."
],
"example": "\ngetVersion \"youtube-dl-2016.01.01\"\n=> \"2016.01.01\"\ngetVersion pkgs.youtube-dl\n=> \"2016.01.01\"\n"
},
{
"category": "./lib/strings.nix",
"name": "nameFromURL",
"fn_type": null,
"description": [
"Extract name with version from URL. Ask for separator which is\nsupposed to start extension."
],
"example": "\nnameFromURL \"https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2\" \"-\"\n=> \"nix\"\nnameFromURL \"https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2\" \"_\"\n=> \"nix-1.7-x86\"\n"
},
{
"category": "./lib/strings.nix",
"name": "enableFeature",
"fn_type": null,
"description": [
"Create an --{enable,disable}-<feat> string that can be passed to\nstandard GNU Autoconf scripts."
],
"example": "\nenableFeature true \"shared\"\n=> \"--enable-shared\"\nenableFeature false \"shared\"\n=> \"--disable-shared\"\n"
},
{
"category": "./lib/strings.nix",
"name": "enableFeatureAs",
"fn_type": null,
"description": [
"Create an --{enable-<feat>=<value>,disable-<feat>} string that can be passed to\nstandard GNU Autoconf scripts."
],
"example": "\nenableFeatureAs true \"shared\" \"foo\"\n=> \"--enable-shared=foo\"\nenableFeatureAs false \"shared\" (throw \"ignored\")\n=> \"--disable-shared\"\n"
},
{
"category": "./lib/strings.nix",
"name": "withFeature",
"fn_type": null,
"description": [
"Create an --{with,without}-<feat> string that can be passed to\nstandard GNU Autoconf scripts."
],
"example": "\nwithFeature true \"shared\"\n=> \"--with-shared\"\nwithFeature false \"shared\"\n=> \"--without-shared\"\n"
},
{
"category": "./lib/strings.nix",
"name": "withFeatureAs",
"fn_type": null,
"description": [
"Create an --{with-<feat>=<value>,without-<feat>} string that can be passed to\nstandard GNU Autoconf scripts."
],
"example": "\nwithFeatureAs true \"shared\" \"foo\"\n=> \"--with-shared=foo\"\nwithFeatureAs false \"shared\" (throw \"ignored\")\n=> \"--without-shared\"\n"
},
{
"category": "./lib/strings.nix",
"name": "fixedWidthString",
"fn_type": "fixedWidthString :: int -> string -> string -> string",
"description": [
"Create a fixed width string with additional prefix to match\nrequired width.",
"This function will fail if the input string is longer than the\nrequested length."
],
"example": "\nfixedWidthString 5 \"0\" (toString 15)\n=> \"00015\"\n"
},
{
"category": "./lib/strings.nix",
"name": "fixedWidthNumber",
"fn_type": null,
"description": ["Format a number adding leading zeroes up to fixed width."],
"example": "\nfixedWidthNumber 5 15\n=> \"00015\"\n"
},
{
"category": "./lib/strings.nix",
"name": "floatToString",
"fn_type": null,
"description": [
"Convert a float to a string, but emit a warning when precision is lost\nduring the conversion"
],
"example": "\nfloatToString 0.000001\n=> \"0.000001\"\nfloatToString 0.0000001\n=> trace: warning: Imprecise conversion from float to string 0.000000\n\"0.000000\"\n"
},
{
"category": "./lib/strings.nix",
"name": "isCoercibleToString",
"fn_type": null,
"description": ["Check whether a value can be coerced to a string"],
"example": null
},
{
"category": "./lib/strings.nix",
"name": "isStorePath",
"fn_type": null,
"description": ["Check whether a value is a store path."],
"example": "\nisStorePath \"/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11/bin/python\"\n=> false\nisStorePath \"/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11\"\n=> true\nisStorePath pkgs.python\n=> true\nisStorePath [] || isStorePath 42 || isStorePath {} || …\n=> false\n"
},
{
"category": "./lib/strings.nix",
"name": "toInt",
"fn_type": "string -> int",
"description": [
"Parse a string as an int. Does not support parsing of integers with preceding zero due to\nambiguity between zero-padded and octal numbers. See toIntBase10."
],
"example": "\n\ntoInt \"1337\"\n=> 1337\n\ntoInt \"-4\"\n=> -4\n\ntoInt \" 123 \"\n=> 123\n\ntoInt \"00024\"\n=> error: Ambiguity in interpretation of 00024 between octal and zero padded integer.\n\ntoInt \"3.14\"\n=> error: floating point JSON numbers are not supported\n"
},
{
"category": "./lib/strings.nix",
"name": "toIntBase10",
"fn_type": "string -> int",
"description": [
"Parse a string as a base 10 int. This supports parsing of zero-padded integers."
],
"example": "\ntoIntBase10 \"1337\"\n=> 1337\n\ntoIntBase10 \"-4\"\n=> -4\n\ntoIntBase10 \" 123 \"\n=> 123\n\ntoIntBase10 \"00024\"\n=> 24\n\ntoIntBase10 \"3.14\"\n=> error: floating point JSON numbers are not supported\n"
},
{
"category": "./lib/strings.nix",
"name": "readPathsFromFile",
"fn_type": null,
"description": [
"Read a list of paths from `file`, relative to the `rootPath`.\nLines beginning with `#` are treated as comments and ignored.\nWhitespace is significant.",
"NOTE: This function is not performant and should be avoided."
],
"example": "\nreadPathsFromFile /prefix\n./pkgs/development/libraries/qt-5/5.4/qtbase/series\n=> [ \"/prefix/dlopen-resolv.patch\" \"/prefix/tzdir.patch\"\n\"/prefix/dlopen-libXcursor.patch\" \"/prefix/dlopen-openssl.patch\"\n\"/prefix/dlopen-dbus.patch\" \"/prefix/xdg-config-dirs.patch\"\n\"/prefix/nix-profiles-library-paths.patch\"\n\"/prefix/compose-search-path.patch\" ]\n"
},
{
"category": "./lib/strings.nix",
"name": "fileContents",
"fn_type": "fileContents :: path -> string",
"description": ["Read the contents of a file removing the trailing \\n"],
"example": "\n$ echo \"1.0\" > ./version\n\nfileContents ./version\n=> \"1.0\"\n"
},
{
"category": "./lib/strings.nix",
"name": "sanitizeDerivationName",
"fn_type": "sanitizeDerivationName :: String -> String",
"description": [
"Creates a valid derivation name from a potentially invalid one."
],
"example": "\nsanitizeDerivationName \"../hello.bar # foo\"\n=> \"-hello.bar-foo\"\nsanitizeDerivationName \"\"\n=> \"unknown\"\nsanitizeDerivationName pkgs.hello\n=> \"-nix-store-2g75chlbpxlrqn15zlby2dfh8hr9qwbk-hello-2.10\"\n"
},
{
"category": "./lib/strings.nix",
"name": "levenshtein",
"fn_type": "levenshtein :: string -> string -> int",
"description": [
"Computes the Levenshtein distance between two strings.\nComplexity O(n*m) where n and m are the lengths of the strings.\nAlgorithm adjusted from https://stackoverflow.com/a/9750974/6605742"
],
"example": "\nlevenshtein \"foo\" \"foo\"\n=> 0\nlevenshtein \"book\" \"hook\"\n=> 1\nlevenshtein \"hello\" \"Heyo\"\n=> 3\n"
},
{
"category": "./lib/strings.nix",
"name": "commonPrefixLength",
"fn_type": null,
"description": ["Returns the length of the prefix common to both strings."],
"example": null
},
{
"category": "./lib/strings.nix",
"name": "commonSuffixLength",
"fn_type": null,
"description": ["Returns the length of the suffix common to both strings."],
"example": null
},
{
"category": "./lib/strings.nix",
"name": "levenshteinAtMost",
"fn_type": "levenshteinAtMost :: int -> string -> string -> bool",
"description": [
"Returns whether the levenshtein distance between two strings is at most some value\nComplexity is O(min(n,m)) for k <= 2 and O(n*m) otherwise"
],
"example": "\nlevenshteinAtMost 0 \"foo\" \"foo\"\n=> true\nlevenshteinAtMost 1 \"foo\" \"boa\"\n=> false\nlevenshteinAtMost 2 \"foo\" \"boa\"\n=> true\nlevenshteinAtMost 2 \"This is a sentence\" \"this is a sentense.\"\n=> false\nlevenshteinAtMost 3 \"This is a sentence\" \"this is a sentense.\"\n=> true\n"
},
{
"category": "./lib/trivial.nix",
"name": "id",
"fn_type": "id :: a -> a",
"description": [
"The identity function\nFor when you need a function that does “nothing”."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "const",
"fn_type": "const :: a -> b -> a",
"description": [
"The constant function",
"Ignores the second argument. If called with only one argument,\nconstructs a function that always returns a static value."
],
"example": "\nlet f = const 5; in f 10\n=> 5\n"
},
{
"category": "./lib/trivial.nix",
"name": "pipe",
"fn_type": "pipe :: a -> [<functions>] -> <return type of last function>",
"description": [
"Pipes a value through a list of functions, left to right."
],
"example": "\npipe 2 [\n(x: x + 2) # 2 + 2 = 4\n(x: x * 2) # 4 * 2 = 8\n]\n=> 8\n\n# ideal to do text transformations\npipe [ \"a/b\" \"a/c\" ] [\n\n# create the cp command\n(map (file: ''cp \"${src}/${file}\" $out\\n''))\n\n# concatenate all commands into one string\nlib.concatStrings\n\n# make that string into a nix derivation\n(pkgs.runCommand \"copy-to-out\" {})\n\n]\n=> <drv which copies all files to $out>\n\nThe output type of each function has to be the input type\nof the next function, and the last function returns the\nfinal value.\n"
},
{
"category": "./lib/trivial.nix",
"name": "concat",
"fn_type": "concat :: [a] -> [a] -> [a]",
"description": ["Concatenate two lists"],
"example": "\nconcat [ 1 2 ] [ 3 4 ]\n=> [ 1 2 3 4 ]\n"
},
{
"category": "./lib/trivial.nix",
"name": "or",
"fn_type": null,
"description": ["boolean “or”"],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "and",
"fn_type": null,
"description": ["boolean “and”"],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "bitAnd",
"fn_type": null,
"description": ["bitwise “and”"],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "bitOr",
"fn_type": null,
"description": ["bitwise “or”"],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "bitXor",
"fn_type": null,
"description": ["bitwise “xor”"],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "bitNot",
"fn_type": null,
"description": ["bitwise “not”"],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "boolToString",
"fn_type": "boolToString :: bool -> string",
"description": [
"Convert a boolean to a string.",
"This function uses the strings \"true\" and \"false\" to represent\nboolean values. Calling `toString` on a bool instead returns \"1\"\nand \"\" (sic!)."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "mergeAttrs",
"fn_type": null,
"description": [
"Merge two attribute sets shallowly, right side trumps left",
"mergeAttrs :: attrs -> attrs -> attrs"
],
"example": "\nmergeAttrs { a = 1; b = 2; } { b = 3; c = 4; }\n=> { a = 1; b = 3; c = 4; }\n"
},
{
"category": "./lib/trivial.nix",
"name": "flip",
"fn_type": "flip :: (a -> b -> c) -> (b -> a -> c)",
"description": ["Flip the order of the arguments of a binary function."],
"example": "\nflip concat [1] [2]\n=> [ 2 1 ]\n"
},
{
"category": "./lib/trivial.nix",
"name": "mapNullable",
"fn_type": null,
"description": ["Apply function if the supplied argument is non-null."],
"example": "\nmapNullable (x: x+1) null\n=> null\nmapNullable (x: x+1) 22\n=> 23\n"
},
{
"category": "./lib/trivial.nix",
"name": "version",
"fn_type": null,
"description": ["Returns the current full nixpkgs version number."],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "release",
"fn_type": null,
"description": ["Returns the current nixpkgs release number as string."],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "oldestSupportedRelease",
"fn_type": null,
"description": [
"The latest release that is supported, at the time of release branch-off,\nif applicable.",
"Ideally, out-of-tree modules should be able to evaluate cleanly with all\nsupported Nixpkgs versions (master, release and old release until EOL).\nSo if possible, deprecation warnings should take effect only when all\nout-of-tree expressions/libs/modules can upgrade to the new way without\nlosing support for supported Nixpkgs versions.",
"This release number allows deprecation warnings to be implemented such that\nthey take effect as soon as the oldest release reaches end of life."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "isInOldestRelease",
"fn_type": null,
"description": [
"Whether a feature is supported in all supported releases (at the time of\nrelease branch-off, if applicable). See `oldestSupportedRelease`."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "codeName",
"fn_type": null,
"description": [
"Returns the current nixpkgs release code name.",
"On each release the first letter is bumped and a new animal is chosen\nstarting with that new letter."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "versionSuffix",
"fn_type": null,
"description": ["Returns the current nixpkgs version suffix as string."],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "revisionWithDefault",
"fn_type": "revisionWithDefault :: string -> string",
"description": [
"Attempts to return the the current revision of nixpkgs and\nreturns the supplied default value otherwise."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "inNixShell",
"fn_type": "inNixShell :: bool",
"description": [
"Determine whether the function is being called from inside a Nix\nshell."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "inPureEvalMode",
"fn_type": "inPureEvalMode :: bool",
"description": [
"Determine whether the function is being called from inside pure-eval mode\nby seeing whether `builtins` contains `currentSystem`. If not, we must be in\npure-eval mode."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "min",
"fn_type": null,
"description": ["Return minimum of two numbers."],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "max",
"fn_type": null,
"description": ["Return maximum of two numbers."],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "mod",
"fn_type": null,
"description": ["Integer modulus"],
"example": "\nmod 11 10\n=> 1\nmod 1 10\n=> 1\n"
},
{
"category": "./lib/trivial.nix",
"name": "compare",
"fn_type": null,
"description": [
"C-style comparisons",
"a < b, compare a b => -1\na == b, compare a b => 0\na > b, compare a b => 1"
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "splitByAndCompare",
"fn_type": "(a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int)",
"description": [
"Split type into two subtypes by predicate `p`, take all elements\nof the first subtype to be less than all the elements of the\nsecond subtype, compare elements of a single subtype with `yes`\nand `no` respectively."
],
"example": "\nlet cmp = splitByAndCompare (hasPrefix \"foo\") compare compare; in\n\ncmp \"a\" \"z\" => -1\ncmp \"fooa\" \"fooz\" => -1\n\ncmp \"f\" \"a\" => 1\ncmp \"fooa\" \"a\" => -1\n# while\ncompare \"fooa\" \"a\" => 1\n"
},
{
"category": "./lib/trivial.nix",
"name": "importJSON",
"fn_type": null,
"description": ["Reads a JSON file.", "Type :: path -> any"],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "importTOML",
"fn_type": null,
"description": ["Reads a TOML file.", "Type :: path -> any"],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "warn",
"fn_type": "string -> a -> a",
"description": [
"Print a warning before returning the second argument. This function behaves\nlike `builtins.trace`, but requires a string message and formats it as a\nwarning, including the `warning: ` prefix.",
"To get a call stack trace and abort evaluation, set the environment variable\n`NIX_ABORT_ON_WARN=true` and set the Nix options `--option pure-eval false --show-trace`"
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "warnIf",
"fn_type": "bool -> string -> a -> a",
"description": [
"Like warn, but only warn when the first argument is `true`."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "warnIfNot",
"fn_type": "bool -> string -> a -> a",
"description": [
"Like warnIf, but negated (warn if the first argument is `false`)."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "throwIfNot",
"fn_type": "bool -> string -> a -> a",
"description": [
"Like the `assert b; e` expression, but with a custom error message and\nwithout the semicolon.",
"If true, return the identity function, `r: r`.",
"If false, throw the error message.",
"Calls can be juxtaposed using function application, as `(r: r) a = a`, so\n`(r: r) (r: r) a = a`, and so forth."
],
"example": "\n\nthrowIfNot (lib.isList overlays) \"The overlays argument to nixpkgs must be a list.\"\nlib.foldr (x: throwIfNot (lib.isFunction x) \"All overlays passed to nixpkgs must be functions.\") (r: r) overlays\npkgs\n"
},
{
"category": "./lib/trivial.nix",
"name": "throwIf",
"fn_type": "bool -> string -> a -> a",
"description": [
"Like throwIfNot, but negated (throw if the first argument is `true`)."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "checkListOfEnum",
"fn_type": "String -> List ComparableVal -> List ComparableVal -> a -> a",
"description": [
"Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise."
],
"example": "\nlet colorVariants = [\"bright\" \"dark\" \"black\"]\nin checkListOfEnum \"color variants\" [ \"standard\" \"light\" \"dark\" ] colorVariants;\n=>\nerror: color variants: bright, black unexpected; valid ones: standard, light, dark\n\n"
},
{
"category": "./lib/trivial.nix",
"name": "setFunctionArgs",
"fn_type": null,
"description": [
"Add metadata about expected function arguments to a function.\nThe metadata should match the format given by\nbuiltins.functionArgs, i.e. a set from expected argument to a bool\nrepresenting whether that argument has a default or not.\nsetFunctionArgs : (a → b) → Map String Bool → (a → b)",
"This function is necessary because you can't dynamically create a\nfunction of the { a, b ? foo, ... }: format, but some facilities\nlike callPackage expect to be able to query expected arguments."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "functionArgs",
"fn_type": null,
"description": [
"Extract the expected function arguments from a function.\nThis works both with nix-native { a, b ? foo, ... }: style\nfunctions and functions with args set with 'setFunctionArgs'. It\nhas the same return type and semantics as builtins.functionArgs.\nsetFunctionArgs : (a → b) → Map String Bool."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "isFunction",
"fn_type": null,
"description": [
"Check whether something is a function or something\nannotated with function args."
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "toFunction",
"fn_type": null,
"description": [
"Turns any non-callable values into constant functions.\nReturns callable values as is."
],
"example": "\n\nnix-repl> lib.toFunction 1 2\n1\n\nnix-repl> lib.toFunction (x: x + 1) 2\n3\n"
},
{
"category": "./lib/trivial.nix",
"name": "toHexString",
"fn_type": null,
"description": [
"Convert the given positive integer to a string of its hexadecimal\nrepresentation. For example:",
"toHexString 0 => \"0\"",
"toHexString 16 => \"10\"",
"toHexString 250 => \"FA\""
],
"example": null
},
{
"category": "./lib/trivial.nix",
"name": "toBaseDigits",
"fn_type": null,
"description": [
"`toBaseDigits base i` converts the positive integer i to a list of its\ndigits in the given base. For example:",
"toBaseDigits 10 123 => [ 1 2 3 ]",
"toBaseDigits 2 6 => [ 1 1 0 ]",
"toBaseDigits 16 250 => [ 15 10 ]"
],
"example": null
},
{
"category": "./lib/cli.nix",
"name": "toGNUCommandLineShell",
"fn_type": null,
"description": [
"Automatically convert an attribute set to command-line options.",
"This helps protect against malformed command lines and also to reduce\nboilerplate related to command-line construction for simple use cases.",
"`toGNUCommandLine` returns a list of nix strings.\n`toGNUCommandLineShell` returns an escaped shell string."
],
"example": "\ncli.toGNUCommandLine {} {\ndata = builtins.toJSON { id = 0; };\nX = \"PUT\";\nretry = 3;\nretry-delay = null;\nurl = [ \"https://example.com/foo\" \"https://example.com/bar\" ];\nsilent = false;\nverbose = true;\n}\n=> [\n\"-X\" \"PUT\"\n\"--data\" \"{\\\"id\\\":0}\"\n\"--retry\" \"3\"\n\"--url\" \"https://example.com/foo\"\n\"--url\" \"https://example.com/bar\"\n\"--verbose\"\n]\n\ncli.toGNUCommandLineShell {} {\ndata = builtins.toJSON { id = 0; };\nX = \"PUT\";\nretry = 3;\nretry-delay = null;\nurl = [ \"https://example.com/foo\" \"https://example.com/bar\" ];\nsilent = false;\nverbose = true;\n}\n=> \"'-X' 'PUT' '--data' '{\\\"id\\\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'\";\n"
},
{
"category": "./lib/kernel.nix",
"name": "whenHelpers",
"fn_type": null,
"description": [
"Common patterns/legacy used in common-config/hardened/config.nix"
],
"example": null
},
{
"category": "./lib/strings-with-deps.nix",
"name": "textClosureList",
"fn_type": null,
"description": [
"!!! The interface of this function is kind of messed up, since\nit's way too overloaded and almost but not quite computes a\ntopological sort of the depstrings."
],
"example": null
},
{
"category": "./lib/debug.nix",
"name": "traceIf",
"fn_type": "traceIf :: bool -> string -> a -> a",
"description": [
"Conditionally trace the supplied message, based on a predicate."
],
"example": "\ntraceIf true \"hello\" 3\ntrace: hello\n=> 3\n"
},
{
"category": "./lib/debug.nix",
"name": "traceValFn",
"fn_type": "traceValFn :: (a -> b) -> a -> a",
"description": [
"Trace the supplied value after applying a function to it, and\nreturn the original value."
],
"example": "\ntraceValFn (v: \"mystring ${v}\") \"foo\"\ntrace: mystring foo\n=> \"foo\"\n"
},
{
"category": "./lib/debug.nix",
"name": "traceVal",
"fn_type": "traceVal :: a -> a",
"description": ["Trace the supplied value and return it."],
"example": "\ntraceVal 42\n# trace: 42\n=> 42\n"
},
{
"category": "./lib/debug.nix",
"name": "traceSeq",
"fn_type": "traceSeq :: a -> b -> b",
"description": [
"`builtins.trace`, but the value is `builtins.deepSeq`ed first."
],
"example": "\ntrace { a.b.c = 3; } null\ntrace: { a = <CODE>; }\n=> null\ntraceSeq { a.b.c = 3; } null\ntrace: { a = { b = { c = 3; }; }; }\n=> null\n"
},
{
"category": "./lib/debug.nix",
"name": "traceSeqN",
"fn_type": null,
"description": [
"Like `traceSeq`, but only evaluate down to depth n.\nThis is very useful because lots of `traceSeq` usages\nlead to an infinite recursion."
],
"example": "\ntraceSeqN 2 { a.b.c = 3; } null\ntrace: { a = { b = {…}; }; }\n=> null\n"
},
{
"category": "./lib/debug.nix",
"name": "traceValSeqFn",
"fn_type": null,
"description": [
"A combination of `traceVal` and `traceSeq` that applies a\nprovided function to the value to be traced after `deepSeq`ing\nit."
],
"example": null
},
{
"category": "./lib/debug.nix",
"name": "traceValSeq",
"fn_type": null,
"description": ["A combination of `traceVal` and `traceSeq`."],
"example": null
},
{
"category": "./lib/debug.nix",
"name": "traceValSeqNFn",
"fn_type": null,
"description": [
"A combination of `traceVal` and `traceSeqN` that applies a\nprovided function to the value to be traced."
],
"example": null
},
{
"category": "./lib/debug.nix",
"name": "traceValSeqN",
"fn_type": null,
"description": ["A combination of `traceVal` and `traceSeqN`."],
"example": null
},
{
"category": "./lib/debug.nix",
"name": "traceFnSeqN",
"fn_type": null,
"description": [
"Trace the input and output of a function `f` named `name`,\nboth down to `depth`.",
"This is useful for adding around a function call,\nto see the before/after of values as they are transformed."
],
"example": "\ntraceFnSeqN 2 \"id\" (x: x) { a.b.c = 3; }\ntrace: { fn = \"id\"; from = { a.b = {…}; }; to = { a.b = {…}; }; }\n=> { a.b.c = 3; }\n"
},
{
"category": "./lib/debug.nix",
"name": "runTests",
"fn_type": null,
"description": [
"Evaluate a set of tests. A test is an attribute set `{expr,\nexpected}`, denoting an expression and its expected result. The\nresult is a list of failed tests, each represented as `{name,\nexpected, actual}`, denoting the attribute name of the failing\ntest and its expected and actual results.",
"Used for regression testing of the functions in lib; see\ntests.nix for an example. Only tests having names starting with\n\"test\" are run.",
"Add attr { tests = [\"testName\"]; } to run these tests only."
],
"example": null
},
{
"category": "./lib/debug.nix",
"name": "testAllTrue",
"fn_type": null,
"description": ["Create a test assuming that list elements are `true`."],
"example": "\n{ testX = allTrue [ true ]; }\n"
},
{
"category": "./lib/licenses.nix",
"name": "abstyles",
"fn_type": null,
"description": [
"License identifiers from spdx.org where possible.\n* If you cannot find your license here, then look for a similar license or\n* add it to this list. The URL mentioned above is a good source for inspiration."
],
"example": null
},
{
"category": "./lib/sources.nix",
"name": "pathType",
"fn_type": null,
"description": [
"Returns the type of a path: regular (for file), symlink, or directory."
],
"example": null
},
{
"category": "./lib/sources.nix",
"name": "pathIsDirectory",
"fn_type": null,
"description": [
"Returns true if the path exists and is a directory, false otherwise."
],
"example": null
},
{
"category": "./lib/sources.nix",
"name": "pathIsRegularFile",
"fn_type": null,
"description": [
"Returns true if the path exists and is a regular file, false otherwise."
],
"example": null
},
{
"category": "./lib/sources.nix",
"name": "cleanSourceFilter",
"fn_type": null,
"description": [
"A basic filter for `cleanSourceWith` that removes\ndirectories of version control system, backup files (*~)\nand some generated files."
],
"example": null
},
{
"category": "./lib/sources.nix",
"name": "cleanSource",
"fn_type": null,
"description": [
"Filters a source tree removing version control files and directories using cleanSourceFilter."
],
"example": "\ncleanSource ./.\n"
},
{
"category": "./lib/sources.nix",
"name": "cleanSourceWith",
"fn_type": null,
"description": [
"Like `builtins.filterSource`, except it will compose with itself,\nallowing you to chain multiple calls together without any\nintermediate copies being put in the nix store."
],
"example": "\nlib.cleanSourceWith {\nfilter = f;\nsrc = lib.cleanSourceWith {\nfilter = g;\nsrc = ./.;\n};\n}\n# Succeeds!\n\nbuiltins.filterSource f (builtins.filterSource g ./.)\n# Fails!\n"
},
{
"category": "./lib/sources.nix",
"name": "trace",
"fn_type": "sources.trace :: sourceLike -> Source",
"description": [
"Add logging to a source, for troubleshooting the filtering behavior."
],
"example": null
},
{
"category": "./lib/sources.nix",
"name": "sourceByRegex",
"fn_type": null,
"description": ["Filter sources by a list of regular expressions."],
"example": "src = sourceByRegex ./my-subproject [\".*\\.py$\" \"^database.sql$\"]\n"
},
{
"category": "./lib/sources.nix",
"name": "sourceFilesBySuffices",
"fn_type": "sourceLike -> [String] -> Source",
"description": [
"Get all files ending with the specified suffices from the given\nsource directory or its descendants, omitting files that do not match\nany suffix. The result of the example below will include files like\n`./dir/module.c` and `./dir/subdir/doc.xml` if present."
],
"example": "\nsourceFilesBySuffices ./. [ \".xml\" \".c\" ]\n"
},
{
"category": "./lib/sources.nix",
"name": "commitIdFromGitRepo",
"fn_type": null,
"description": ["Get the commit id of a git repo."],
"example": "commitIdFromGitRepo <nixpkgs/.git>\n"
},
{
"category": "./lib/meta.nix",
"name": "addMetaAttrs",
"fn_type": null,
"description": [
"Add to or override the meta attributes of the given\nderivation."
],
"example": "\naddMetaAttrs {description = \"Bla blah\";} somePkg\n"
},
{
"category": "./lib/meta.nix",
"name": "dontDistribute",
"fn_type": null,
"description": ["Disable Hydra builds of given derivation."],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "setName",
"fn_type": null,
"description": [
"Change the symbolic name of a package for presentation purposes\n(i.e., so that nix-env users can tell them apart)."
],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "updateName",
"fn_type": null,
"description": [
"Like `setName', but takes the previous name as an argument."
],
"example": "\nupdateName (oldName: oldName + \"-experimental\") somePkg\n"
},
{
"category": "./lib/meta.nix",
"name": "appendToName",
"fn_type": null,
"description": [
"Append a suffix to the name of a package (before the version\npart)."
],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "mapDerivationAttrset",
"fn_type": null,
"description": [
"Apply a function to each derivation and only to derivations in an attrset."
],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "setPrio",
"fn_type": null,
"description": ["Set the nix-env priority of the package."],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "lowPrio",
"fn_type": null,
"description": [
"Decrease the nix-env priority of the package, i.e., other\nversions/variants of the package will be preferred."
],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "lowPrioSet",
"fn_type": null,
"description": ["Apply lowPrio to an attrset with derivations"],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "hiPrio",
"fn_type": null,
"description": [
"Increase the nix-env priority of the package, i.e., this\nversion/variant of the package will be preferred."
],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "hiPrioSet",
"fn_type": null,
"description": ["Apply hiPrio to an attrset with derivations"],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "platformMatch",
"fn_type": null,
"description": [
"Check to see if a platform is matched by the given `meta.platforms`\nelement.",
"A `meta.platform` pattern is either",
"1. (legacy) a system string.",
"2. (modern) a pattern for the platform `parsed` field.",
"We can inject these into a pattern for the whole of a structured platform,\nand then match that."
],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "availableOn",
"fn_type": null,
"description": [
"Check if a package is available on a given platform.",
"A package is available on a platform if both",
"1. One of `meta.platforms` pattern matches the given platform.",
"2. None of `meta.badPlatforms` pattern matches the given platform."
],
"example": null
},
{
"category": "./lib/meta.nix",
"name": "getLicenseFromSpdxId",
"fn_type": "getLicenseFromSpdxId :: str -> AttrSet",
"description": [
"Get the corresponding attribute in lib.licenses\nfrom the SPDX ID.\nFor SPDX IDs, see\nhttps://spdx.org/licenses"
],
"example": "\nlib.getLicenseFromSpdxId \"MIT\" == lib.licenses.mit\n=> true\nlib.getLicenseFromSpdxId \"mIt\" == lib.licenses.mit\n=> true\nlib.getLicenseFromSpdxId \"MY LICENSE\"\n=> trace: warning: getLicenseFromSpdxId: No license matches the given SPDX ID: MY LICENSE\n=> { shortName = \"MY LICENSE\"; }\n"
},
{
"category": "./lib/meta.nix",
"name": "getExe",
"fn_type": "getExe :: derivation -> string",
"description": [
"Get the path to the main program of a derivation with either\nmeta.mainProgram or pname or name"
],
"example": "\ngetExe pkgs.hello\n=> \"/nix/store/g124820p9hlv4lj8qplzxw1c44dxaw1k-hello-2.12/bin/hello\"\ngetExe pkgs.mustache-go\n=> \"/nix/store/am9ml4f4ywvivxnkiaqwr0hyxka1xjsf-mustache-go-1.3.0/bin/mustache\"\n"
},
{
"category": "./lib/derivations.nix",
"name": "lazyDerivation",
"fn_type": null,
"description": [
"Restrict a derivation to a predictable set of attribute names, so\nthat the returned attrset is not strict in the actual derivation,\nsaving a lot of computation when the derivation is non-trivial.",
"This is useful in situations where a derivation might only be used for its\npassthru attributes, improving evaluation performance.",
"The returned attribute set is lazy in `derivation`. Specifically, this\nmeans that the derivation will not be evaluated in at least the\nsituations below.",
"For illustration and/or testing, we define derivation such that its\nevaluation is very noticable.",
"let derivation = throw \"This won't be evaluated.\";",
"In the following expressions, `derivation` will _not_ be evaluated:",
"(lazyDerivation { inherit derivation; }).type",
"attrNames (lazyDerivation { inherit derivation; })",
"(lazyDerivation { inherit derivation; } // { foo = true; }).foo",
"(lazyDerivation { inherit derivation; meta.foo = true; }).meta",
"In these expressions, it `derivation` _will_ be evaluated:",
"\"${lazyDerivation { inherit derivation }}\"",
"(lazyDerivation { inherit derivation }).outPath",
"(lazyDerivation { inherit derivation }).meta",
"And the following expressions are not valid, because the refer to\nimplementation details and/or attributes that may not be present on\nsome derivations:",
"(lazyDerivation { inherit derivation }).buildInputs",
"(lazyDerivation { inherit derivation }).passthru",
"(lazyDerivation { inherit derivation }).pythonPath"
],
"example": null
}
]
Reference in New Issue View Git Blame Copy Permalink