ring-lang-rs

Rust bindings for the Ring programming language.

Use Cases

• Write Ring extensions in Rust - Create native extensions with Rust's safety and performance
• Wrap Rust crates - Expose any Rust library to Ring applications
• Performance-critical code - Offload CPU-intensive work (parsing, compression, crypto, physics)
• System integration - Access OS APIs, hardware, or FFI libraries not available in Ring

Supported Platforms

Linux, macOS, Windows, FreeBSD

Requirements

• Rust (stable)
• Ring language installed

Installation

Add to your Cargo.toml:

[lib]
crate-type = ["cdylib"]

[dependencies]
ring-lang-rs = "0.1"

Or clone and use locally:

git clone https://github.com/ysdragon/ring-lang-rs
cd ring-lang-rs
cargo build --release

Environment Variables

Optional: Set RING (or ring) to your Ring installation directory:

# Linux/macOS
export RING=/path/to/ring

# Windows (PowerShell)
$env:RING = "C:\path\to\ring"

# Windows (CMD)
set RING=C:\path\to\ring

If not set, the system's libring will be used.

Quick Start

See examples/basic/ for a complete working example:

cd examples/basic
cargo build --release
ring test.ring

Usage

Basic Function

use ring_lang_rs::*;

ring_func!(ring_hello, |p| {
    ring_check_paracount!(p, 0);
    ring_ret_string!(p, "Hello from Rust!");
});

ring_libinit! {
    b"rust_hello\0" => ring_hello,
}

Working with Numbers

ring_func!(ring_add, |p| {
    ring_check_paracount!(p, 2);
    ring_check_number!(p, 1);
    ring_check_number!(p, 2);

    let a = ring_get_number!(p, 1);
    let b = ring_get_number!(p, 2);

    ring_ret_number!(p, a + b);
});

Working with Strings

ring_func!(ring_greet, |p| {
    ring_check_paracount!(p, 1);
    ring_check_string!(p, 1);

    let name = ring_get_string!(p, 1);
    let greeting = format!("Hello, {}!", name);

    ring_ret_string!(p, &greeting);
});

Working with Lists

ring_func!(ring_create_list, |p| {
    let list = ring_new_list!(p);
    ring_list_addint(list, 1);
    ring_list_addint(list, 2);
    ring_list_adddouble(list, 3.14);
    ring_list_addstring(list, b"hello\0");

    ring_ret_list!(p, list);
});

ring_func!(ring_sum_list, |p| {
    ring_check_paracount!(p, 1);
    ring_check_list!(p, 1);

    let list = ring_get_list!(p, 1);
    let size = ring_list_getsize(list);
    let mut sum = 0.0;

    for i in 1..=size {
        if ring_list_isnumber(list, i) {
            sum += ring_list_getdouble(list, i);
        }
    }

    ring_ret_number!(p, sum);
});

Working with C Pointers (Rust Structs)

use std::ffi::c_void;

const MY_TYPE: &[u8] = b"MyStruct\0";

struct MyStruct {
    value: i32,
}

ring_func!(ring_create_struct, |p| {
    let my_struct = Box::new(MyStruct { value: 42 });
    let ptr = Box::into_raw(my_struct);

    ring_ret_cpointer!(p, ptr, MY_TYPE);
});

ring_func!(ring_get_value, |p| {
    ring_check_paracount!(p, 1);
    ring_check_cpointer!(p, 1);

    if let Some(s) = ring_get_pointer!(p, 1, MyStruct, MY_TYPE) {
        ring_ret_number!(p, s.value);
    } else {
        ring_error!(p, "Invalid pointer");
    }
});

Managed Pointers (Auto-freed by Ring GC)

extern "C" fn free_my_struct(_state: *mut c_void, ptr: *mut c_void) {
    if !ptr.is_null() {
        unsafe { let _ = Box::from_raw(ptr as *mut MyStruct); }
    }
}

ring_func!(ring_create_managed, |p| {
    let my_struct = Box::new(MyStruct { value: 42 });
    let ptr = Box::into_raw(my_struct);

    ring_ret_managed_cpointer!(p, ptr, MY_TYPE, free_my_struct);
});

Available Macros

Module Structure

API Coverage

186 / 456 functions (41%) of Ring's public C API.

We focused on functions useful for writing extensions. ringapi.h has many type-check macros (bound separately). rlist.h and vmgc.h have _gc variants we skip.

License

This project is licensed under the MIT License - see the LICENSE file for details.