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::*;

let mut interp = artichoke_backend::interpreter()?;
let result = interp.eval(b"10 * 10")?;
let result = result.try_convert_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::*;

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_convert_into::<i64>(&mut interp)?;
assert_eq!(result, 12);

Virtual File System and Kernel#require

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

The virtual file system enables applications built with artichoke-backend to require sources that are embedded in the binary without host file system 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:

• Regexp and MatchData, which are backed by regular expressions from the onig and regex crates.
• ENV, which glues Ruby to an environ backend.

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::error::Error;
• pub use crate::error::RubyException;

Modules

• block
• class
• convert
• core
  A “prelude” for users of the artichoke-core crate.
• def
• error
  Error types for Ruby exceptions and unwinding support.
• exception_handler
• extn
• ffi
  Functions for interacting directly with mruby structs from sys.
• fmt
  Utilities for interfacing std::fmt with Artichoke’s exception types.
• gc
• load_path
  Virtual file system.
• method
• module
• prelude
  A “prelude” for users of the artichoke-backend crate.
• release_metadata
  Information about an Artichoke build.
• state
• sys
  Rust bindings for mruby, customized for Artichoke.
• types
• value
  Boxed values on the Ruby interpreter heap.

Macros

• mrb_get_args
  Extract sys::mrb_values from a sys::mrb_state to adapt a C entry point 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.