[][src]Crate artichoke_backend

artichoke-backend

artichoke-backend crate provides a Ruby interpreter. It currently is 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::{Eval, ValueLike};

let mut interp = artichoke_backend::interpreter().unwrap();
let result = interp.eval(b"10 * 10").unwrap();
let result = result.try_into::<i64>(&interp).unwrap();
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::{Eval, ValueLike};

let mut interp = artichoke_backend::interpreter().unwrap();
let result = interp.eval(b"'ruby funcall'").unwrap();
let result = result.funcall::<usize>(&mut interp, "length", &[], None).unwrap();
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 artichoke_core as core;

Modules

class
convert
def
exception
exception_handler
extn
ffi

Functions for interacting directly with mruby structs from sys.

fs

Virtual filesystem.

gc
method
module
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.

Traits

Convert

Infallible conversion between two types.

ConvertMut

Mutable infallible conversion between two types.

DefineConstant

Deifne constants on an interprter.

Eval

Execute code and retrieve its result.

File

Rust extension hook that can be required.

Globals

Get and set global variables on an interpreter.

Intern

Store and retrieve byte vectors that have the same lifetime as the interpreter.

LoadSources

Load Ruby sources and Rust extensions into an interpreter.

Parser

Manage parser state, active filename context, and line number metadata.

TopSelf

Return a Value-wrapped reference to top self.

TryConvert

Fallible conversions between two types.

TryConvertMut

Mutable fallible conversions between two types.

ValueLike

A boxed Ruby value owned by the interpreter.

Warn

Emit warnings during interpreter execution to stderr.

Functions

interpreter

Create and initialize an Artichoke interpreter.