artichoke_backend/extn/core/env/
mod.rs

1//! ENV is a hash-like accessor for environment variables.
2//!
3//! This module implements the [`ENV`] singleton object from Ruby Core.
4//!
5//! In Artichoke, the environment variable store is modeled as a hash map of
6//! byte vector keys and values, e.g. `HashMap<Vec<u8>, Vec<u8>>`. Backends are
7//! expected to convert their internals to this representation in their public
8//! APIs. For this reason, all APIs exposed by ENV backends in this crate are
9//! fallible.
10//!
11//! You can use this object in your application by accessing it directly. As a
12//! Core API, it is globally available:
13//!
14//! ```ruby
15//! ENV["PATH"]
16//! ENV["PS1"] = 'artichoke> '
17//! ```
18//!
19//! [`ENV`]: https://ruby-doc.org/core-3.1.2/ENV.html
20
21use std::borrow::Cow;
22use std::collections::HashMap;
23
24use spinoso_env::{ArgumentError as EnvArgumentError, Error as EnvError, InvalidError};
25
26use crate::extn::prelude::*;
27
28pub(in crate::extn) mod mruby;
29pub(super) mod trampoline;
30
31#[cfg(not(feature = "core-env-system"))]
32type Backend = spinoso_env::Memory;
33#[cfg(feature = "core-env-system")]
34type Backend = spinoso_env::System;
35
36#[derive(Default, Debug)]
37#[allow(missing_copy_implementations, reason = "not all backends implement `Copy`")]
38pub struct Environ(Backend);
39
40impl Environ {
41    #[must_use]
42    pub fn new() -> Self {
43        Self(Backend::new())
44    }
45
46    pub fn get(&self, name: &[u8]) -> Result<Option<Cow<'_, [u8]>>, Error> {
47        let value = self.0.get(name)?;
48        Ok(value)
49    }
50
51    pub fn put(&mut self, name: &[u8], value: Option<&[u8]>) -> Result<(), Error> {
52        self.0.put(name, value)?;
53        Ok(())
54    }
55
56    pub fn to_map(&self) -> Result<HashMap<Vec<u8>, Vec<u8>>, Error> {
57        let map = self.0.to_map()?;
58        Ok(map)
59    }
60}
61
62impl HeapAllocatedData for Environ {
63    const RUBY_TYPE: &'static str = "Artichoke::Environ";
64}
65
66impl From<EnvArgumentError> for Error {
67    fn from(err: EnvArgumentError) -> Self {
68        ArgumentError::from(err.message()).into()
69    }
70}
71
72impl From<InvalidError> for Error {
73    fn from(err: InvalidError) -> Self {
74        // TODO: This should be an `Errno::EINVAL`.
75        SystemCallError::from(err.into_message()).into()
76    }
77}
78
79impl From<EnvError> for Error {
80    fn from(err: EnvError) -> Self {
81        match err {
82            EnvError::Argument(err) => err.into(),
83            EnvError::Invalid(err) => err.into(),
84        }
85    }
86}
artichoke_backend/extn/core/env/mod.rs

artichoke_backend/extn/core/env/
mod.rs
