Bindings to the Nix language evaluator. More...

Collaboration diagram for libexpr:

Topics
	Adding primops
	GC
	Reference counting and garbage collector operations.
	Externals
	Deal with external values.
	Manipulating values
	Functions to inspect and change Nix language values, represented by nix_value.

Files
file	nix_api_expr.h
	Main entry for the libexpr C bindings.
file	nix_api_value.h
	libexpr C bindings dealing with values

Data Structures
struct	EvalState
	Represents a state of the Nix language evaluator. More...

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

Typedefs
typedef struct nix_eval_state_builder	nix_eval_state_builder
	Builder for EvalState.
typedef struct EvalState	EvalState
typedef struct nix_value	nix_value
	A Nix language value, or thunk that may evaluate to a value.
typedef struct nix_value	nix_value
typedef struct EvalState	EvalState
typedef nix_value	Value
typedef struct nix_realised_string	nix_realised_string
	String without placeholders, and realised store paths.

Enumerations
enum	ValueType { NIX_TYPE_THUNK , NIX_TYPE_INT , NIX_TYPE_FLOAT , NIX_TYPE_BOOL , NIX_TYPE_STRING , NIX_TYPE_PATH , NIX_TYPE_NULL , NIX_TYPE_ATTRS , NIX_TYPE_LIST , NIX_TYPE_FUNCTION , NIX_TYPE_EXTERNAL }

Functions
	NIX_DEPRECATED ("use nix_value instead") typedef nix_value Value
nix_err	nix_libexpr_init (nix_c_context *context)
	Initialize the Nix language evaluator.
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_err	nix_value_force_deep (nix_c_context context, EvalState state, nix_value *value)
	Forces the deep evaluation of a Nix value.
nix_eval_state_builder *	nix_eval_state_builder_new (nix_c_context context, Store store)
	Create a new nix_eval_state_builder.
nix_err	nix_eval_state_builder_load (nix_c_context context, nix_eval_state_builder builder)
	Read settings from the ambient environment.
nix_err	nix_eval_state_builder_set_lookup_path (nix_c_context context, nix_eval_state_builder builder, const char **lookupPath)
	Set the lookup path for <...> expressions.
EvalState *	nix_eval_state_build (nix_c_context context, nix_eval_state_builder builder)
	Create a new Nix language evaluator state.
void	nix_eval_state_builder_free (nix_eval_state_builder *builder)
	Free a nix_eval_state_builder.
EvalState *	nix_state_create (nix_c_context context, const char lookupPath, Store store)
	Create a new Nix language evaluator state.
void	nix_state_free (EvalState *state)
	Frees a Nix state.
nix_value *	nix_alloc_value (nix_c_context context, EvalState state)
	Allocate a Nix value.
nix_err	nix_value_incref (nix_c_context context, nix_value value)
	Increment the garbage collector reference counter for the given nix_value.
nix_err	nix_value_decref (nix_c_context context, nix_value value)
	Decrement the garbage collector reference counter for the given object.
nix_realised_string *	nix_string_realise (nix_c_context context, EvalState state, nix_value *value, bool isIFD)
	Realise a string context.
const char *	nix_realised_string_get_buffer_start (nix_realised_string *realised_string)
	Start of the string.
size_t	nix_realised_string_get_buffer_size (nix_realised_string *realised_string)
	Length of the string.
size_t	nix_realised_string_get_store_path_count (nix_realised_string *realised_string)
	Number of realised store paths.
const StorePath *	nix_realised_string_get_store_path (nix_realised_string *realised_string, size_t index)
	Get a store path. The store paths are stored in an arbitrary order.
void	nix_realised_string_free (nix_realised_string *realised_string)
	Free a realised string.

Detailed Description

Bindings to the Nix language evaluator.

See Embedding the Nix Evaluator for an example.

Macro Definition Documentation

◆ __has_c_attribute

#define __has_c_attribute ( x )

Value:

0

◆ 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

Typedef Documentation

◆ nix_value

typedef struct nix_value nix_value

A Nix language value, or thunk that may evaluate to a value.

Values are the primary objects manipulated in the Nix language. They are considered to be immutable from a user's perspective, but the process of evaluating a value changes its ValueType if it was a thunk. After a value has been evaluated, its ValueType does not change.

Evaluation in this context refers to the process of evaluating a single value object, also called "forcing" the value; see nix_value_force.

The evaluator manages its own memory, but your use of the C API must follow the reference counting rules.

See also: Manipulating values; nix_value_incref, nix_value_decref

Function Documentation

◆ nix_alloc_value()

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

Allocate a Nix value.

Owned by the GC. Use nix_gc_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_eval_state_build()

EvalState * nix_eval_state_build	(	nix_c_context *	context,
		nix_eval_state_builder *	builder )

Create a new Nix language evaluator state.

Remember to nix_eval_state_builder_free after building the state.

Parameters

[out]	context	Optional, stores error information
[in]	builder	The builder to use and free

Returns: A new Nix state or NULL on failure.

See also: nix_eval_state_builder_new, nix_eval_state_builder_free

◆ nix_eval_state_builder_free()

void nix_eval_state_builder_free ( nix_eval_state_builder * builder )

Free a nix_eval_state_builder.

Does not fail.

Parameters

[in] builder The builder to free.

◆ nix_eval_state_builder_load()

nix_err nix_eval_state_builder_load	(	nix_c_context *	context,
		nix_eval_state_builder *	builder )

Read settings from the ambient environment.

Settings are sourced from environment variables and configuration files, as documented in the Nix manual.

Parameters

[out]	context	Optional, stores error information
[out]	builder	The builder to modify.

