detlef.h

/* Experimental DETLEF ABI, version 4. MIT licensed.
 * Setup and API navigation: ../../../docs/c/index.md
 */
#ifndef DETLEF_DB1E2997_E00E_4A25_9C4D_34D3080D7039
#define DETLEF_DB1E2997_E00E_4A25_9C4D_34D3080D7039
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ABI storage is fixed-width in C and C++. Doxygen sees the corresponding
 * enums instead so links from signatures lead directly to their values.
 * DETLEF_DOXYGEN is reserved for documentation builds. */
#ifndef DETLEF_DOXYGEN
typedef int32_t DetlefStatus;
typedef uint32_t DetlefBool;
typedef uint32_t DetlefHandleKind;
typedef uint32_t DetlefDescriptorKind;
typedef uint32_t DetlefTypeKind;
typedef uint32_t DetlefPackageSection;
typedef uint32_t DetlefExpressionKind;
typedef uint32_t DetlefTypeRefKind;
#endif
 
/* Runtime ownership and context access */
 
typedef struct DetlefRuntime DetlefRuntime;
 
typedef struct DetlefAccess DetlefAccess;
 
typedef struct DetlefFunctionAccess DetlefFunctionAccess;
 
#ifdef DETLEF_DOXYGEN
enum DetlefStatus {
#else
enum DetlefStatusCode {
#endif
    DETLEF_OK = 0,
 
    DETLEF_ERROR = 1,
 
    DETLEF_INVALID_ARGUMENT = 2,
 
    DETLEF_PANIC = 3,
 
    DETLEF_BUSY = 4,
};
 
/* Text, handles, and source locations */
 
typedef struct DetlefText {
    uint8_t *data;
 
    size_t len;
} DetlefText;
 
typedef struct DetlefSlice {
    const uint8_t *data;
 
    size_t len;
} DetlefSlice;
 
typedef uint64_t DetlefHandle;
 
typedef struct DetlefNamed {
    DetlefSlice name;
 
    DetlefHandle handle;
} DetlefNamed;
 
typedef struct DetlefSpan {
    size_t start;
 
    size_t end;
} DetlefSpan;
 
#ifdef DETLEF_DOXYGEN
enum DetlefHandleKind {
#else
enum DetlefHandleKindCode {
#endif
    DETLEF_VOID = 0,
 
    DETLEF_NONE = 1,
 
    DETLEF_INTEGER = 2,
 
    DETLEF_FLOAT = 3,
 
    DETLEF_BOOLEAN = 4,
 
    DETLEF_STRING = 5,
 
    DETLEF_OBJECT = 6,
 
    DETLEF_TYPE = 7,
 
    DETLEF_PARAMETER = 8,
 
    DETLEF_VARARG = 9,
 
    DETLEF_FIELD = 10,
 
    DETLEF_EXPRESSION = 11,
 
    DETLEF_ENVIRONMENT = 12,
 
    DETLEF_PACKAGE = 13,
 
    DETLEF_TYPE_REF = 14,
};
 
#ifdef DETLEF_DOXYGEN
enum DetlefDescriptorKind {
#else
enum DetlefDescriptorKindCode {
#endif
    DETLEF_DESCRIPTOR_PARAMETER = DETLEF_PARAMETER,
 
    DETLEF_DESCRIPTOR_VARARG = DETLEF_VARARG,
 
    DETLEF_DESCRIPTOR_FIELD = DETLEF_FIELD,
};
 
#ifdef DETLEF_DOXYGEN
enum DetlefBool {
#else
enum DetlefBoolCode {
#endif
    DETLEF_FALSE = 0,
 
    DETLEF_TRUE = 1,
};
 
#ifdef DETLEF_DOXYGEN
enum DetlefTypeKind {
#else
enum DetlefTypeKindCode {
#endif
    DETLEF_TYPE_PRIMITIVE = 0,
 
    DETLEF_TYPE_NONE = 1,
 
    DETLEF_TYPE_OPTIONAL = 2,
 
    DETLEF_TYPE_ARRAY = 3,
 
