Handles and Values

Functions
DetlefStatus	detlef_handle_release (DetlefAccess *a, DetlefHandle handle)
DetlefStatus	detlef_handle_clone (DetlefAccess *a, DetlefHandle handle, DetlefHandle *out)
DetlefStatus	detlef_handle_kind (DetlefAccess *a, DetlefHandle handle, DetlefHandleKind *out)
DetlefStatus	detlef_value_none (DetlefAccess *a, DetlefHandle *out)
DetlefStatus	detlef_value_integer (DetlefAccess *a, int64_t value, DetlefHandle *out)
DetlefStatus	detlef_value_float (DetlefAccess *a, double value, DetlefHandle *out)
DetlefStatus	detlef_value_boolean (DetlefAccess *a, DetlefBool value, DetlefHandle *out)
DetlefStatus	detlef_value_string (DetlefAccess *a, DetlefSlice input, DetlefHandle *out)
DetlefStatus	detlef_value_get_integer (DetlefAccess *a, DetlefHandle handle, int64_t *out)
DetlefStatus	detlef_value_get_float (DetlefAccess *a, DetlefHandle handle, double *out)
DetlefStatus	detlef_value_get_boolean (DetlefAccess *a, DetlefHandle handle, DetlefBool *out)
DetlefStatus	detlef_value_get_string (DetlefAccess *a, DetlefHandle handle, DetlefText *out)
DetlefStatus	detlef_value_to_string (DetlefAccess *a, DetlefHandle handle, DetlefText *out)
DetlefStatus	detlef_descriptor_create (DetlefAccess *a, DetlefDescriptorKind kind, DetlefSlice input, DetlefHandle type_handle, DetlefHandle *out)
DetlefStatus	detlef_descriptor_info (DetlefAccess *a, DetlefHandle handle, DetlefText *name_out, DetlefHandle *type_out)
DetlefStatus	detlef_execute (DetlefAccess *a, DetlefSlice source, DetlefHandle *out)

Detailed Description

Function Documentation

detlef_descriptor_create()

DetlefStatus detlef_descriptor_create	(	DetlefAccess *	a,
		DetlefDescriptorKind	kind,
		DetlefSlice	input,
		DetlefHandle	type_handle,
		DetlefHandle *	out
	)

Create a parameter, variadic-parameter, or field descriptor using its name and resolved type.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	kind	DETLEF_DESCRIPTOR_PARAMETER, DETLEF_DESCRIPTOR_VARARG, or DETLEF_DESCRIPTOR_FIELD. The matching DETLEF_PARAMETER, DETLEF_VARARG, and DETLEF_FIELD handle-kind constants are also accepted.
	input	Borrowed UTF-8 name, without a trailing NUL requirement. Storage may be released after the call.
	type_handle	Borrowed resolved type descriptor, for example from detlef_type_lookup(). Not consumed.
[out]	out	On success, receives an owned descriptor handle of the requested kind. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_descriptor_info()

DetlefStatus detlef_descriptor_info	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefText *	name_out,
		DetlefHandle *	type_out
	)

Inspect a parameter, variadic-parameter, or field descriptor without consuming it.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed parameter, variadic-parameter, or field descriptor handle. Not consumed.
[out]	name_out	Receives owned UTF-8 text without a trailing NUL. Must be freed once with detlef_text_free().
[out]	type_out	On success, receives an owned resolved type descriptor for the named descriptor. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_execute()

DetlefStatus detlef_execute	(	DetlefAccess *	a,
		DetlefSlice	source,
		DetlefHandle *	out
	)

Parse and execute source expressions in order and return the last evaluation. Earlier side effects remain if a later expression fails.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	source	Borrowed UTF-8 source bytes. Storage may be released after the call.
[out]	out	On success, receives an owned evaluation handle for the last expression, including descriptors or void. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_handle_clone()

DetlefStatus detlef_handle_clone	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefHandle *	out
	)

