Functions for allocating and initializing Nix values. More...

Data Structures
struct	BindingsBuilder
	Stores an under-construction set of bindings. More...
struct	ListBuilder
	Stores an under-construction list. More...

Macros
#define	NIX_VALUE_CALL(context, state, value, fn, ...)
	Calls a Nix function with multiple arguments.

Functions
nix_err	nix_expr_eval_from_string (nix_c_context context, EvalState state, const char expr, const char path, nix_value *value)
	Parses and evaluates a Nix expression from a string.
nix_err	nix_value_call (nix_c_context context, EvalState state, nix_value fn, nix_value arg, nix_value *value)
	Calls a Nix function with an argument.
nix_err	nix_value_call_multi (nix_c_context context, EvalState state, nix_value fn, size_t nargs, nix_value args, nix_value value)
	Calls a Nix function with multiple arguments.
nix_err	nix_value_force (nix_c_context context, EvalState state, nix_value *value)
	Forces the evaluation of a Nix value.
nix_value *	nix_alloc_value (nix_c_context context, EvalState state)
	Allocate a Nix value.

Initializers
Values are typically "returned" by initializing already allocated memory that serves as the return value. For this reason, the construction of values is not tied their allocation. Nix is a language with immutable values. Respect this property by only initializing Values once; and only initialize Values that are meant to be initialized by you. Failing to adhere to these rules may lead to undefined behavior.
nix_err	nix_init_bool (nix_c_context context, nix_value value, bool b)
	Set boolean value.
nix_err	nix_init_string (nix_c_context context, nix_value value, const char *str)
	Set a string.
nix_err	nix_init_path_string (nix_c_context context, EvalState s, nix_value value, const char str)
	Set a path.
nix_err	nix_init_float (nix_c_context context, nix_value value, double d)
	Set a float.
nix_err	nix_init_int (nix_c_context context, nix_value value, int64_t i)
	Set an int.
nix_err	nix_init_null (nix_c_context context, nix_value value)
	Set null.
nix_err	nix_init_apply (nix_c_context context, nix_value value, nix_value fn, nix_value arg)
	Set the value to a thunk that will perform a function application when needed.
nix_err	nix_init_external (nix_c_context context, nix_value value, ExternalValue *val)
	Set an external value.
nix_err	nix_make_list (nix_c_context context, ListBuilder list_builder, nix_value *value)
	Create a list from a list builder.
ListBuilder *	nix_make_list_builder (nix_c_context context, EvalState state, size_t capacity)
	Create a list builder.
nix_err	nix_make_attrs (nix_c_context context, nix_value value, BindingsBuilder *b)
	Create an attribute set from a bindings builder.
nix_err	nix_init_primop (nix_c_context context, nix_value value, PrimOp *op)
	Set primop.
nix_err	nix_copy_value (nix_c_context context, nix_value value, const nix_value *source)
	Copy from another value.
nix_err	nix_list_builder_insert (nix_c_context context, ListBuilder list_builder, unsigned int index, nix_value *value)
	Insert bindings into a builder.
void	nix_list_builder_free (ListBuilder *list_builder)
	Free a list builder.

Detailed Description

Functions for allocating and initializing Nix values.

Values are usually created with nix_alloc_value followed by nix_init_* functions. In primop callbacks, allocation is already done and only initialization is needed.

Macro Definition Documentation

◆ NIX_VALUE_CALL

#define NIX_VALUE_CALL	(	context,
		state,
		value,
		fn,
		... )

Value:

do {                                                                    \
    nix_value * args_array[] = {__VA_ARGS__};                           \
    size_t nargs = sizeof(args_array) / sizeof(args_array[0]);          \
    nix_value_call_multi(context, state, fn, nargs, args_array, value); \
} while (0)

Calls a Nix function with multiple arguments.

Technically these are functions that return functions. It is common for Nix functions to be curried, so this function is useful for calling them.

Parameters

[out]	context	Optional, stores error information
[in]	state	The state of the evaluation.
[out]	Value	The result of the function call.
[in]	fn	The Nix function to call.
[in]	...	The arguments to pass to the function.

See also: nix_value_call_multi

Function Documentation

◆ nix_alloc_value()

nix_value * nix_alloc_value	(	nix_c_context *	context,
		EvalState *	state )