    DETLEF_TYPE_RECORD_UNDEFINED = 4,
 
    DETLEF_TYPE_RECORD_DEFINED = 5,
};
 
#ifdef DETLEF_DOXYGEN
enum DetlefPackageSection {
#else
enum DetlefPackageSectionCode {
#endif
    DETLEF_PACKAGE_RECORDS = 0,
 
    DETLEF_PACKAGE_BINDINGS = 1,
 
    DETLEF_PACKAGE_FUNCTIONS = 2,
 
    DETLEF_PACKAGE_CONTROLS = 3,
};
 
#ifdef DETLEF_DOXYGEN
enum DetlefExpressionKind {
#else
enum DetlefExpressionKindCode {
#endif
    DETLEF_EXPR_INTEGER = 0,
 
    DETLEF_EXPR_FLOAT = 1,
 
    DETLEF_EXPR_STRING = 2,
 
    DETLEF_EXPR_IDENTIFIER = 3,
 
    DETLEF_EXPR_CALL = 4,
 
    DETLEF_EXPR_BLOCK = 5,
};
 
#ifdef DETLEF_DOXYGEN
enum DetlefTypeRefKind {
#else
enum DetlefTypeRefKindCode {
#endif
    DETLEF_REF_NAMED = 0,
 
    DETLEF_REF_ARRAY = 1,
 
