[−][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.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 |
def_method_unchecked | Defines a method on a |
Structs
AnyException | Any Ruby exception. |
AnyObject | An instance of any Ruby object. |
Array | An instance of Ruby's |
Class | An instance of Ruby's |
Float | An instance of Ruby's |
Hash | An instance of Ruby's |
Integer | An instance of Ruby's |
Module | An instance of Ruby's |
Range | An instance of Ruby's |
RosyObject | An instance of a Ruby object that wraps around Rust data. |
String | An instance of Ruby's |
Symbol | An instance of Ruby's |
SymbolId | An identifier for a |
Constants
RUBY_VERSION | The version of the Ruby library API being used: 2.6. |
Traits
Exception | Some concrete Ruby exception. |
Mixin | |
Object | Some concrete Ruby object. |
Rosy | A Rust type that can be used as a object. |
Functions
protected | Calls |
protected_no_panic⚠ | Calls the non-panicking function |
Type Definitions
Result | A simplified form of
|