Allocate a Nix value.

Call nix_value_decref() when you're done with the pointer

Parameters

[out]	context	Optional, stores error information
[in]	state	nix evaluator state

Returns: value, or null in case of errors

◆ nix_copy_value()

nix_err nix_copy_value	(	nix_c_context *	context,
		nix_value *	value,
		const nix_value *	source )

Copy from another value.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	source	value to copy from

Returns: error code, NIX_OK on success.

◆ nix_expr_eval_from_string()

nix_err nix_expr_eval_from_string	(	nix_c_context *	context,
		EvalState *	state,
		const char *	expr,
		const char *	path,
		nix_value *	value )

Parses and evaluates a Nix expression from a string.

Parameters

[out]	context	Optional, stores error information
[in]	state	The state of the evaluation.
[in]	expr	The Nix expression to parse.
[in]	path	The file path to associate with the expression. This is required for expressions that contain relative paths (such as ./.) that are resolved relative to the given directory.
[out]	Value	The result of the evaluation. You must allocate this yourself.

Returns: NIX_OK if the evaluation was successful, an error code otherwise.

◆ nix_init_apply()

nix_err nix_init_apply	(	nix_c_context *	context,
		nix_value *	value,
		nix_value *	fn,
		nix_value *	arg )

Set the value to a thunk that will perform a function application when needed.

Thunks may be put into attribute sets and lists to perform some computation lazily; on demand. However, note that in some places, a thunk must not be returned, such as in the return value of a PrimOp. In such cases, you may use nix_value_call() instead (but note the different argument order).

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	fn	function to call
[in]	arg	argument to pass

Returns: error code, NIX_OK on successful initialization.

See also: nix_value_call() for a similar function that performs the call immediately and only stores the return Value. Note the different argument order.

◆ nix_init_bool()

nix_err nix_init_bool	(	nix_c_context *	context,
		nix_value *	value,
		bool	b )

Set boolean value.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	b	the boolean value

Returns: error code, NIX_OK on success.

◆ nix_init_external()

nix_err nix_init_external	(	nix_c_context *	context,
		nix_value *	value,
		ExternalValue *	val )

Set an external value.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	val	the external value to set. Will be GC-referenced by the value.

Returns: error code, NIX_OK on success.

◆ nix_init_float()

nix_err nix_init_float	(	nix_c_context *	context,
		nix_value *	value,
		double	d )

Set a float.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	d	the float, 64-bits

Returns: error code, NIX_OK on success.

◆ nix_init_int()

nix_err nix_init_int	(	nix_c_context *	context,
		nix_value *	value,
		int64_t	i )

Set an int.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	i	the int

Returns: error code, NIX_OK on success.

◆ nix_init_null()

nix_err nix_init_null	(	nix_c_context *	context,
		nix_value *	value )

Set null.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify

Returns: error code, NIX_OK on success.

◆ nix_init_path_string()

nix_err nix_init_path_string	(	nix_c_context *	context,
		EvalState *	s,
		nix_value *	value,
		const char *	str )

Set a path.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	str	the path string, copied

Returns: error code, NIX_OK on success.

◆ nix_init_primop()

nix_err nix_init_primop	(	nix_c_context *	context,
		nix_value *	value,
		PrimOp *	op )

Set primop.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	op	primop, will be gc-referenced by the value

See also: nix_alloc_primop

Returns: error code, NIX_OK on success.

◆ nix_init_string()

nix_err nix_init_string	(	nix_c_context *	context,
		nix_value *	value,
		const char *	str )

Set a string.

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	str	the string, copied

Returns: error code, NIX_OK on success.

◆ nix_list_builder_free()

void nix_list_builder_free ( ListBuilder * list_builder )

Free a list builder.

Does not fail.

Parameters

[in] list_builder The builder to free.

◆ nix_list_builder_insert()

nix_err nix_list_builder_insert	(	nix_c_context *	context,
		ListBuilder *	list_builder,
		unsigned int	index,
		nix_value *	value )

Insert bindings into a builder.

Parameters

[out]	context	Optional, stores error information
[in]	list_builder	ListBuilder to insert into
[in]	index	index to manipulate
[in]	Value	value to insert

