Nix 2.30.0
Nix, the purely functional package manager: C API (experimental)
Loading...
Searching...
No Matches
libexpr

Bindings to the Nix language evaluator. More...

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_buildernix_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.
EvalStatenix_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.
EvalStatenix_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_valuenix_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_stringnix_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 StorePathnix_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)
struct nix_value nix_value
A Nix language value, or thunk that may evaluate to a value.
Definition nix_api_expr.h:62

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]contextOptional, stores error information
[in]stateThe state of the evaluation.
[out]valueThe result of the function call.
[in]fnThe 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]contextOptional, stores error information
[in]statenix 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]contextOptional, stores error information
[in]builderThe 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]builderThe 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]contextOptional, stores error information
[out]builderThe 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]contextOptional, stores error information
[in]storeThe 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]contextOptional, stores error information
[in]builderThe builder to modify.
[in]lookupPathNull-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]contextOptional, stores error information
[in]stateThe state of the evaluation.
[in]exprThe Nix expression to parse.
[in]pathThe 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]valueThe 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]contextOptional, 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]indexindex 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]contextOptional, stores error information
[in]lookupPathNull-terminated array of strings corresponding to entries in NIX_PATH.
[in]storeThe 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]stateThe 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]contextOptional, stores error information
[in]valueNix value, which must be a string
[in]stateNix evaluator state
[in]isIFDIf 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]contextOptional, stores error information
[in]stateThe state of the evaluation.
[in]fnThe Nix function to call.
[in]argThe argument to pass to the function.
[out]valueThe 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]contextOptional, stores error information
[in]stateThe state of the evaluation.
[in]fnThe Nix function to call.
[in]nargsThe number of arguments.
[in]argsThe arguments to pass to the function.
[out]valueThe 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]contextOptional, stores error information
[in]valueThe 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]contextOptional, stores error information
[in]stateThe state of the evaluation.
[in,out]valueThe 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]contextOptional, stores error information
[in]stateThe state of the evaluation.
[in,out]valueThe 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]contextOptional, stores error information
[in]valueThe object to keep alive