Nix 2.30.0
Nix, the purely functional package manager: C API (experimental)
Loading...
Searching...
No Matches
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

BindingsBuildernix_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.
ExternalValuenix_get_external (nix_c_context *context, nix_value *value)
 Get external reference.
nix_valuenix_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_valuenix_get_attr_byname (nix_c_context *context, const nix_value *value, EvalState *state, const char *name)
 Get an attr by name.
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_valuenix_get_attr_byidx (nix_c_context *context, const nix_value *value, EvalState *state, unsigned int i, const char **name)
 Get an attribute by index in the sorted bindings.
const char * nix_get_attr_name_byidx (nix_c_context *context, const nix_value *value, EvalState *state, unsigned int i)
 Get an attribute name by index in the sorted bindings.

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

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]builderthe 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]contextOptional, stores error information
[in]builderBindingsBuilder to insert into
[in]nameattribute name, only used for the duration of the call.
[in]valuevalue 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]contextOptional, stores error information
[out]valueNix value to modify
[in]sourcevalue to copy from
Returns
error code, NIX_OK on success.

◆ nix_get_attr_byidx()

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

Get an attribute by index in the sorted bindings.

Also gives you the name.

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

Parameters
[out]contextOptional, stores error information
[in]valueNix value to inspect
[in]statenix evaluator state
[in]iattribute index
[out]namewill 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.

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

Parameters
[out]contextOptional, stores error information
[in]valueNix value to inspect
[in]statenix evaluator state
[in]nameattribute name
Returns
value, NULL in case of errors

◆ nix_get_attr_name_byidx()

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

Get an attribute name by index in the sorted bindings.

Useful when you want the name but want to avoid evaluation.

Owned by the nix EvalState

Parameters
[out]contextOptional, stores error information
[in]valueNix value to inspect
[in]statenix evaluator state
[in]iattribute 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix value to inspect
[in]statenix evaluator state
[in]ixlist 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix value to inspect
[in]callbackCalled with the string value.
[in]user_dataoptional, 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix 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]contextOptional, stores error information
[in]valueNix value to inspect
[in]statenix evaluator state
[in]nameattribute 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]contextOptional, stores error information
[out]valueNix value to modify
[in]fnfunction to call
[in]argargument 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]contextOptional, stores error information
[out]valueNix value to modify
[in]bthe 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]contextOptional, stores error information
[out]valueNix value to modify
[in]valthe 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]contextOptional, stores error information
[out]valueNix value to modify
[in]dthe 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]contextOptional, stores error information
[out]valueNix value to modify
[in]ithe 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]contextOptional, stores error information
[out]valueNix 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]contextOptional, stores error information
[out]valueNix value to modify
[in]strthe 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]contextOptional, stores error information
[out]valueNix value to modify
[in]opprimop, 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]contextOptional, stores error information
[out]valueNix value to modify
[in]strthe 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_builderThe 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]contextOptional, stores error information
[in]list_builderListBuilder to insert into
[in]indexindex to manipulate
[in]valuevalue 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]contextOptional, stores error information
[out]valueNix value to modify
[in]bbindings 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]contextOptional, stores error information
[in]statenix evaluator state
[in]capacityhow 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]contextOptional, stores error information
[in]list_builderlist builder to use. Make sure to unref this afterwards.
[out]valueNix 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]contextOptional, stores error information
[in]statenix evaluator state
[in]capacityhow many bindings you'll add. Don't exceed.
Returns
owned reference to a list builder. Make sure to unref when you're done.