libexpr

Bindings to the Nix evaluator. More...

Modules
	Primops
	Create your own primops.
	GC
	Reference counting and garbage collector operations.
	Externals
	Deal with external values.
	Manipulating values
	Functions to inspect and change nix Value's.

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	State
	Represents a nix evaluator state. More...
struct	Value
	Represents a nix value. More...

Typedefs
typedef struct State	State
typedef void	Value
typedef void	Value
typedef struct State	State

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_err	nix_libexpr_init (nix_c_context *context)
	Initializes the Nix expression evaluator. More...
nix_err	nix_expr_eval_from_string (nix_c_context *context, State *state, const char *expr, const char *path, Value *value)
	Parses and evaluates a Nix expression from a string. More...
nix_err	nix_value_call (nix_c_context *context, State *state, Value *fn, Value *arg, Value *value)
	Calls a Nix function with an argument. More...
nix_err	nix_value_force (nix_c_context *context, State *state, Value *value)
	Forces the evaluation of a Nix value. More...
nix_err	nix_value_force_deep (nix_c_context *context, State *state, Value *value)
	Forces the deep evaluation of a Nix value. More...
State *	nix_state_create (nix_c_context *context, const char **searchPath, Store *store)
	Creates a new Nix state. More...
void	nix_state_free (State *state)
	Frees a Nix state. More...
Value *	nix_alloc_value (nix_c_context *context, State *state)
	Allocate a Nix value. More...

Detailed Description

Bindings to the Nix evaluator.

Example (without error handling):

int main() {
   nix_libexpr_init(NULL);
 
   Store* store = nix_store_open(NULL, "dummy", NULL);
   State* state = nix_state_create(NULL, NULL, store); // empty nix path
   Value *value = nix_alloc_value(NULL, state);
 
   nix_expr_eval_from_string(NULL, state, "builtins.nixVersion", ".", value);
   nix_value_force(NULL, state, value);
   printf("nix version: %s\n", nix_get_string(NULL, value));
 
   nix_gc_decref(NULL, value);
   nix_state_free(state);
   nix_store_unref(store);
   return 0;
   }

Function Documentation

nix_alloc_value()

Value * nix_alloc_value	(	nix_c_context *	context,
		State *	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_expr_eval_from_string()

nix_err nix_expr_eval_from_string	(	nix_c_context *	context,
		State *	state,
		const char *	expr,
		const char *	path,
		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.
[out]	value	The result of the evaluation. You should 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

)

Initializes the Nix expression evaluator.

This function should be called before creating a State. This function can be called multiple times.

Parameters

[out]

context

Optional, stores error information

Returns

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

nix_state_create()

State * nix_state_create	(	nix_c_context *	context,
		const char **	searchPath,
		Store *	store
	)

Creates a new Nix state.

Parameters

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

Returns

A new Nix state or NULL on failure.

nix_state_free()

void nix_state_free

(

State *

state

)

Frees a Nix state.

Does not fail.

Parameters

[in]

state

The state to free.

nix_value_call()

nix_err nix_value_call	(	nix_c_context *	context,
		State *	state,
		Value *	fn,
		Value *	arg,
		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.

nix_value_force()

nix_err nix_value_force	(	nix_c_context *	context,
		State *	state,
		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 converts these Values into their final type.

Note

You don't need this function for basic API usage, since all functions that return a value call it for you. The only place you will see a NIX_TYPE_THUNK is in the primop callback.

Parameters

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

Postcondition

values 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,
		State *	state,
		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.