magnus

Magnus allows you to expose Rust structs and enums as Ruby objects. This enables Ruby to interact with Rust logic seamlessly. You can return these wrapped objects to Ruby or pass them back to Rust, where they are automatically unwrapped to native Rust references.

There are two primary ways to wrap a type:

1. Use the #[magnus::wrap] convenience macro.
2. Implement the magnus::TypedData trait for more customization.

Handling Mutability

Because Ruby's GC manages the memory of the wrapped object, Magnus cannot bind functions using mutable references (&mut T). To allow mutation of fields within a wrapped struct, use the newtype pattern with RefCell.

use magnus::{function, method, prelude::*, Error, Ruby};

#[magnus::wrap(class = "Point")]
struct Point {
    x: isize,
    y: isize,
}

impl Point {
    fn new(x: isize, y: isize) -> Self {
        Self { x, y }
    }

    fn x(&self) -> isize {
        self.x
    }

    fn y(&self) -> isize {
        self.y
    }

    fn distance(&self, other: &Point) -> f64 {
        (((other.x - self.x).pow(2) + (other.y - self.y).pow(2)) as f64).sqrt()
    }
}

#[magnus::init]
fn init(ruby: &Ruby) -> Result<(), Error> {
    let class = ruby.define_class("Point", ruby.class_object())?;
    class.define_singleton_method("new", function!(Point::new, 2))?;
    class.define_method("x", method!(Point::x, 0))?;
    class.define_method("y", method!(Point::y, 0))?;
    class.define_method("distance", method!(Point::distance, 1))?;
    Ok(())
}

Magnus provides automatic type conversion between Rust and Ruby. Conversions follow Ruby's core pattern: if an object is not of the requested type, Magnus will attempt to call the corresponding #to_<type> method (e.g., #to_int, #to_str, #to_sym, #to_ary, #to_hash).

For more granular control, you can use magnus::TryConvert for arguments accepted from Ruby, or magnus::IntoValue for values being returned to Ruby. If you need to bypass automatic conversions (for example, to enforce specific encodings or avoid allocations), use the magnus::Value type and perform manual type checking or conversion.

fn example(ruby: &Ruby, val: magnus::Value) -> Result<(), magnus::Error> {
    // checks value is a String, does not call #to_str
    let r_string = RString::from_value(val)
        .ok_or_else(|| magnus::Error::new(ruby.exception_type_error(), "expected string"))?;
    
    if !r_string.is_utf8_compatible_encoding() {
        return Err(magnus::Error::new(
            ruby.exception_encoding_error(),
            "string must be utf-8",
        ));
    }

    unsafe {
        let s = r_string.as_str()?;
        // ...
    }
    Ok(())
}

You can bind regular Rust functions to Ruby as either global functions or instance methods. Magnus handles automatic type conversion between Ruby and Rust types. If the arguments passed from Ruby are incompatible, Magnus will raise standard Ruby errors like ArgumentError or TypeError.

// Defining a global function (no Ruby `self` argument)
fn fib(n: usize) -> usize {
    match n {
        0 => 0,
        1 | 2 => 1,
        _ => fib(n - 1) + fib(n - 2),
    }
}

#[magnus::init]
fn init(ruby: &magnus::Ruby) -> Result<(), Error> {
    ruby.define_global_function("fib", magnus::function!(fib, 1));
    Ok(())
}

// Defining an instance method (requires a Ruby `self` argument)
fn is_blank(rb_self: String) -> bool {
    !rb_self.contains(|c: char| !c.is_whitespace())
}

#[magnus::init]
fn init(ruby: &magnus::Ruby) -> Result<(), Error> {
    let class = ruby.define_class("String", ruby.class_object())?;
    // 0 indicates the number of arguments excluding `self`
    class.define_method("blank?", magnus::method!(is_blank, 0))?;
    Ok(())
}

To create a Ruby extension, follow these steps:

1. Configure Cargo.toml: Set the crate-type to ["cdylib"] so it builds as a dynamic system library.
2. Define the entry point: Use the #[magnus::init] attribute on a function that takes &magnus::Ruby to define your classes and methods.
3. Build and Package:
   • For development/packaging, use the rb_sys gem and rake-compiler to automate the build process.
   • Create an extconf.rb file in your extension directory that calls create_rust_makefile.
   • Run rake compile to generate the .so or .bundle file.
4. Load in Ruby: Use require_relative to load the compiled extension.

Example Cargo.toml

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

[dependencies]
magnus = "0.8"

Example ext/my_example_gem/extconf.rb

require "mkmf"
require "rb_sys/mkmf"

create_rust_makefile("my_example_gem/my_example_gem")

To allow Ruby to subclass a type wrapped in Magnus, the Rust type must satisfy three requirements:

1. Implement the Default trait.
2. Define an allocator.
3. Define an initializer.

You must also register the allocator and the initializer method in your init function using class.define_alloc_func::<T>() and class.define_method("initialize", ...).

#[derive(Default)]
struct Point {
    x: isize,
    y: isize,
}

#[derive(Default)]
#[wrap(class = "Point")]
struct MutPoint(RefCell<Point>);

impl MutPoint {
    fn initialize(&self, x: isize, y: isize) {
        let mut this = self.0.borrow_mut();
        this.x = x;
        this.y = y;
    }
}

#[magnus::init]
fn init(ruby: &Ruby) -> Result<(), Error> {
    let class = ruby.define_class("Point", ruby.class_object()).unwrap();
    class.define_alloc_func::<MutPoint>();
    class.define_method("initialize", method!(MutPoint::initialize, 2))?;
    Ok(())
}

The Numeric trait provides specialized methods for performing operations on Ruby's Numeric subclasses (like Integer, Float, or Rational) while following Ruby's coercion protocol. This is more robust than a standard funcall because it correctly handles how Ruby objects interact when they are of different numeric types.

There are four primary coercion methods:

• coerce_bin: For binary operators like +, -, *, /.
• coerce_cmp: For comparison operators like <=>.
• coerce_relop: For relationship operators like <=, >, ==.
• coerce_bit: For bitwise operators like |, ^, &.

Note on coerce_cmp: If coercion fails, this method returns nil. To detect a nil result, set the expected return type to Option<U>. Other errors will still return an Err.

All methods return Result<U, Error>, where U is the type you wish to convert the result into.

use magnus::{Error, Numeric, Ruby};

fn example(ruby: &Ruby) -> Result<(), Error> {
    let a = ruby.integer_from_i64(2);
    let b = ruby.float_from_f64(3.5);
    // Using coerce_bin for addition
    let c: Value = a.coerce_bin(b, "+")?;
    let c = Float::from_value(c);
    assert!(c.is_some());
    assert_eq!(c.unwrap().to_f64(), 5.5);

    Ok(())
}