artichoke_core/
globals.rs

1//! Get and set global variables on an interpreter.
2//!
3//! Global variables can be an arbitrary Ruby value. Variable names must start
4//! with `$`.
5
6use alloc::borrow::Cow;
7
8use crate::value::Value;
9
10/// Get and set global variables on an interpreter.
11///
12/// Global variables can be an arbitrary Ruby value. Variable names must start
13/// with `$`.
14pub trait Globals {
15    /// Concrete value type for global variables.
16    type Value: Value;
17
18    /// Concrete error type for failures manipulating global variables.
19    type Error;
20
21    /// Set global variable pointed to by `name` to the given Ruby value.
22    ///
23    /// # Errors
24    ///
25    /// If the name is not a valid global name, an error is returned.
26    ///
27    /// If there is insufficient capacity in the global storage, an error is
28    /// returned.
29    fn set_global_variable<T>(&mut self, name: T, value: &Self::Value) -> Result<(), Self::Error>
30    where
31        T: Into<Cow<'static, [u8]>>;
32
33    /// Unset global variable pointed to by `name`.
34    ///
35    /// Unsetting a global variable removes the name from the global storage
36    /// table. Unset globals resolve to `nil` in the Ruby VM.
37    ///
38    /// Unsetting a global that is currently unset is a no-op.
39    ///
40    /// # Errors
41    ///
42    /// If the name is not a valid global name, an error is returned.
43    fn unset_global_variable<T>(&mut self, name: T) -> Result<(), Self::Error>
44    where
45        T: Into<Cow<'static, [u8]>>;
46
47    /// Get the Ruby value stored in the global variable pointed to by `name`.
48    ///
49    /// # Compatibility Notes
50    ///
51    /// Getting a global that is currently may return `Ok(None)` even through
52    /// a non-existent global resolves to `nil` in the Ruby VM. Consult the
53    /// documentation on implementations of this trait for implementation-defined
54    /// behavior.
55    ///
56    /// # Errors
57    ///
58    /// If the name is not a valid global name, an error is returned.
59    fn get_global_variable<T>(&mut self, name: T) -> Result<Option<Self::Value>, Self::Error>
60    where
61        T: Into<Cow<'static, [u8]>>;
62}
artichoke_core/globals.rs

artichoke_core/
globals.rs