Create a separately owned handle to the same value or descriptor. Objects remain shared; no deep copy is made.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed handle to clone; zero produces a zero output. Not consumed.
[out]	out	On success, receives an owned handle to the same item, or zero when the input is zero. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_handle_kind()

DetlefStatus detlef_handle_kind	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefHandleKind *	out
	)

Read the handle category, such as DETLEF_INTEGER, DETLEF_OBJECT, or DETLEF_TYPE. Zero has kind DETLEF_VOID.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed handle to inspect; zero reports DETLEF_VOID. Not consumed.
[out]	out	Receives the DetlefHandleKind constant for the handle.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_handle_release()

DetlefStatus detlef_handle_release	(	DetlefAccess *	a,
		DetlefHandle	handle
	)

Release one owned handle. The handle must not be used or released again; zero is a no-op.

Parameters

a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
handle	Owned handle to release. Must not be used afterwards; zero has no effect.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_boolean()

DetlefStatus detlef_value_boolean	(	DetlefAccess *	a,
		DetlefBool	value,
		DetlefHandle *	out
	)

Create a boolean value from DETLEF_FALSE (0) or DETLEF_TRUE (1). Other inputs are rejected.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	value	DETLEF_FALSE (0) or DETLEF_TRUE (1). Other values are rejected.
[out]	out	On success, receives an owned boolean value handle. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_float()

DetlefStatus detlef_value_float	(	DetlefAccess *	a,
		double	value,
		DetlefHandle *	out
	)

Create a floating-point value from a C double.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	value	Floating-point number to store.
[out]	out	On success, receives an owned float value handle. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_get_boolean()

DetlefStatus detlef_value_get_boolean	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefBool *	out
	)

Read a boolean as zero or one. Other value types are rejected.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed boolean value handle. Not consumed.
[out]	out	Receives DETLEF_FALSE or DETLEF_TRUE.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_get_float()

DetlefStatus detlef_value_get_float	(	DetlefAccess *	a,
		DetlefHandle	handle,
		double *	out
	)

Read a float value. Other value types are rejected rather than converted.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed float value handle. Not consumed.
[out]	out	Receives the floating-point value.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_get_integer()

DetlefStatus detlef_value_get_integer	(	DetlefAccess *	a,
		DetlefHandle	handle,
		int64_t *	out
	)

Read an integer value. Other value types are rejected rather than converted.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed integer value handle. Not consumed.
[out]	out	Receives the signed 64-bit integer.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_get_string()

DetlefStatus detlef_value_get_string	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefText *	out
	)

Copy a string value into owned UTF-8 text. Other value types are rejected.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed string value handle. Not consumed.
[out]	out	Receives owned UTF-8 text without a trailing NUL. Must be freed once with detlef_text_free().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_integer()

DetlefStatus detlef_value_integer	(	DetlefAccess *	a,
		int64_t	value,
		DetlefHandle *	out
	)

Create a signed 64-bit integer value.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	value	Signed 64-bit integer to store.
[out]	out	On success, receives an owned integer value handle. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_none()

DetlefStatus detlef_value_none	(	DetlefAccess *	a,
		DetlefHandle *	out
	)

Create the language value none. Its handle is distinct from zero, which means no result.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
[out]	out	On success, receives an owned handle to the language value none. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_string()

DetlefStatus detlef_value_string	(	DetlefAccess *	a,
		DetlefSlice	input,
		DetlefHandle *	out
	)

Create a string by copying the supplied UTF-8 bytes. Embedded NUL bytes are permitted.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	input	Borrowed UTF-8 bytes to copy. Storage may be released after the call.
[out]	out	On success, receives an owned string value handle. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_value_to_string()

DetlefStatus detlef_value_to_string	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefText *	out
	)

Format a value as text. Strings are returned as their contents; arrays and records use JSON representation.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed runtime value handle to format. Not consumed.
[out]	out	Receives owned UTF-8 text without a trailing NUL. Must be freed once with detlef_text_free().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.