Miscellaneous functions
lib.trivial.id
id :: a -> a
The identity function For when you need a function that does “nothing”.
-
x
-
The value to return
lib.trivial.const
const :: a -> b -> a
The constant function
Ignores the second argument. If called with only one argument, constructs a function that always returns a static value.
-
x
-
Value to return
-
y
-
Value to ignore
lib.trivial.const usage example
let f = const 5; in f 10
=> 5
lib.trivial.pipe
pipe :: a -> [<functions>] -> <return type of last function>
Pipes a value through a list of functions, left to right.
-
val
-
Function argument
-
functions
-
Function argument
lib.trivial.pipe usage example
pipe 2 [
(x: x + 2) # 2 + 2 = 4
(x: x * 2) # 4 * 2 = 8
]
=> 8
# ideal to do text transformations
pipe [ "a/b" "a/c" ] [
# create the cp command
(map (file: ''cp "${src}/${file}" $out\n''))
# concatenate all commands into one string
lib.concatStrings
# make that string into a nix derivation
(pkgs.runCommand "copy-to-out" {})
]
=> <drv which copies all files to $out>
The output type of each function has to be the input type
of the next function, and the last function returns the
final value.
lib.trivial.concat
concat :: [a] -> [a] -> [a]
Concatenate two lists
-
x
-
Function argument
-
y
-
Function argument
lib.trivial.concat usage example
concat [ 1 2 ] [ 3 4 ]
=> [ 1 2 3 4 ]
lib.trivial.or
boolean “or”
-
x
-
Function argument
-
y
-
Function argument
lib.trivial.and
boolean “and”
-
x
-
Function argument
-
y
-
Function argument
lib.trivial.bitAnd
bitwise “and”
lib.trivial.bitOr
bitwise “or”
lib.trivial.bitXor
bitwise “xor”
lib.trivial.bitNot
bitwise “not”
lib.trivial.boolToString
boolToString :: bool -> string
Convert a boolean to a string.
This function uses the strings "true" and "false" to represent
boolean values. Calling toString
on a bool instead returns "1"
and "" (sic!).
-
b
-
Function argument
lib.trivial.mergeAttrs
Merge two attribute sets shallowly, right side trumps left
mergeAttrs :: attrs -> attrs -> attrs
-
x
-
Left attribute set
-
y
-
Right attribute set (higher precedence for equal keys)
lib.trivial.mergeAttrs usage example
mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; }
=> { a = 1; b = 3; c = 4; }
lib.trivial.flip
flip :: (a -> b -> c) -> (b -> a -> c)
Flip the order of the arguments of a binary function.
-
f
-
Function argument
-
a
-
Function argument
-
b
-
Function argument
lib.trivial.flip usage example
flip concat [1] [2]
=> [ 2 1 ]
lib.trivial.mapNullable
Apply function if the supplied argument is non-null.
-
f
-
Function to call
-
a
-
Argument to check for null before passing it to
f
lib.trivial.mapNullable usage example
mapNullable (x: x+1) null
=> null
mapNullable (x: x+1) 22
=> 23
lib.trivial.version
Returns the current full nixpkgs version number.
lib.trivial.release
Returns the current nixpkgs release number as string.
lib.trivial.oldestSupportedRelease
The latest release that is supported, at the time of release branch-off, if applicable.
Ideally, out-of-tree modules should be able to evaluate cleanly with all supported Nixpkgs versions (master, release and old release until EOL). So if possible, deprecation warnings should take effect only when all out-of-tree expressions/libs/modules can upgrade to the new way without losing support for supported Nixpkgs versions.
This release number allows deprecation warnings to be implemented such that they take effect as soon as the oldest release reaches end of life.
lib.trivial.isInOldestRelease
Whether a feature is supported in all supported releases (at the time of
release branch-off, if applicable). See oldestSupportedRelease
.
-
release
-
Release number of feature introduction as an integer, e.g. 2111 for 21.11. Set it to the upcoming release, matching the nixpkgs/.version file.
lib.trivial.codeName
Returns the current nixpkgs release code name.
On each release the first letter is bumped and a new animal is chosen starting with that new letter.
lib.trivial.versionSuffix
Returns the current nixpkgs version suffix as string.
lib.trivial.revisionWithDefault
revisionWithDefault :: string -> string
Attempts to return the the current revision of nixpkgs and returns the supplied default value otherwise.
-
default
-
Default value to return if revision can not be determined
lib.trivial.inNixShell
inNixShell :: bool
Determine whether the function is being called from inside a Nix shell.
lib.trivial.inPureEvalMode
inPureEvalMode :: bool
Determine whether the function is being called from inside pure-eval mode
by seeing whether builtins
contains currentSystem
. If not, we must be in
pure-eval mode.
lib.trivial.min
Return minimum of two numbers.
-
x
-
Function argument
-
y
-
Function argument
lib.trivial.max
Return maximum of two numbers.
-
x
-
Function argument
-
y
-
Function argument
lib.trivial.mod
Integer modulus
-
base
-
Function argument
-
int
-
Function argument
lib.trivial.mod usage example
mod 11 10
=> 1
mod 1 10
=> 1
lib.trivial.compare
C-style comparisons
a < b, compare a b => -1 a == b, compare a b => 0 a > b, compare a b => 1
-
a
-
Function argument
-
b
-
Function argument
lib.trivial.splitByAndCompare
(a -> bool) -> (a -> a -> int) -> (a -> a -> int) -> (a -> a -> int)
Split type into two subtypes by predicate p
, take all elements
of the first subtype to be less than all the elements of the
second subtype, compare elements of a single subtype with yes
and no
respectively.
-
p
-
Predicate
-
yes
-
Comparison function if predicate holds for both values
-
no
-
Comparison function if predicate holds for neither value
-
a
-
First value to compare
-
b
-
Second value to compare
lib.trivial.splitByAndCompare usage example
let cmp = splitByAndCompare (hasPrefix "foo") compare compare; in
cmp "a" "z" => -1
cmp "fooa" "fooz" => -1
cmp "f" "a" => 1
cmp "fooa" "a" => -1
# while
compare "fooa" "a" => 1
lib.trivial.importJSON
Reads a JSON file.
Type :: path -> any
-
path
-
Function argument
lib.trivial.importTOML
Reads a TOML file.
Type :: path -> any
-
path
-
Function argument
lib.trivial.warn
string -> a -> a
Print a warning before returning the second argument. This function behaves
like builtins.trace
, but requires a string message and formats it as a
warning, including the warning:
prefix.
To get a call stack trace and abort evaluation, set the environment variable
NIX_ABORT_ON_WARN=true
and set the Nix options --option pure-eval false --show-trace
lib.trivial.warnIf
bool -> string -> a -> a
Like warn, but only warn when the first argument is true
.
-
cond
-
Function argument
-
msg
-
Function argument
lib.trivial.warnIfNot
bool -> string -> a -> a
Like warnIf, but negated (warn if the first argument is false
).
-
cond
-
Function argument
-
msg
-
Function argument
lib.trivial.throwIfNot
bool -> string -> a -> a
Like the assert b; e
expression, but with a custom error message and
without 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
(r: r) (r: r) a = a
, and so forth.
-
cond
-
Function argument
-
msg
-
Function argument
lib.trivial.throwIfNot usage example
throwIfNot (lib.isList overlays) "The overlays argument to nixpkgs must be a list."
lib.foldr (x: throwIfNot (lib.isFunction x) "All overlays passed to nixpkgs must be functions.") (r: r) overlays
pkgs
lib.trivial.throwIf
bool -> string -> a -> a
Like throwIfNot, but negated (throw if the first argument is true
).
-
cond
-
Function argument
-
msg
-
Function argument
lib.trivial.checkListOfEnum
String -> List ComparableVal -> List ComparableVal -> a -> a
Check if the elements in a list are valid values from a enum, returning the identity function, or throwing an error message otherwise.
-
msg
-
Function argument
-
valid
-
Function argument
-
given
-
Function argument
lib.trivial.checkListOfEnum usage example
let colorVariants = ["bright" "dark" "black"]
in checkListOfEnum "color variants" [ "standard" "light" "dark" ] colorVariants;
=>
error: color variants: bright, black unexpected; valid ones: standard, light, dark
lib.trivial.setFunctionArgs
Add metadata about expected function arguments to a function. The metadata should match the format given by builtins.functionArgs, i.e. a set from expected argument to a bool representing whether that argument has a default or not. setFunctionArgs : (a → b) → Map String Bool → (a → b)
This function is necessary because you can't dynamically create a function of the { a, b ? foo, ... }: format, but some facilities like callPackage expect to be able to query expected arguments.
-
f
-
Function argument
-
args
-
Function argument
lib.trivial.functionArgs
Extract the expected function arguments from a function. This works both with nix-native { a, b ? foo, ... }: style functions and functions with args set with 'setFunctionArgs'. It has the same return type and semantics as builtins.functionArgs. setFunctionArgs : (a → b) → Map String Bool.
-
f
-
Function argument
lib.trivial.isFunction
Check whether something is a function or something annotated with function args.
-
f
-
Function argument
lib.trivial.toFunction
Turns any non-callable values into constant functions. Returns callable values as is.
-
v
-
Any value
lib.trivial.toFunction usage example
nix-repl> lib.toFunction 1 2
1
nix-repl> lib.toFunction (x: x + 1) 2
3
lib.trivial.toHexString
Convert the given positive integer to a string of its hexadecimal representation. For example:
toHexString 0 => "0"
toHexString 16 => "10"
toHexString 250 => "FA"
-
i
-
Function argument
lib.trivial.toBaseDigits
toBaseDigits base i
converts the positive integer i to a list of its
digits in the given base. For example:
toBaseDigits 10 123 => [ 1 2 3 ]
toBaseDigits 2 6 => [ 1 1 0 ]
toBaseDigits 16 250 => [ 15 10 ]
-
base
-
Function argument
-
i
-
Function argument