Crate spinoso_env

source ·
Expand description

ENV is a hash-like accessor for environment variables.

This module implements the ENV singleton object from Ruby Core.

In Artichoke, the environment variable store is modeled as a hash map of byte vector keys and values, e.g. HashMap<Vec<u8>, Vec<u8>>. Backends are expected to convert their internals to this representation in their public APIs. For this reason, all APIs exposed by ENV backends in this crate are fallible.

You can use this object in your application by accessing it directly. As a Core API, it is globally available:

ENV["PATH"]
ENV["PS1"] = 'artichoke> '

There are two ENV implementations in this crate:

  • Memory, enabled by default, implements an ENV store and accessor on top of a Rust HashMap. This backend does not query or modify the host system.
  • System, enabled when the system-env feature is activated, is a proxy for the system environment and uses platform-specific APIs defined in the Rust Standard Library.

§Examples

Using the in-memory backend allows safely manipulating an emulated environment:

let mut env = Memory::new();
// This does not alter the behavior of the host Rust process.
env.put(b"PATH", None)?;
// `Memory` backends start out empty.
assert_eq!(env.get(b"HOME")?, None);

System backends inherit and mutate the environment from the current Rust process:

const ENV: System = System::new();
ENV.put(b"RUBY", Some(b"Artichoke"))?;
assert!(ENV.get(b"PATH")?.is_some());

§Crate features

This crate requires std, the Rust Standard Library.

All features are enabled by default:

  • system-env - Enable an ENV backend that accesses the host system’s environment variables via the std::env module.

Structs§

  • ArgumentError
    Error that indicates an argument parsing or value logic error occurred.
  • InvalidError
    Error that indicates the underlying platform API returned an error.
  • Memory
    A hash-like accessor for environment variables using a fake in-memory store.
  • System
    A hash-like accessor for environment variables using platform APIs.

Enums§