Crate code_native 

code-native — Helper crate for writing Code language native modules in Rust.

This crate eliminates the boilerplate required to create native .so modules for the Code language. It re-exports all C-ABI types, provides safe value constructors and field-access helpers, and ships the code_module! macro that generates the required #[no_mangle] entry-points (code_module_abi_version + code_module_init).

Quick Start

use code_native::*;

unsafe extern "C" fn handle_add(particle: CodeValue) -> CodeValue {
    let a = read_field_number(&particle, "a");
    let b = read_field_number(&particle, "b");
    code_object(vec![
        code_field("_class", code_string("AddResult")),
        code_field("result", code_number(a + b)),
    ])
}

code_module! {
    vars: [
        "PI" => code_number(3.14159),
    ],
    types: [
        "Add" [("a", "Number"), ("b", "Number")],
    ],
    handlers: [
        "Add" => handle_add,
    ],
    emissions: [],
}

Compile with:

cargo build -p code-native
rustc --edition 2021 --crate-type cdylib \
    --extern code_native=target/debug/libcode_native.rlib \
    -o mymodule.so mymodule.rs

Macros

code_module

Declare an Code native module.

Structs

CodeEmission

Emission declaration exported by a native module.

CodeExportHandler

Exported handler: class name + handler function.

CodeExportType

Exported type declaration.

CodeExportVar

Exported variable: name + constant value.

CodeField

A key-value pair for object fields.

CodeModuleDesc

Top-level module descriptor returned by code_module_init().

CodeTypeField

Field descriptor for type declarations.

CodeValue

A single Code value in C-ABI representation.

Constants

CODE_ABI_VERSION

Current ABI version. Native modules must return this from code_module_abi_version.

CODE_EMIT_TARGET_BASE

Emission target: dispatch to the linking module’s base handlers.

CODE_TAG_ARRAY

CODE_TAG_BOOLEAN

CODE_TAG_NULL

CODE_TAG_NUMBER

CODE_TAG_OBJECT

CODE_TAG_STRING

Functions

code_array

Create an Array value from a Vec of elements.

code_boolean

Create a Boolean value.

code_emit

Emit a particle to the host runtime.

code_emit_exception

Build and emit an Exception particle.

code_emit_log

Build and emit a Log particle.

code_field

Create a single object field. The name is leaked.

code_null

Create a Null value.

code_number

Create a Number value.

code_object

Create an Object value from a Vec of fields.

code_string

Create a String value. The string is leaked into a C-compatible pointer that lives for the remainder of the process — fine for return values and module descriptors.

code_string_raw

Create a String value from a raw *const c_char pointer.

leak_str

Leak a Rust &str into a *const c_char that lives forever.

read_boolean

Read a boolean from an CodeValue, returning false if the tag is wrong.

read_field^⚠

Look up a field by name inside an Object CodeValue.

read_field_bool^⚠

Convenience: read a boolean field from an object by name. Returns false if the field doesn’t exist or isn’t a boolean.

read_field_number^⚠

Convenience: read a number field from an object by name. Returns 0.0 if the field doesn’t exist or isn’t a number.

read_field_str^⚠

Convenience: read a string field from an object by name. Returns "" if the field doesn’t exist or isn’t a string.

read_number

Read a number from an CodeValue, returning 0.0 if the tag is wrong.

read_str^⚠

Read a string from an CodeValue, returning "" if the tag is wrong or the pointer is null.

Type Aliases

CodeEmitFn

Callback signature for native-module emission.

CodeNativeHandlerFn

Native handler signature: fn(particle) -> CodeValue.