    DETLEF_REF_OPTIONAL = 2,
};
 
/* Callback types */
 
typedef DetlefStatus (*DetlefAccessCallback)(
    void *user_data,
    DetlefAccess *access
);
 
typedef DetlefStatus (*DetlefCallback)(
    void *user_data,
    DetlefAccess *access,
    DetlefHandle *result
);
 
typedef DetlefStatus (*DetlefFunctionCallback)(
    void *user_data,
    DetlefFunctionAccess *access,
    DetlefHandle *result
);
 
typedef void (*DetlefOutput)(
    void *user_data,
    const uint8_t *text,
    size_t len
);
 
typedef DetlefStatus (*DetlefLineInput)(
    void *user_data,
    DetlefSlice *line,
    DetlefBool *present
);
 
/* Runtime lifecycle */
 
uint32_t detlef_abi_version(void);
 
DetlefRuntime *detlef_runtime_new(void);
 
void detlef_runtime_free(DetlefRuntime *runtime);
 
void detlef_text_free(DetlefText text);
 
DetlefStatus detlef_runtime_access(
    DetlefRuntime *runtime,
    DetlefAccessCallback callback,
    void *user_data
);
 
DetlefStatus detlef_last_error(DetlefRuntime *runtime, DetlefText *error);
 
#if !defined(__wasm32__)
DetlefStatus detlef_runtime_load_package(DetlefRuntime *runtime, DetlefSlice archive);
DetlefStatus detlef_native_target(DetlefText *out);
#endif
 
/* Outputs are owned handles/text unless documented otherwise.
 * Per-operation ownership requirements are documented below.
 */
/* BEGIN CONTEXT API */
 
/* Native Function operations */
 
DetlefStatus detlef_function_handle_release(DetlefFunctionAccess *a, DetlefHandle handle);
 
DetlefStatus detlef_function_handle_clone(DetlefFunctionAccess *a, DetlefHandle handle, DetlefHandle *out);
 
DetlefStatus detlef_function_handle_kind(DetlefFunctionAccess *a, DetlefHandle handle, DetlefHandleKind *out);
 
DetlefStatus detlef_function_value_none(DetlefFunctionAccess *a, DetlefHandle *out);
 
DetlefStatus detlef_function_value_integer(DetlefFunctionAccess *a, int64_t value, DetlefHandle *out);
 
DetlefStatus detlef_function_value_float(DetlefFunctionAccess *a, double value, DetlefHandle *out);
 
DetlefStatus detlef_function_value_boolean(DetlefFunctionAccess *a, DetlefBool value, DetlefHandle *out);
 
DetlefStatus detlef_function_value_string(DetlefFunctionAccess *a, DetlefSlice input, DetlefHandle *out);
 
DetlefStatus detlef_function_value_get_integer(DetlefFunctionAccess *a, DetlefHandle handle, int64_t *out);
 
DetlefStatus detlef_function_value_get_float(DetlefFunctionAccess *a, DetlefHandle handle, double *out);
 
DetlefStatus detlef_function_value_get_boolean(DetlefFunctionAccess *a, DetlefHandle handle, DetlefBool *out);
 
DetlefStatus detlef_function_value_get_string(DetlefFunctionAccess *a, DetlefHandle handle, DetlefText *out);
 
DetlefStatus detlef_function_value_to_string(DetlefFunctionAccess *a, DetlefHandle handle, DetlefText *out);
 
DetlefStatus detlef_function_type_of(DetlefFunctionAccess *a, DetlefHandle handle, DetlefHandle *out);
 
DetlefStatus detlef_function_array_create(DetlefFunctionAccess *a, DetlefHandle type_handle, const DetlefHandle *items, size_t count, DetlefHandle *out);
 
DetlefStatus detlef_function_array_length(DetlefFunctionAccess *a, DetlefHandle handle, size_t *out);
 
DetlefStatus detlef_function_array_get(DetlefFunctionAccess *a, DetlefHandle handle, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_function_array_set(DetlefFunctionAccess *a, DetlefHandle handle, size_t index, DetlefHandle new_value);
 
DetlefStatus detlef_function_array_push(DetlefFunctionAccess *a, DetlefHandle handle, DetlefHandle new_value);
 
DetlefStatus detlef_function_array_remove(DetlefFunctionAccess *a, DetlefHandle handle, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_function_record_create(DetlefFunctionAccess *a, DetlefHandle type_handle, const DetlefHandle *items, size_t count, DetlefHandle *out);
 
DetlefStatus detlef_function_record_get(DetlefFunctionAccess *a, DetlefHandle handle, DetlefSlice input, DetlefHandle *out);
 
DetlefStatus detlef_function_record_set(DetlefFunctionAccess *a, DetlefHandle handle, DetlefSlice input, DetlefHandle new_value);
 
DetlefStatus detlef_function_type_lookup(DetlefFunctionAccess *a, DetlefSlice input, DetlefHandle *out);
 
DetlefStatus detlef_function_type_array(DetlefFunctionAccess *a, DetlefHandle inner, DetlefHandle *out);
 
DetlefStatus detlef_function_type_optional(DetlefFunctionAccess *a, DetlefHandle inner, DetlefHandle *out);
 
DetlefStatus detlef_function_type_kind(DetlefFunctionAccess *a, DetlefHandle handle, DetlefTypeKind *out);
 
DetlefStatus detlef_function_type_name(DetlefFunctionAccess *a, DetlefHandle handle, DetlefText *out);
 
DetlefStatus detlef_function_type_inner(DetlefFunctionAccess *a, DetlefHandle handle, DetlefHandle *out);
 
DetlefStatus detlef_function_record_type_field_count(DetlefFunctionAccess *a, DetlefHandle handle, size_t *out);
 
DetlefStatus detlef_function_record_type_field(DetlefFunctionAccess *a, DetlefHandle handle, size_t index, DetlefText *name_out, DetlefHandle *type_out);
 
DetlefStatus detlef_function_argument_count(DetlefFunctionAccess *a, size_t *out);
 
DetlefStatus detlef_function_argument_value(DetlefFunctionAccess *a, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_function_argument_boolean(DetlefFunctionAccess *a, size_t index, DetlefBool *out);
 
DetlefStatus detlef_function_callback_error(DetlefFunctionAccess *a, DetlefSlice message, DetlefSpan span, DetlefBool has_span);
 
DetlefStatus detlef_function_access_error(DetlefFunctionAccess *a, DetlefText *out, DetlefSpan *span, DetlefBool *has_span);
 
/* Value operations */
 
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_type_of(DetlefAccess *a, DetlefHandle handle, DetlefHandle *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);
 
/* Context operations */
 
DetlefStatus detlef_with_protected_values(DetlefAccess *a, const DetlefHandle *handles, size_t count, DetlefAccessCallback callback, void *data);
 
DetlefStatus detlef_register_binding(DetlefAccess *a, DetlefSlice input, DetlefHandle handle);
 
DetlefStatus detlef_execute(DetlefAccess *a, DetlefSlice source, DetlefHandle *out);
 
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_variable_declare(DetlefAccess *a, DetlefSlice input, DetlefHandle type_handle, DetlefHandle initial);
 
DetlefStatus detlef_variable_set(DetlefAccess *a, DetlefSlice input, DetlefHandle handle);
 
DetlefStatus detlef_variable_unset(DetlefAccess *a, DetlefSlice input);
 
DetlefStatus detlef_variable_get(DetlefAccess *a, DetlefSlice input, 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);
 
/* Type operations */
 
DetlefStatus detlef_type_lookup(DetlefAccess *a, DetlefSlice input, DetlefHandle *out);
 
DetlefStatus detlef_type_array(DetlefAccess *a, DetlefHandle inner, DetlefHandle *out);
 
DetlefStatus detlef_type_optional(DetlefAccess *a, DetlefHandle inner, DetlefHandle *out);
 
DetlefStatus detlef_type_kind(DetlefAccess *a, DetlefHandle handle, DetlefTypeKind *out);
 
DetlefStatus detlef_type_name(DetlefAccess *a, DetlefHandle handle, DetlefText *out);
 
DetlefStatus detlef_type_inner(DetlefAccess *a, DetlefHandle handle, DetlefHandle *out);
 
DetlefStatus detlef_record_type_ensure(DetlefAccess *a, DetlefSlice input, DetlefHandle *out, DetlefBool *created);
 
DetlefStatus detlef_record_type_define(DetlefAccess *a, DetlefHandle handle, const DetlefNamed *fields, size_t count);
 
DetlefStatus detlef_record_type_field_count(DetlefAccess *a, DetlefHandle handle, size_t *out);
 
DetlefStatus detlef_record_type_field(DetlefAccess *a, DetlefHandle handle, size_t index, DetlefText *name_out, DetlefHandle *type_out);
 
/* Object operations */
 
DetlefStatus detlef_array_create(DetlefAccess *a, DetlefHandle type_handle, const DetlefHandle *items, size_t count, DetlefHandle *out);
 
DetlefStatus detlef_array_length(DetlefAccess *a, DetlefHandle handle, size_t *out);
 
DetlefStatus detlef_array_get(DetlefAccess *a, DetlefHandle handle, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_array_set(DetlefAccess *a, DetlefHandle handle, size_t index, DetlefHandle new_value);
 
DetlefStatus detlef_array_push(DetlefAccess *a, DetlefHandle handle, DetlefHandle new_value);
 
DetlefStatus detlef_array_remove(DetlefAccess *a, DetlefHandle handle, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_record_create(DetlefAccess *a, DetlefHandle type_handle, const DetlefHandle *items, size_t count, DetlefHandle *out);
 
DetlefStatus detlef_record_get(DetlefAccess *a, DetlefHandle handle, DetlefSlice input, DetlefHandle *out);
 
DetlefStatus detlef_record_set(DetlefAccess *a, DetlefHandle handle, DetlefSlice input, DetlefHandle new_value);
 
/* Callback operations */
 
DetlefStatus detlef_stdlib_install(DetlefAccess *a, DetlefOutput output_callback, void *output_data, DetlefLineInput input_callback, void *input_data);
 
DetlefStatus detlef_argument_count(DetlefAccess *a, size_t *out);
 
DetlefStatus detlef_argument_evaluate(DetlefAccess *a, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_argument_value(DetlefAccess *a, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_argument_boolean(DetlefAccess *a, size_t index, DetlefBool *out);
 
DetlefStatus detlef_argument_expression(DetlefAccess *a, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_argument_identifier(DetlefAccess *a, size_t index, DetlefText *out);
 
DetlefStatus detlef_argument_span(DetlefAccess *a, size_t index, DetlefSpan *out);
 
DetlefStatus detlef_call_span(DetlefAccess *a, DetlefSpan *out);
 
DetlefStatus detlef_callback_error(DetlefAccess *a, DetlefSlice message, DetlefSpan span, DetlefBool has_span);
 
DetlefStatus detlef_access_error(DetlefAccess *a, DetlefText *out, DetlefSpan *span, DetlefBool *has_span);
 
DetlefStatus detlef_register_function(DetlefAccess *a, DetlefSlice input, const DetlefNamed *params, size_t count, const DetlefNamed *vararg, DetlefFunctionCallback callback, void *data);
 
DetlefStatus detlef_register_control(DetlefAccess *a, DetlefSlice input, DetlefCallback callback, void *data);
 
DetlefStatus detlef_register_script_function(DetlefAccess *a, DetlefSlice input, const DetlefNamed *params, size_t count, const DetlefNamed *vararg, DetlefHandle body, DetlefHandle env);
 
/* Package operations */
 
DetlefStatus detlef_package_function_callback(DetlefAccess *a, DetlefHandle handle, size_t index, DetlefFunctionCallback *callback_out, void * *data_out);
 
DetlefStatus detlef_package_control_callback(DetlefAccess *a, DetlefHandle handle, size_t index, DetlefCallback *callback_out, void * *data_out);
 
DetlefStatus detlef_type_ref_resolve(DetlefAccess *a, DetlefHandle handle, DetlefHandle *out);
 
DetlefStatus detlef_type_ref_named(DetlefAccess *a, DetlefSlice input, DetlefHandle *out);
 
DetlefStatus detlef_type_ref_array(DetlefAccess *a, DetlefHandle inner, DetlefHandle *out);
 
DetlefStatus detlef_type_ref_optional(DetlefAccess *a, DetlefHandle inner, DetlefHandle *out);
 
DetlefStatus detlef_type_ref_info(DetlefAccess *a, DetlefHandle handle, DetlefTypeRefKind *kind, DetlefText *name_out, DetlefHandle *inner);
 
DetlefStatus detlef_package_new(DetlefAccess *a, DetlefSlice input, DetlefHandle *out);
 
DetlefStatus detlef_package_name(DetlefAccess *a, DetlefHandle handle, DetlefText *out);
 
DetlefStatus detlef_package_binding(DetlefAccess *a, DetlefHandle handle, DetlefSlice input, DetlefHandle binding);
 
DetlefStatus detlef_package_record(DetlefAccess *a, DetlefHandle handle, DetlefSlice input, const DetlefNamed *fields, size_t count);
 
DetlefStatus detlef_package_function(DetlefAccess *a, DetlefHandle handle, DetlefSlice input, const DetlefNamed *params, size_t count, const DetlefNamed *vararg, DetlefFunctionCallback callback, void *data);
 
DetlefStatus detlef_package_control(DetlefAccess *a, DetlefHandle handle, DetlefSlice input, DetlefCallback callback, void *data);
 
DetlefStatus detlef_package_install(DetlefAccess *a, DetlefHandle handle);
 
DetlefStatus detlef_package_count(DetlefAccess *a, DetlefHandle handle, DetlefPackageSection kind, size_t *out);
 
DetlefStatus detlef_package_entry_name(DetlefAccess *a, DetlefHandle handle, DetlefPackageSection kind, size_t index, DetlefText *out);
 
DetlefStatus detlef_package_binding_get(DetlefAccess *a, DetlefHandle handle, size_t index, DetlefHandle *out);
 
DetlefStatus detlef_package_member_count(DetlefAccess *a, DetlefHandle handle, DetlefPackageSection kind, size_t index, size_t *out, DetlefBool *has_vararg);
 
DetlefStatus detlef_package_member(DetlefAccess *a, DetlefHandle handle, DetlefPackageSection kind, size_t index, size_t member, DetlefText *name_out, DetlefHandle *type_out);
 
/* END CONTEXT API */
 
#ifdef __cplusplus
}
#endif
#endif /* DETLEF_DF9F5A8C_788C_4B37_94E8_0C6D743A9E24 */