[][src]Crate rosy

Banner

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 Definitions

Result

A simplified form of Result for when exceptions are caught.