artichoke_core/
lib.rs

1#![warn(clippy::all, clippy::pedantic, clippy::undocumented_unsafe_blocks)]
2#![allow(
3    clippy::let_underscore_untyped,
4    reason = "https://github.com/rust-lang/rust-clippy/pull/10442#issuecomment-1516570154"
5)]
6#![allow(
7    clippy::question_mark,
8    reason = "https://github.com/rust-lang/rust-clippy/issues/8281"
9)]
10#![allow(clippy::manual_let_else, reason = "manual_let_else was very buggy on release")]
11#![allow(clippy::missing_errors_doc, reason = "A lot of existing code fails this lint")]
12#![allow(
13    clippy::unnecessary_lazy_evaluations,
14    reason = "https://github.com/rust-lang/rust-clippy/issues/8109"
15)]
16#![allow(
17    clippy::module_name_repetitions,
18    reason = "incompatible with how code is organized in private modules"
19)]
20#![cfg_attr(
21    test,
22    allow(clippy::non_ascii_literal, reason = "tests sometimes require UTF-8 string content")
23)]
24#![allow(unknown_lints)]
25#![warn(
26    missing_copy_implementations,
27    missing_debug_implementations,
28    missing_docs,
29    rust_2024_compatibility,
30    trivial_casts,
31    trivial_numeric_casts,
32    unused_qualifications,
33    variant_size_differences
34)]
35#![forbid(unsafe_code)]
36// Enable feature callouts in generated documentation:
37// https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html
38//
39// This approach is borrowed from tokio.
40#![cfg_attr(docsrs, feature(doc_cfg))]
41#![cfg_attr(docsrs, feature(doc_alias))]
42
43//! This crate provides a set of traits that, when implemented, comprise a
44//! complete Ruby interpreter.
45//!
46//! `artichoke-core` is `no_std` + `alloc` with an optional (enabled by default)
47//! `std` feature.
48//!
49//! Interpreters implement the traits in Artichoke Core to indicate which
50//! capabilities they offer. Defining interpreters by their capabilities allows
51//! for interpreter agnostic implementations of Ruby Core and Standard Library.
52//!
53//! # Interpreter APIs
54//!
55//! Artichoke Core defines traits for the following interpreter capabilities:
56//!
57//! - [`ClassRegistry`][core-class-registry]: Define and store class specs for
58//!   Ruby `Class`es.
59//! - [`CoerceToNumeric`][core-coerce-numeric]: Coerce Ruby values to native
60//!   numerics (floats and integers).
61//! - [`Debug`][core-debug]: Provide debugging and `Exception` message support.
62//! - [`DefineConstant`][core-define-constant]: Define global, class, and module
63//!   constants to be arbitrary Ruby [`Value`][core-value]s.
64//! - [`Eval`][core-eval]: Execute Ruby source code on an interpreter from
65//!   various sources.
66//! - [`Globals`][core-globals]: Get, set, and unset interpreter-level global
67//!   variables.
68//! - [`Hash`][core-hash]: Hashing functions such as building hashers.
69//! - [`Intern`][core-intern]: Intern byte strings to a cheap to copy and compare
70//!   symbol type.
71//! - [`Io`][core-io]: External I/O APIs, such as writing to the standard output
72//!   of the current process.
73//! - [`LoadSources`][core-load-sources]: [Require][kernel#require] source code
74//!   from interpreter disk or [`File`][core-file] gems.
75//! - [`ModuleRegistry`][core-module-registry]: Define and store module spec for
76//!   Ruby `Module`s.
77//! - [`Parser`][core-parser]: Manipulate the parser state, e.g. setting the
78//!   current filename.
79//! - [`Prng`][core-prng]: An interpreter-level pseudorandom number generator
80//!   that is the backend for [`Random::DEFAULT`].
81//! - [`Regexp`][core-regexp]: Manipulate interpreter-global `Regexp` state.
82//! - [`ReleaseMetadata`][core-releasemetadata]: Enable interpreters to describe
83//!   themselves.
84//! - [`TopSelf`][core-topself]: Access to the root execution context.
85//! - [`Warn`][core-warn]: Emit warnings.
86//!
87//! [core-class-registry]: class_registry::ClassRegistry
88//! [core-coerce-numeric]: coerce_to_numeric::CoerceToNumeric
89//! [core-convert-module]: convert
90//! [core-debug]: debug::Debug
91//! [core-define-constant]: constant::DefineConstant
92//! [core-value]: value::Value
93//! [core-eval]: eval::Eval
94//! [core-globals]: globals::Globals
95//! [core-hash]: hash::Hash
96//! [core-intern]: intern::Intern
97//! [core-io]: io::Io
98//! [core-load-sources]: load::LoadSources
99//! [core-file]: file::File
100//! [core-module-registry]: module_registry::ModuleRegistry
101//! [core-parser]: parser::Parser
102//! [core-prng]: prng::Prng
103//! [core-regexp]: regexp::Regexp
104//! [core-releasemetadata]: release_metadata::ReleaseMetadata
105//! [core-topself]: top_self::TopSelf
106//! [core-warn]: warn::Warn
107//!
108//! Artichoke Core also describes what capabilities a Ruby
109//! [`Value`](value::Value) must have and how to [convert] between Ruby VM and
110//! Rust types.
111//!
112//! # Examples
113//!
114//! [`artichoke-backend`](https://artichoke.github.io/artichoke/artichoke_backend/)
115//! is one implementation of the `artichoke-core` traits.
116//!
117//! To use all the APIs defined in Artichoke Core, bring the traits into
118//! scope by importing the prelude:
119//!
120//! ```
121//! use artichoke_core::prelude::*;
122//! ```
123//!
124//! # Crate features
125//!
126//! All features are enabled by default:
127//!
128//! - **std**: By default, `artichoke-core` is `no_std` + `alloc`. Enabling
129//!   this feature adds several trait methods that depend on `OsStr` and `Path`
130//!   as well as several implementations of `std::error::Error`.
131//!
132//! [Kernel#require]: https://ruby-doc.org/core-3.1.2/Kernel.html#method-i-require
133//! [`Random::DEFAULT`]: https://ruby-doc.org/core-3.1.2/Random.html#DEFAULT
134//! [`Regexp`]: https://ruby-doc.org/core-3.1.2/Regexp.html#class-Regexp-label-Special+global+variables
135//! [convert]: crate::convert
136
137#![no_std]
138#![doc(html_root_url = "https://artichoke.github.io/artichoke/artichoke_core")]
139#![doc(html_favicon_url = "https://www.artichokeruby.org/favicon-32x32.png")]
140#![doc(html_logo_url = "https://www.artichokeruby.org/artichoke-logo.svg")]
141
142// Ensure code blocks in `README.md` compile
143#[cfg(doctest)]
144#[doc = include_str!("../README.md")]
145mod readme {}
146
147extern crate alloc;
148#[cfg(feature = "std")]
149extern crate std;
150
151pub mod class_registry;
152pub mod coerce_to_numeric;
153pub mod constant;
154pub mod convert;
155pub mod debug;
156pub mod eval;
157pub mod file;
158pub mod globals;
159pub mod hash;
160pub mod intern;
161pub mod io;
162pub mod load;
163pub mod module_registry;
164pub mod parser;
165pub mod prng;
166pub mod regexp;
167pub mod release_metadata;
168pub mod top_self;
169pub mod types;
170pub mod value;
171pub mod warn;
172
173/// A "prelude" for users of the `artichoke-core` crate.
174///
175/// This prelude is similar to the standard library's prelude in that you'll
176/// almost always want to import its entire contents, but unlike the standard
177/// library's prelude, you'll have to do so manually:
178///
179/// ```
180/// use artichoke_core::prelude::*;
181/// ```
182///
183/// The prelude may grow over time as additional items see ubiquitous use.
184pub mod prelude {
185    pub use crate::class_registry::ClassRegistry;
186    pub use crate::coerce_to_numeric::CoerceToNumeric;
187    pub use crate::constant::DefineConstant;
188    pub use crate::convert::{Convert, ConvertMut, TryConvert, TryConvertMut};
189    pub use crate::debug::Debug;
190    pub use crate::eval::Eval;
191    pub use crate::file::File;
192    pub use crate::globals::Globals;
193    pub use crate::hash::Hash;
194    pub use crate::intern::Intern;
195    pub use crate::io::Io;
196    pub use crate::load::LoadSources;
197    pub use crate::module_registry::ModuleRegistry;
198    pub use crate::parser::{IncrementLinenoError, Parser};
199    pub use crate::prng::Prng;
200    pub use crate::regexp::Regexp;
201    pub use crate::release_metadata::ReleaseMetadata;
202    pub use crate::top_self::TopSelf;
203    pub use crate::types::{Ruby, Rust};
204    pub use crate::value::Value;
205    pub use crate::warn::Warn;
206}
artichoke_core/lib.rs

artichoke_core/
lib.rs
