Manipulating values

Functions to inspect and change Nix language values, represented by nix_value. More...

Typedefs
typedef struct BindingsBuilder	BindingsBuilder
	Stores an under-construction set of bindings.
typedef struct ListBuilder	ListBuilder
	Stores an under-construction list.

Functions
BindingsBuilder *	nix_make_bindings_builder (nix_c_context *context, EvalState *state, size_t capacity)
	Create a bindings builder.
nix_err	nix_bindings_builder_insert (nix_c_context *context, BindingsBuilder *builder, const char *name, nix_value *value)
	Insert bindings into a builder.
void	nix_bindings_builder_free (BindingsBuilder *builder)
	Free a bindings builder.

Getters
ValueType	nix_get_type (nix_c_context *context, const nix_value *value)
	Get value type.
const char *	nix_get_typename (nix_c_context *context, const nix_value *value)
	Get type name of value as defined in the evaluator.
bool	nix_get_bool (nix_c_context *context, const nix_value *value)
	Get boolean value.
nix_err	nix_get_string (nix_c_context *context, const nix_value *value, nix_get_string_callback callback, void *user_data)
	Get the raw string.
const char *	nix_get_path_string (nix_c_context *context, const nix_value *value)
	Get path as string.
unsigned int	nix_get_list_size (nix_c_context *context, const nix_value *value)
	Get the length of a list.
unsigned int	nix_get_attrs_size (nix_c_context *context, const nix_value *value)
	Get the element count of an attrset.
double	nix_get_float (nix_c_context *context, const nix_value *value)
	Get float value in 64 bits.
int64_t	nix_get_int (nix_c_context *context, const nix_value *value)
	Get int value.
ExternalValue *	nix_get_external (nix_c_context *context, nix_value *value)
	Get external reference.
nix_value *	nix_get_list_byidx (nix_c_context *context, const nix_value *value, EvalState *state, unsigned int ix)
	Get the ix'th element of a list.
nix_value *	nix_get_list_byidx_lazy (nix_c_context *context, const nix_value *value, EvalState *state, unsigned int ix)
	Get the ix'th element of a list without forcing evaluation of the element.
nix_value *	nix_get_attr_byname (nix_c_context *context, const nix_value *value, EvalState *state, const char *name)
	Get an attr by name.
nix_value *	nix_get_attr_byname_lazy (nix_c_context *context, const nix_value *value, EvalState *state, const char *name)
	Get an attribute value by attribute name, without forcing evaluation of the attribute's value.
bool	nix_has_attr_byname (nix_c_context *context, const nix_value *value, EvalState *state, const char *name)
	Check if an attribute name exists on a value.
nix_value *	nix_get_attr_byidx (nix_c_context *context, nix_value *value, EvalState *state, unsigned int i, const char **name)
	Get an attribute by index.
nix_value *	nix_get_attr_byidx_lazy (nix_c_context *context, nix_value *value, EvalState *state, unsigned int i, const char **name)
	Get an attribute by index, without forcing evaluation of the attribute's value.
const char *	nix_get_attr_name_byidx (nix_c_context *context, nix_value *value, EvalState *state, unsigned int i)
	Get an attribute name by index.

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_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.
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.

Detailed Description

Functions to inspect and change Nix language values, represented by nix_value.

Typedef Documentation

BindingsBuilder

typedef struct BindingsBuilder BindingsBuilder

Stores an under-construction set of bindings.

Do not reuse.

See also

nix_make_bindings_builder, nix_bindings_builder_free, nix_make_attrs

nix_bindings_builder_insert

ListBuilder

typedef struct ListBuilder ListBuilder

Stores an under-construction list.

Do not reuse.

See also

nix_make_list_builder, nix_list_builder_free, nix_make_list

nix_list_builder_insert

Function Documentation

nix_bindings_builder_free()

void nix_bindings_builder_free

(

BindingsBuilder *

builder

)

Free a bindings builder.

Does not fail.

Parameters

[in]

builder

the builder to free

nix_bindings_builder_insert()

