[][src]Crate artichoke_backend

artichoke-backend

artichoke-backend crate provides a Ruby interpreter. It is currently implemented with mruby bindings exported by the sys module.

Execute Ruby Code

artichoke-backend crate exposes several mechanisms for executing Ruby code on the interpreter.

Evaling Source Code

The artichoke-backend interpreter implements Eval from artichoke-core.

use artichoke_backend::prelude::core::*;
use artichoke_backend::prelude::*;

let mut interp = artichoke_backend::interpreter()?;
let result = interp.eval(b"10 * 10")?;
let result = result.try_into::<i64>(&interp)?;
assert_eq!(result, 100);

Calling Functions on Ruby Objects

Values returned by the artichoke-backend interpreter implement Value from artichoke-core, which enables calling Ruby functions from Rust.

use artichoke_backend::prelude::core::*;
use artichoke_backend::prelude::*;

let mut interp = artichoke_backend::interpreter()?;
let result = interp.eval(b"'ruby funcall'")?;
let result = result.funcall(&mut interp, "length", &[], None)?;
let result = result.try_into::<i64>(&mut interp)?;
assert_eq!(result, 12);

Virtual Filesystem and Kernel#require

The artichoke-backend interpreter includes an in-memory virtual filesystem. The filesystem stores Ruby sources and Rust extension functions that are similar to MRI C extensions.

The virtual filesystem enables applications built with artichoke-backend to require sources that are embedded in the binary without host filesystem access.

Embed Rust Types in Ruby Values

artichoke-backend exposes a concept similar to data-typed values in MRI and mruby.

When Rust types implement a special trait, they can be embedded in a Ruby Value and passed through the Ruby VM as a Ruby object. Classes defined in this way can define methods in Rust or Ruby.

Examples of these types include:

Converters Between Ruby and Rust Types

The convert module provides implementations for conversions between boxed Ruby values and native Rust types like i64 and HashMap<String, Option<Vec<u8>>> using an artichoke-backend interpreter.

Re-exports

pub use crate::exception::Exception;
pub use crate::exception::RubyException;

Modules

block
class
class_registry
convert
core

A "prelude" for users of the artichoke-core crate.

def
exception
exception_handler
extn
ffi

Functions for interacting directly with mruby structs from sys.

fs

Virtual filesystem.

gc
method
module
module_registry
prelude

A "prelude" for users of the artichoke-backend crate.

release_metadata
state
string

Utilities for working with Ruby Strings.

sys

Rust bindings for mruby, customized for Artichoke.

types
value

Macros

mrb_get_args

Extract sys::mrb_values from a sys::mrb_state to adapt a C entrypoint to a Rust implementation of a Ruby function.

unwrap_interpreter

Extract an Artichoke instance from the userdata on a sys::mrb_state.

Structs

Artichoke

Interpreter instance.

Guard

Interpreter guard that prepares an Artichoke to re-enter an FFI boundary.

Functions

interpreter

Create and initialize an Artichoke interpreter.

interpreter_with_config

Create and initialize an Artichoke interpreter with build metadata.