Env

Env :: # (opaque)

Read and modify the process environment without losing native OS strings.

Variable names and values use OsStr because Unix environment data is not required to be UTF-8. Use var_str! when an application specifically requires text. Paths use basic-cli's byte-preserving Path type.

path_value = Env.var_str!("PATH")?
Stdout.line!("PATH: ${path_value}")?

platform! : () => {
    arch : [X86, X64, ARM, AARCH64, OTHER(Str)],
    os : [LINUX, MACOS, WINDOWS, OTHER(Str)],
}

Report the architecture and operating system for which the host was built.

dict! : () => List((OsStr, OsStr))

Return all environment variables as native name/value pairs.

Native non-Unicode values are preserved. Iteration order is unspecified and may differ between calls or operating systems.

var! : OsStr => Try(OsStr, [VarNotFound(OsStr), EnvErr(IOErr)])

Reads the given environment variable.

Returns Err(VarNotFound(name)) if the variable is not set.

var_str! : OsStr => Try(Str, [VarNotFound(OsStr), EnvErr(IOErr), InvalidStr(U64)])

Reads the given environment variable as a string if its native value is valid text.

cwd! : () => Try(Path, [CwdUnavailable])

Reads the current working directory from the environment.

Returns Err(CwdUnavailable) if the cwd cannot be determined.

set_cwd! : Path => Try({}, [InvalidCwd(IOErr)])

Change the process current working directory.

Returns Err(InvalidCwd(err)) when the path cannot be used as a working directory. The process-wide change remains in effect until changed again.

exe_path! : () => Try(Path, [ExePathUnavailable])

Gets the path to the currently-running executable.

Returns Err(ExePathUnavailable) if the path cannot be determined.

program_name! : () => Try(OsStr, [ProgramNameUnavailable])

Gets the program name supplied by the process launcher as its first argument.

This is conventionally the executable name or path, but launchers may supply another value. Unlike exe_path!, it is returned as an OsStr, preserving the value exactly without treating it as a path. Returns Err(ProgramNameUnavailable) if the launcher supplied no first argument.

create_temp_dir! : () => Try(Path, [TempDirErr(IOErr)])

Atomically create a private directory in the system temporary directory. The caller owns cleanup. Unix directories have mode 0700.

create_temp_dir_with_prefix! : Str => Try(Path, [TempDirErr(IOErr)])

Create a private temporary directory with a filename prefix.

create_temp_dir_in! : Path, Str => Try(Path, [TempDirErr(IOErr)])

Create a private temporary directory under an existing parent directory. Prefixes cannot contain separators, colons, NUL, or be . or ...

with_temp_dir! : (Path => Try(a, err)) => Try(a, [TempDirErr(IOErr), CallbackErr(err), CleanupErr(IOErr, Path), CallbackAndCleanupErr(err, IOErr, Path)])

Run a callback with a private directory and delete the directory afterward. Cleanup is attempted after callback success and failure. If both fail, both errors are returned.

Env.with_temp_dir!(|directory| {
	file = Path.join(directory, "result.txt")
	Path.write_utf8!(file, "temporary data")?
	Path.read_utf8!(file)
})?

temp_dir! : () => Path

Gets the default directory for temporary files.