nix_err nix_bindings_builder_insert	(	nix_c_context *	context,
		BindingsBuilder *	builder,
		const char *	name,
		nix_value *	value )

Insert bindings into a builder.

Parameters

[out]	context	Optional, stores error information
[in]	builder	BindingsBuilder to insert into
[in]	name	attribute name, only used for the duration of the call.
[in]	value	value to give the binding

Returns

error code, NIX_OK on success.

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_get_attr_byidx()

nix_value * nix_get_attr_byidx	(	nix_c_context *	context,
		nix_value *	value,
		EvalState *	state,
		unsigned int	i,
		const char **	name )

Get an attribute by index.

Also gives you the name.

Attributes are returned in an unspecified order which is NOT suitable for reproducible operations. In Nix's domain, reproducibility is paramount. The caller is responsible for sorting the attributes or storing them in an ordered map to ensure deterministic behavior in your application.

Note

When Nix does sort attributes, which it does for virtually all intermediate operations and outputs, it uses byte-wise lexicographic order (equivalent to lexicographic order by Unicode scalar value for valid UTF-8). We recommend applying this same ordering for consistency.

Use nix_gc_decref when you're done with the pointer

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect
[in]	state	nix evaluator state
[in]	i	attribute index
[out]	name	will store a pointer to the attribute name

Returns

value, NULL in case of errors

nix_get_attr_byidx_lazy()

nix_value * nix_get_attr_byidx_lazy	(	nix_c_context *	context,
		nix_value *	value,
		EvalState *	state,
		unsigned int	i,
		const char **	name )

Get an attribute by index, without forcing evaluation of the attribute's value.

Also gives you the name.

Returns the attribute value without forcing its evaluation, allowing access to lazy values. The attribute set value itself must already have been evaluated.

Attributes are returned in an unspecified order which is NOT suitable for reproducible operations. In Nix's domain, reproducibility is paramount. The caller is responsible for sorting the attributes or storing them in an ordered map to ensure deterministic behavior in your application.

Note

When Nix does sort attributes, which it does for virtually all intermediate operations and outputs, it uses byte-wise lexicographic order (equivalent to lexicographic order by Unicode scalar value for valid UTF-8). We recommend applying this same ordering for consistency.

Use nix_gc_decref when you're done with the pointer

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect (must be an evaluated attribute set)
[in]	state	nix evaluator state
[in]	i	attribute index
[out]	name	will store a pointer to the attribute name

Returns

value, NULL in case of errors

nix_get_attr_byname()

nix_value * nix_get_attr_byname	(	nix_c_context *	context,
		const nix_value *	value,
		EvalState *	state,
		const char *	name )

Get an attr by name.

Use nix_gc_decref when you're done with the pointer

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect
[in]	state	nix evaluator state
[in]	name	attribute name

Returns

value, NULL in case of errors

nix_get_attr_byname_lazy()

nix_value * nix_get_attr_byname_lazy	(	nix_c_context *	context,
		const nix_value *	value,
		EvalState *	state,
		const char *	name )

Get an attribute value by attribute name, without forcing evaluation of the attribute's value.

Returns the attribute value without forcing its evaluation, allowing access to lazy values. The attribute set value itself must already be evaluated.

Use nix_gc_decref when you're done with the pointer

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect (must be an evaluated attribute set)
[in]	state	nix evaluator state
[in]	name	attribute name

Returns

value, NULL in case of errors

nix_get_attr_name_byidx()

const char * nix_get_attr_name_byidx	(	nix_c_context *	context,
		nix_value *	value,
		EvalState *	state,
		unsigned int	i )

Get an attribute name by index.

Returns the attribute name without forcing evaluation of the attribute's value.

Attributes are returned in an unspecified order which is NOT suitable for reproducible operations. In Nix's domain, reproducibility is paramount. The caller is responsible for sorting the attributes or storing them in an ordered map to ensure deterministic behavior in your application.

Note

When Nix does sort attributes, which it does for virtually all intermediate operations and outputs, it uses byte-wise lexicographic order (equivalent to lexicographic order by Unicode scalar value for valid UTF-8). We recommend applying this same ordering for consistency.