Returns: NIX_OK if successful, an error code otherwise.

◆ nix_eval_state_builder_new()

nix_eval_state_builder * nix_eval_state_builder_new	(	nix_c_context *	context,
		Store *	store )

Create a new nix_eval_state_builder.

The settings are initialized to their default value. Values can be sourced elsewhere with nix_eval_state_builder_load.

Parameters

[out]	context	Optional, stores error information
[in]	store	The Nix store to use.

Returns: A new nix_eval_state_builder or NULL on failure.

◆ nix_eval_state_builder_set_lookup_path()

nix_err nix_eval_state_builder_set_lookup_path	(	nix_c_context *	context,
		nix_eval_state_builder *	builder,
		const char **	lookupPath )

Set the lookup path for <...> expressions.

Parameters

[in]	context	Optional, stores error information
[in]	builder	The builder to modify.
[in]	lookupPath	Null-terminated array of strings corresponding to entries in NIX_PATH.

◆ 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_libexpr_init()

nix_err nix_libexpr_init ( nix_c_context * context )

Initialize the Nix language evaluator.

This function must be called at least once, at some point before constructing a EvalState for the first time. This function can be called multiple times, and is idempotent.

Parameters

[out] context Optional, stores error information

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

◆ nix_realised_string_free()

void nix_realised_string_free ( nix_realised_string * realised_string )

Free a realised string.

Parameters

[in] realised_string

◆ nix_realised_string_get_buffer_size()

size_t nix_realised_string_get_buffer_size ( nix_realised_string * realised_string )

Length of the string.

Parameters

[in] realised_string

Returns: length of the string in bytes

◆ nix_realised_string_get_buffer_start()

const char * nix_realised_string_get_buffer_start ( nix_realised_string * realised_string )

Start of the string.

Parameters

[in] realised_string

Returns: pointer to the start of the string. It may not be null-terminated.

◆ nix_realised_string_get_store_path()

const StorePath * nix_realised_string_get_store_path	(	nix_realised_string *	realised_string,
		size_t	index )

Get a store path. The store paths are stored in an arbitrary order.

Parameters

[in]	realised_string
[in]	index	index of the store path, must be less than the count

Returns: store path

◆ nix_realised_string_get_store_path_count()

size_t nix_realised_string_get_store_path_count ( nix_realised_string * realised_string )

Number of realised store paths.

Parameters

[in] realised_string

Returns: number of realised store paths that were referenced by the string via its context

◆ nix_state_create()

EvalState * nix_state_create	(	nix_c_context *	context,
		const char **	lookupPath,
		Store *	store )

Create a new Nix language evaluator state.

For more control, use nix_eval_state_builder

Parameters

[out]	context	Optional, stores error information
[in]	lookupPath	Null-terminated array of strings corresponding to entries in NIX_PATH.
[in]	store	The Nix store to use.

Returns: A new Nix state or NULL on failure.

See also: nix_state_builder_new

◆ nix_state_free()

void nix_state_free ( EvalState * state )

Frees a Nix state.

Does not fail.

Parameters

[in] state The state to free.

◆ nix_string_realise()

nix_realised_string * nix_string_realise	(	nix_c_context *	context,
		EvalState *	state,
		nix_value *	value,
		bool	isIFD )

Realise a string context.

This will

realise the store paths referenced by the string's context, and
perform the replacement of placeholders.
create temporary garbage collection roots for the store paths, for the lifetime of the current process.
log to stderr

Parameters

[out]	context	Optional, stores error information
[in]	value	Nix value, which must be a string
[in]	state	Nix evaluator state
[in]	isIFD	If true, disallow derivation outputs if setting allow-import-from-derivation is false. You should set this to true when this call is part of a primop. You should set this to false when building for your application's purpose.

Returns: NULL if failed, are a new nix_realised_string, which must be freed with nix_realised_string_free

◆ 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_decref()

nix_err nix_value_decref	(	nix_c_context *	context,
		nix_value *	value )

Decrement the garbage collector reference counter for the given object.

Parameters

[out]	context	Optional, stores error information
[in]	value	The object to stop referencing

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

◆ nix_value_force_deep()

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

Forces the deep evaluation of a Nix value.

Recursively calls nix_value_force

See also: nix_value_force

Warning: Calling this function on a recursive data structure will cause a stack overflow.

Parameters

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

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

◆ nix_value_incref()

nix_err nix_value_incref	(	nix_c_context *	context,
		nix_value *	value )

Increment the garbage collector reference counter for the given nix_value.

The Nix language evaluator C API keeps track of alive objects by reference counting. When you're done with a refcounted pointer, call nix_value_decref().

Parameters

[out]	context	Optional, stores error information
[in]	value	The object to keep alive

Topics

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ __has_c_attribute

◆ NIX_VALUE_CALL

Typedef Documentation

◆ nix_value

Function Documentation

◆ nix_alloc_value()

◆ nix_eval_state_build()

◆ nix_eval_state_builder_free()

◆ nix_eval_state_builder_load()

◆ nix_eval_state_builder_new()

◆ nix_eval_state_builder_set_lookup_path()

◆ nix_expr_eval_from_string()

◆ nix_libexpr_init()

◆ nix_realised_string_free()

◆ nix_realised_string_get_buffer_size()

◆ nix_realised_string_get_buffer_start()

◆ nix_realised_string_get_store_path()

◆ nix_realised_string_get_store_path_count()

◆ nix_state_create()

◆ nix_state_free()

◆ nix_string_realise()

◆ nix_value_call()

◆ nix_value_call_multi()

◆ nix_value_decref()

◆ nix_value_force()

◆ nix_value_force_deep()

◆ nix_value_incref()