Expressions and Environments

Functions
DetlefStatus	detlef_expression_parse (DetlefAccess *a, DetlefSlice source, DetlefHandle *out)
DetlefStatus	detlef_expression_span (DetlefAccess *a, DetlefHandle handle, DetlefSpan *out)
DetlefStatus	detlef_expression_evaluate (DetlefAccess *a, DetlefHandle expr, DetlefBool require_value, DetlefHandle *out)
DetlefStatus	detlef_expression_with_variables (DetlefAccess *a, DetlefHandle expr, const DetlefNamed *bindings, size_t count, DetlefHandle *out)
DetlefStatus	detlef_environment_capture (DetlefAccess *a, DetlefHandle *out)
DetlefStatus	detlef_environment_evaluate (DetlefAccess *a, DetlefHandle env, DetlefHandle expr, DetlefHandle *out)
DetlefStatus	detlef_expression_kind (DetlefAccess *a, DetlefHandle handle, DetlefExpressionKind *out)
DetlefStatus	detlef_expression_child_count (DetlefAccess *a, DetlefHandle handle, size_t *out)
DetlefStatus	detlef_expression_child (DetlefAccess *a, DetlefHandle handle, size_t index, DetlefHandle *out)
DetlefStatus	detlef_expression_text (DetlefAccess *a, DetlefHandle handle, DetlefText *out)
DetlefStatus	detlef_expression_literal_value (DetlefAccess *a, DetlefHandle handle, DetlefHandle *out)
DetlefStatus	detlef_expression_identifier (DetlefAccess *a, DetlefSlice input, DetlefSpan span, DetlefHandle *out)
DetlefStatus	detlef_expression_literal (DetlefAccess *a, DetlefHandle handle, DetlefSpan span, DetlefHandle *out)
DetlefStatus	detlef_expression_call (DetlefAccess *a, DetlefHandle callee, const DetlefHandle *arguments, size_t count, DetlefSpan span, DetlefHandle *out)
DetlefStatus	detlef_expression_block (DetlefAccess *a, const DetlefHandle *expressions, size_t count, DetlefSpan span, DetlefHandle *out)

Detailed Description

Function Documentation

detlef_environment_capture()

DetlefStatus detlef_environment_capture	(	DetlefAccess *	a,
		DetlefHandle *	out
	)

Capture the current lexical environment. The returned environment handle keeps its captured objects alive until released.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
[out]	out	On success, receives an owned captured-environment handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_environment_evaluate()

DetlefStatus detlef_environment_evaluate	(	DetlefAccess *	a,
		DetlefHandle	env,
		DetlefHandle	expr,
		DetlefHandle *	out
	)

Evaluate an expression in a captured lexical environment.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	env	Borrowed captured-environment handle from detlef_environment_capture(); must be nonzero. Not consumed.
	expr	Borrowed expression handle to evaluate. Not consumed.
[out]	out	On success, receives an owned evaluation handle for the expression's result. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_block()

DetlefStatus detlef_expression_block	(	DetlefAccess *	a,
		const DetlefHandle *	expressions,
		size_t	count,
		DetlefSpan	span,
		DetlefHandle *	out
	)

Create a block expression by copying its ordered child expressions.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	expressions	Borrowed array of expression handles in evaluation order, copied into the block. Handles are not consumed.
	count	Number of entries in the supplied array.
	span	Half-open source range in UTF-8 byte offsets.
[out]	out	On success, receives an owned block expression handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_call()

DetlefStatus detlef_expression_call	(	DetlefAccess *	a,
		DetlefHandle	callee,
		const DetlefHandle *	arguments,
		size_t	count,
		DetlefSpan	span,
		DetlefHandle *	out
	)

Create a call expression by copying a callee expression and its argument expressions.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	callee	Borrowed callee expression handle. Not consumed.
	arguments	Borrowed array of argument expression handles, copied into the call. Handles are not consumed.
	count	Number of entries in the supplied array.
	span	Half-open source range in UTF-8 byte offsets.
[out]	out	On success, receives an owned call expression handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_child()

