libexpr C bindings dealing with values More...

#include "nix_api_util.h"
#include "nix_api_store.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Typedefs
typedef nix_value	Value
typedef struct BindingsBuilder	BindingsBuilder
typedef struct ListBuilder	ListBuilder
typedef struct PrimOp	PrimOp
typedef struct ExternalValue	ExternalValue
typedef struct nix_realised_string	nix_realised_string
typedef void(*	PrimOpFun) (void user_data, nix_c_context context, EvalState state, nix_value args, nix_value ret)
	Function pointer for primops.

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 , NIX_TYPE_FAILED }
	Represents the state of a Nix value. More...

Functions
PrimOp *	nix_alloc_primop (nix_c_context context, PrimOpFun fun, int arity, const char name, const char *args, const char doc, void *user_data)
	Allocate a PrimOp.
nix_err	nix_register_primop (nix_c_context context, PrimOp primOp)
	add a primop to the builtins attribute set
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.
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.
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.
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.
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

libexpr C bindings dealing with values

Typedef Documentation

◆ Value

typedef nix_value Value

Deprecated: Use nix_value instead

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_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: bindings builder. Call nix_bindings_builder_free() when you're done.

◆ 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, valid until realised_string is freed. 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 valid until realised_string is freed

◆ 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_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, or a new nix_realised_string, which must be freed with nix_realised_string_free

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ Value

Function Documentation

◆ nix_bindings_builder_free()

◆ nix_bindings_builder_insert()

◆ nix_make_bindings_builder()

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