Crate artichoke_core

source ·
Expand description

This crate provides a set of traits that, when implemented, comprise a complete Ruby interpreter.

artichoke-core is no_std + alloc with an optional (enabled by default) std feature.

Interpreters implement the traits in Artichoke Core to indicate which capabilities they offer. Defining interpreters by their capabilities allows for interpreter agnostic implementations of Ruby Core and Standard Library.

Interpreter APIs

Artichoke Core defines traits for the following interpreter capabilities:

  • ClassRegistry: Define and store class specs for Ruby Classes.
  • CoerceToNumeric: Coerce Ruby values to native numerics (floats and integers).
  • Debug: Provide debugging and Exception message support.
  • DefineConstant: Define global, class, and module constants to be arbitrary Ruby Values.
  • Eval: Execute Ruby source code on an interpreter from various sources.
  • Globals: Get, set, and unset interpreter-level global variables.
  • Hash: Hashing functions such as building hashers.
  • Intern: Intern byte strings to a cheap to copy and compare symbol type.
  • Io: External I/O APIs, such as writing to the standard output of the current process.
  • LoadSources: Require source code from interpreter disk or File gems.
  • ModuleRegistry: Define and store module spec for Ruby Modules.
  • Parser: Manipulate the parser state, e.g. setting the current filename.
  • Prng: An interpreter-level pseudorandom number generator that is the backend for Random::DEFAULT.
  • Regexp: Manipulate [Regexp][regexp-globals] global state.
  • ReleaseMetadata: Enable interpreters to describe themselves.
  • TopSelf: Access to the root execution context.
  • Warn: Emit warnings.

Artichoke Core also describes what capabilities a Ruby Value must have and how to convert between Ruby VM and Rust types.

Examples

artichoke-backend is one implementation of the artichoke-core traits.

To use all the APIs defined in Artichoke Core, bring the traits into scope by importing the prelude:

use artichoke_core::prelude::*;

Crate features

All features are enabled by default:

  • std: By default, artichoke-core is no_std + alloc. Enabling this feature adds several trait methods that depend on OsStr and Path as well as several implementations of std::error::Error.

Modules

  • class_registry
    Define and store class specs on an interpreter.
  • coerce_to_numeric
    Coerce Ruby values to native numerics.
  • constant
    Define constants on an interpreter.
  • convert
    Convert between Rust and Ruby objects.
  • debug
    Routines for debugging and printing exception messages.
  • eval
    Run code on an Artichoke interpreter.
  • file
    File-backed Rust extensions for the Artichoke VM.
  • globals
    Get and set global variables on an interpreter.
  • hash
    Build hashers and hash values.
  • intern
    Intern Symbols on an interpreter.
  • io
    I/O read and write APIs.
  • load
    Load Ruby and Rust sources into the VM.
  • module_registry
    Define and store module specs on an interpreter.
  • parser
    Parse code on an Artichoke interpreter.
  • prelude
    A “prelude” for users of the artichoke-core crate.
  • prng
    Interpreter global pseudorandom number generator.
  • regexp
    Track Regexp global state.
  • release_metadata
    Information about an Artichoke build.
  • top_self
    Expose the global context, called top self, to the interpreter.
  • types
    Ruby and Rust type mappings.
  • value
    Types that implement Value can be represented in the Artichoke VM.
  • warn
    Emit warnings during interpreter execution.