Owned by the nix EvalState

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect
[in]	state	nix evaluator state
[in]	i	attribute index

Returns

name, NULL in case of errors

nix_get_attrs_size()

unsigned int nix_get_attrs_size	(	nix_c_context *	context,
		const nix_value *	value )

Get the element count of an attrset.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

attrset element count, error info via context

nix_get_bool()

bool nix_get_bool	(	nix_c_context *	context,
		const nix_value *	value )

Get boolean value.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

true or false, error info via context

nix_get_external()

ExternalValue * nix_get_external	(	nix_c_context *	context,
		nix_value *	value )

Get external reference.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

reference to external, NULL in case of error

nix_get_float()

double nix_get_float	(	nix_c_context *	context,
		const nix_value *	value )

Get float value in 64 bits.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

float contents, error info via context

nix_get_int()

int64_t nix_get_int	(	nix_c_context *	context,
		const nix_value *	value )

Get int value.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

int contents, error info via context

nix_get_list_byidx()

nix_value * nix_get_list_byidx	(	nix_c_context *	context,
		const nix_value *	value,
		EvalState *	state,
		unsigned int	ix )

Get the ix'th element of a list.

Owned by the GC. Use nix_gc_decref when you're done with the pointer

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect
[in]	state	nix evaluator state
[in]	ix	list element to get

Returns

value, NULL in case of errors

nix_get_list_byidx_lazy()

nix_value * nix_get_list_byidx_lazy	(	nix_c_context *	context,
		const nix_value *	value,
		EvalState *	state,
		unsigned int	ix )

Get the ix'th element of a list without forcing evaluation of the element.

Returns the list element without forcing its evaluation, allowing access to lazy values. The list value itself must already be evaluated.

Owned by the GC. Use nix_gc_decref when you're done with the pointer

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect (must be an evaluated list)
[in]	state	nix evaluator state
[in]	ix	list element to get

Returns

value, NULL in case of errors

nix_get_list_size()

unsigned int nix_get_list_size	(	nix_c_context *	context,
		const nix_value *	value )

Get the length of a list.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

length of list, error info via context

nix_get_path_string()

const char * nix_get_path_string	(	nix_c_context *	context,
		const nix_value *	value )

Get path as string.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

string, if the type is NIX_TYPE_PATH

NULL in case of error.

nix_get_string()

nix_err nix_get_string	(	nix_c_context *	context,
		const nix_value *	value,
		nix_get_string_callback	callback,
		void *	user_data )

Get the raw string.

This may contain placeholders.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect
[in]	callback	Called with the string value.
[in]	user_data	optional, arbitrary data, passed to the callback when it's called.

Returns

string

error code, NIX_OK on success.

nix_get_type()

ValueType nix_get_type	(	nix_c_context *	context,
		const nix_value *	value )

Get value type.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

type of nix value

nix_get_typename()

const char * nix_get_typename	(	nix_c_context *	context,
		const nix_value *	value )

Get type name of value as defined in the evaluator.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect

Returns

type name, owned string

Todo

way to free the result

nix_has_attr_byname()

bool nix_has_attr_byname	(	nix_c_context *	context,
		const nix_value *	value,
		EvalState *	state,
		const char *	name )

Check if an attribute name exists on a value.

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value to inspect
[in]	state	nix evaluator state
[in]	name	attribute name

Returns

value, error info via context

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.

Parameters

[out]	context	Optional, stores error information
[out]	value	Nix value to modify
[in]	b	bindings builder to use. Make sure to unref this afterwards.

Returns

error code, NIX_OK on success.

nix_make_bindings_builder()

BindingsBuilder * nix_make_bindings_builder	(	nix_c_context *	context,
		EvalState *	state,
		size_t	capacity )

Create a bindings 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

owned reference to a bindings builder. Make sure to unref when you're done.

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.

Parameters

[out]	context	Optional, stores error information
[in]	list_builder	list builder to use. Make sure to unref this afterwards.
[out]	value	Nix value to modify

Returns

error code, NIX_OK on success.

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

owned reference to a list builder. Make sure to unref when you're done.