Returns: error code, NIX_OK on success.

◆ nix_make_attrs()

nix_err nix_make_attrs	(	nix_c_context *	context,
		nix_value *	value,
		BindingsBuilder *	b )

Create an attribute set from a bindings builder.

After this call, the bindings builder becomes invalid and cannot be used again. The only necessary next step is to free it with nix_bindings_builder_free().

Parameters

[out]	context	Optional, stores error information
[out]	Value	Nix value to modify
[in]	b	bindings builder to use

Returns: error code, NIX_OK on success.

See also: nix_bindings_builder_free

◆ nix_make_list()

nix_err nix_make_list	(	nix_c_context *	context,
		ListBuilder *	list_builder,
		nix_value *	value )

Create a list from a list builder.

After this call, the list builder becomes invalid and cannot be used again. The only necessary next step is to free it with nix_list_builder_free().

Parameters

[out]	context	Optional, stores error information
[in]	list_builder	list builder to use
[out]	Value	Nix value to modify

Returns: error code, NIX_OK on success.

See also: nix_list_builder_free

◆ nix_make_list_builder()

ListBuilder * nix_make_list_builder	(	nix_c_context *	context,
		EvalState *	state,
		size_t	capacity )

Create a list builder.

Parameters

[out]	context	Optional, stores error information
[in]	state	nix evaluator state
[in]	capacity	how many bindings you'll add. Don't exceed.

Returns: list builder. Call nix_list_builder_free() when you're done.

◆ nix_value_call()

nix_err nix_value_call	(	nix_c_context *	context,
		EvalState *	state,
		nix_value *	fn,
		nix_value *	arg,
		nix_value *	value )

Calls a Nix function with an argument.

Parameters

[out]	context	Optional, stores error information
[in]	state	The state of the evaluation.
[in]	fn	The Nix function to call.
[in]	arg	The argument to pass to the function.
[out]	Value	The result of the function call.

Returns: NIX_OK if the function call was successful, an error code otherwise.

See also: nix_init_apply() for a similar function that does not performs the call immediately, but stores it as a thunk. Note the different argument order.

◆ nix_value_call_multi()

nix_err nix_value_call_multi	(	nix_c_context *	context,
		EvalState *	state,
		nix_value *	fn,
		size_t	nargs,
		nix_value **	args,
		nix_value *	value )

Calls a Nix function with multiple arguments.

Technically these are functions that return functions. It is common for Nix functions to be curried, so this function is useful for calling them.

Parameters

[out]	context	Optional, stores error information
[in]	state	The state of the evaluation.
[in]	fn	The Nix function to call.
[in]	nargs	The number of arguments.
[in]	args	The arguments to pass to the function.
[out]	Value	The result of the function call.

See also: nix_value_call For the single argument primitive.; NIX_VALUE_CALL For a macro that wraps this function for convenience.

◆ nix_value_force()

nix_err nix_value_force	(	nix_c_context *	context,
		EvalState *	state,
		nix_value *	value )

Forces the evaluation of a Nix value.

The Nix interpreter is lazy, and not-yet-evaluated values can be of type NIX_TYPE_THUNK instead of their actual value.

This function mutates such a nix_value, so that, if successful, it has its final type.

Parameters

[out]	context	Optional, stores error information
[in]	state	The state of the evaluation.
[in,out]	Value	The Nix value to force.

Postcondition: value is not of type NIX_TYPE_THUNK

Returns: NIX_OK if the force operation was successful, an error code otherwise.

Data Structures

Macros

Functions

Initializers

Detailed Description

Macro Definition Documentation

◆ NIX_VALUE_CALL

Function Documentation

◆ nix_alloc_value()

◆ nix_copy_value()

◆ nix_expr_eval_from_string()

◆ nix_init_apply()

◆ nix_init_bool()

◆ nix_init_external()

◆ nix_init_float()

◆ nix_init_int()

◆ nix_init_null()

◆ nix_init_path_string()

◆ nix_init_primop()

◆ nix_init_string()

◆ nix_list_builder_free()

◆ nix_list_builder_insert()

◆ nix_make_attrs()

◆ nix_make_list()

◆ nix_make_list_builder()

◆ nix_value_call()

◆ nix_value_call_multi()

◆ nix_value_force()