Home › env

Module env

env
Stability: unstable, and closer to freezing than most of this group: the shapes are Rust's `std::env` and are not expected to move. What is open is error reporting. `args`, `env`, `cwd` and the user-directory functions report failure in three different ways across this module — some return an `Option`, some a `Result(_, IoError)`, some throw — because they were added at different times, and D1 wants one answer per kind of failure. Freezing means picking it, which will change a signature or two. The user-directory functions (`home_dir`, `config_dir`, `cache_dir`, `temp_dir`) also encode a per-platform convention (XDG on Linux, `~/Library` on macOS, `%APPDATA%` on Windows). Those conventions are deliberate and documented per function; a caller that needs a different one should build the path itself rather than expect a knob here. — stable modules only change additively; this one may still change.

Process environment: command-line arguments, environment variables, current working directory, and platform-aware user directories.

Mirrors the layout of Rust's std::env. Platform/architecture detection and child-process spawning live in std/process.

Stability

unstable, and closer to freezing than most of this group: the shapes are Rust's std::env and are not expected to move. What is open is error reporting. args, env, cwd and the user-directory functions report failure in three different ways across this module — some return an Option, some a Result(_, IoError), some throw — because they were added at different times, and D1 wants one answer per kind of failure. Freezing means picking it, which will change a signature or two.

The user-directory functions (home_dir, config_dir, cache_dir, temp_dir) also encode a per-platform convention (XDG on Linux, ~/Library on macOS, %APPDATA% on Windows). Those conventions are deliberate and documented per function; a caller that needs a different one should build the path itself rather than expect a knob here.

Functions

args function
fn() -> ArrayList(String)

Get command-line arguments as an ArrayList(String). The first element is the program name.

Returns: ArrayList(String)

cwd function
fn() -> Result(Path, IoError)

Get the current working directory as a Path.

Mirrors Rust's std::env::current_dir: Err(IoError) on failure, with the real OS reason (errno on POSIX, GetLastError() on Windows) rather than a prose message.

Returns: Result(Path, IoError)

current_exe function
fn() -> Result(Path, IoError)

Get the absolute path of the current executable. The path is symlink-resolved on macOS/Linux (via /proc/self/exe on Linux, _NSGetExecutablePath + realpath on macOS) and comes from GetModuleFileNameW on Windows.

Mirrors Rust's std::env::current_exe: Err(IoError) on failure, and Err(IoError.NotSupported) on platforms with no way to discover the executable (wasm).

Returns: Result(Path, IoError)

chdir function
fn(path : Path) -> Result(unit, IoError)

Change the current working directory to path.

Mirrors Rust's std::env::set_current_dir: Ok(()) on success, or Err(IoError) carrying the real OS reason — e.g. IoError.NotFound when path does not exist.

Parameters

NameTypeNotes
pathPath

Returns: Result(unit, IoError)

home_dir function
fn() -> Option(String)

Return the current user's home directory, or .None if unavailable.

Returns: Option(String)

config_dir function
fn() -> Option(String)

Return the user-specific configuration directory.

  • Linux/macOS: $XDG_CONFIG_HOME or $HOME/.config
  • Windows: %APPDATA%

Returns: Option(String)

cache_dir function
fn() -> Option(String)

Return the user-specific cache directory.

  • Linux: $XDG_CACHE_HOME or $HOME/.cache
  • macOS: $HOME/Library/Caches
  • Windows: %LOCALAPPDATA%

Returns: Option(String)

temp_dir function
fn() -> String

Return the system temporary directory.

  • Linux/macOS: $TMPDIR, else /tmp (POSIX honors TMPDIR; on macOS it is a per-user confined directory — plans/archive/STD_API_AUDIT.md D8)
  • Windows: %TEMP%, then %TMP%, else C:\Temp

Returns: String

Constants

env constant module (get : fn(generic(K) name : K : (ToString)) -> Option(String), set : fn(generic(K, V) name : K : (ToString), value : V : (ToString), overwrite : bool) -> bool, remove : fn(generic(K) name : K : (ToString)) -> bool, vars : fn() -> ArrayList(IterPair(String, String)))

Environment variable access and manipulation.

Value: source_namespace_yo_id_41984(get: <fn(name)>, set: <fn(name, value, overwrite)>, remove: <fn(name)>, vars: <fn()>)