Crate rosy

Expand description

This crate provides high-level bindings to the Ruby virtual machine.

§Installation

This crate is available on crates.io and can be used by adding the following to your project’s Cargo.toml:

[dependencies]
rosy = "0.0.9"

Rosy has functionality that is only available for certain Ruby versions. The following features can currently be enabled:

ruby_2_6

For example:

[dependencies.rosy]
version = "0.0.9"
features = ["ruby_2_6"]

Finally add this to your crate root (main.rs or lib.rs):

extern crate rosy;

§Initialization

The Ruby virtual machine is initialized via vm::init:

rosy::vm::init().expect("Failed to initialize Ruby");

This should be called once by the thread expected to be associated with Ruby. All mutations to Ruby objects from there on are only safe from that same thread since the VM is not known to be thread-safe.

§Cleaning Up

When done with the Ruby VM, one should call vm::destroy, which will return a status code appropriate for exiting the program.

if let Err(code) = unsafe { rosy::vm::destroy() } {
    code.exit_process();
}

§Catching Ruby Exceptions

With Rosy, your Rust code can be protected from Ruby exceptions when calling unchecked functions that may throw.

Not catching an exception from Rust will result in a segmentation fault at best. As a result, every function that throws an exception is annotated as unsafe in Rust-land. If a function is found to not uphold this invariant, please report it at issue #4 or file a pull request to fix this.

use rosy::{Object, String};

let string = String::from("hello\r\n");

rosy::protected(|| unsafe {
    string.call("chomp!");
}).unwrap();

assert_eq!(string.len(), 5);

Modules§

array: Ruby arrays.
exception: Ruby exceptions.
gc: Ruby’s garbage collector.
hash: Ruby hash tables.
meta: Metadata for Ruby.
mixin: Ruby mixins.
num: Ruby numbers.
object: General functionality over Ruby objects.
prelude: Types and traits that are commonly used within this library.
range: Ruby ranges.
string: Ruby strings.
symbol: Ruby symbols.
vm: Interacting with the Ruby VM directly.

Macros§

def_method: Defines a method on a Class instance in a simple manner.
def_method_unchecked: Defines a method on a Class instance in a simple manner, without checking for exceptions.

Structs§

AnyException: Any Ruby exception.
AnyObject: An instance of any Ruby object.
Array: An instance of Ruby’s Array class.
Class: An instance of Ruby’s Class type.
Float: An instance of Ruby’s Float class.
Hash: An instance of Ruby’s Hash class.
Integer: An instance of Ruby’s Integer class.
Module: An instance of Ruby’s Module type.
Range: An instance of Ruby’s Range type.
RosyObject: An instance of a Ruby object that wraps around Rust data.
String: An instance of Ruby’s String class.
Symbol: An instance of Ruby’s Symbol class.
SymbolId: An identifier for a Symbol.

Constants§

RUBY_VERSION: The version of the Ruby library API being used: 2.6.

Traits§

Exception: Some concrete Ruby exception.
Mixin: A type that supports mixins (see Class and Module).
Object: Some concrete Ruby object.
Rosy: A Rust type that can be used as a object.

Functions§

protected: Calls f and returns its output or an exception if one is raised in f.
protected_no_panic^⚠: Calls the non-panicking function f and returns its output or an exception if one is raised in f.

Type Aliases§

Result: A simplified form of Result for when exceptions are caught.

Crate rosyCopy item path