DetlefStatus detlef_expression_child	(	DetlefAccess *	a,
		DetlefHandle	handle,
		size_t	index,
		DetlefHandle *	out
	)

Obtain one expression child by zero-based index. Blocks contain their expressions; calls contain the callee followed by arguments.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed call or block expression handle. Not consumed.
	index	Zero-based child index. For calls, zero selects the callee and later indices select arguments; for blocks, it selects a statement.
[out]	out	On success, receives an owned child expression handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_child_count()

DetlefStatus detlef_expression_child_count	(	DetlefAccess *	a,
		DetlefHandle	handle,
		size_t *	out
	)

Read the number of expression children. A call includes its callee as child zero, followed by its arguments.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed expression handle. Not consumed.
[out]	out	Receives the number of child expressions.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_evaluate()

DetlefStatus detlef_expression_evaluate	(	DetlefAccess *	a,
		DetlefHandle	expr,
		DetlefBool	require_value,
		DetlefHandle *	out
	)

Evaluate an expression. A nonzero require_value rejects void results and descriptors; otherwise the complete evaluation is returned.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	expr	Borrowed expression handle to evaluate. Not consumed.
	require_value	Nonzero requires a runtime value; zero permits void and descriptor evaluations.
[out]	out	On success, receives an owned evaluation handle; with require_value set, the result must be a runtime value. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_identifier()

DetlefStatus detlef_expression_identifier	(	DetlefAccess *	a,
		DetlefSlice	input,
		DetlefSpan	span,
		DetlefHandle *	out
	)

Create an identifier expression with the supplied name and source span.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	input	Borrowed UTF-8 name, without a trailing NUL requirement. Storage may be released after the call.
	span	Half-open source range in UTF-8 byte offsets.
[out]	out	On success, receives an owned identifier expression handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_kind()

DetlefStatus detlef_expression_kind	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefExpressionKind *	out
	)

Read the expression kind, using the DETLEF_EXPR_* constants.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed expression handle. Not consumed.
[out]	out	Receives the expression's DetlefExpressionKind constant.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_literal()

DetlefStatus detlef_expression_literal	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefSpan	span,
		DetlefHandle *	out
	)

Create a literal expression from an integer, float, or string value. Other value types are rejected.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed integer, float, or string value handle to embed as a literal. Not consumed.
	span	Half-open source range in UTF-8 byte offsets.
[out]	out	On success, receives an owned literal expression handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_literal_value()

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

Create a runtime value from an integer, float, or string literal expression. Non- literal nodes are rejected.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed integer, float, or string-literal expression handle. Not consumed.
[out]	out	On success, receives an owned integer, float, or 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_expression_parse()

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

Parse exactly one expression without evaluating it. Empty input and multiple expressions are rejected.

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 expression handle. Release with detlef_handle_release().

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_span()

DetlefStatus detlef_expression_span	(	DetlefAccess *	a,
		DetlefHandle	handle,
		DetlefSpan *	out
	)

Read an expression's half-open source range in UTF-8 byte offsets.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed expression handle. Not consumed.
[out]	out	Receives the expression's half-open source range in UTF-8 byte offsets.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.

detlef_expression_text()

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

Copy the text stored in a string literal or identifier expression. Other node kinds are rejected.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	handle	Borrowed identifier or string-literal expression 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_expression_with_variables()

DetlefStatus detlef_expression_with_variables	(	DetlefAccess *	a,
		DetlefHandle	expr,
		const DetlefNamed *	bindings,
		size_t	count,
		DetlefHandle *	out
	)

Evaluate an expression with temporary variable bindings. Binding values and expression handles are borrowed and not consumed.

Parameters

	a	Borrowed callback access. Must not be freed, saved, or used outside its current callback.
	expr	Borrowed expression handle to evaluate. Not consumed.
	bindings	Borrowed name/value pairs for temporary variables. Each handle must hold a runtime value; handles are not consumed.
	count	Number of entries in the supplied array.
[out]	out	On success, receives an owned evaluation handle for the expression's result. Release with detlef_handle_release() unless transferred as a callback result.

Returns

DETLEF_OK on success; otherwise a DetlefStatus error code.