[−][src]Crate rosy

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.6"

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.6"
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() } {
    std::process::exit(code);
}

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");

let value: usize = rosy::protected(|| unsafe {
    string.call_unchecked("chomp!");
    string.len()
}).unwrap();

assert_eq!(value, 5);

Modules

array	Ruby arrays.
exception	Ruby exceptions.
float	Ruby floating-point numbers.
gc	Ruby's garbage collector.
hash	Ruby hash tables.
integer	Ruby integers.
mixin	Ruby mixins.
object	General functionality over Ruby objects.
prelude	Types and traits that are commonly used within this library.
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.
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 Definitions

Result

A simplified form of Result for when exceptions are caught.