ring-lang-rs

Rust bindings for the Ring programming language.

Use Cases

1. Write Ring extensions in Rust - Create native extensions with Rust's safety and performance
2. Embed Ring in Rust applications - Run Ring scripts from your Rust programs
3. Wrap Rust crates for Ring - Expose any Rust library to Ring applications

How It Works

flowchart LR
    subgraph ext["<b>Extensions</b>"]
        direction LR
        A["Ring Program<br/><code>.ring</code>"] -->|"loadlib()"| B["Rust Extension<br/><code>.dll/.so/.dylib</code>"]
        B -->|"return values"| A
    end
    
    subgraph emb["<b>Embedding</b>"]
        direction LR
        C["Rust Application<br/><code>binary</code>"] -->|"ring_state_*()"| D["Ring VM<br/><code>embedded</code>"]
        D -->|"results"| C
    end

Code Generation Tools

Two approaches to generate Ring extensions from Rust code:

Proc Macro (ring_extension!) - Zero config, just cargo build:

ring_extension! {
    prefix: "mylib";
    pub fn add(a: i32, b: i32) -> i32 { a + b }
}

Ring Script (parsec.ring) - Uses .rf config files:

ring parsec.ring mylib.rf src/lib.rs mylib_classes.ring

Both generate the same Ring-callable functions. See each README for details.

Using Extensions

If you have a Rust extension (.dll/.so/.dylib), using it is simple:

# Load the library (OS-specific)
if iswindows()
    loadlib("myextension.dll")
elseif ismacosx()
    loadlib("libmyextension.dylib")
else
    loadlib("libmyextension.so")
ok

# Call functions just like native Ring functions
? rust_hello()           # Hello from Rust!
? rust_add(10, 20)       # 30
? rust_greet("Ring")     # Hello, Ring!

That's it! No Rust knowledge required.

Creating Extensions

The rest of this document covers how to create Ring extensions in Rust or embed Ring in Rust applications.

Supported Platforms

Other Unix-like systems (OpenBSD, NetBSD, DragonFly BSD, Solaris, etc.) are supported via the generic Unix build path. Any target supported by Rust's std and LLVM should work.

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

Extension example:

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

Embedding example:

cd examples/embed
cargo build --release
./target/release/embed_ring        # Linux/macOS
.\target\release\embed_ring.exe    # Windows

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

188 / 386 functions (48%) of Ring's public C API.

We focused on functions useful for writing extensions. rlist.h and vmgc.h have _gc variants we skip.

Embedding Ring

To embed Ring in a Rust application:

Cargo.toml:

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

Running Code

use ring_lang_rs::*;

fn main() {
    // Run code from string (VM must be initialized)
    let state = ring_state_init();
    ring_state_runcode_str(state, r#"? "Hello from Ring!""#);
    ring_state_delete(state);

    // Run code from file (compiles from scratch)
    let state = ring_state_new();
    ring_state_runfile_str(state, "script.ring");
    ring_state_delete(state);
}

Sharing Variables

use ring_lang_rs::*;

fn main() {
    let state = ring_state_init();

    // Rust -> Ring: Pass data via runcode
    let value = 42.5;
    ring_state_runcode_str(state, &format!("x = {}", value));

    // Ring computes
    ring_state_runcode_str(state, "result = x * 2");

    // Ring -> Rust: Read variable back
    let var = ring_state_findvar_str(state, "result");
    if !var.is_null() {
        let result = ring_list_getdouble(var, RING_VAR_VALUE);
        println!("result = {}", result); // 85
    }

    ring_state_delete(state);
}

API Reference

See examples/embed/ for a complete working example.

License

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