Package

std/sys/env

std/env — OS-standard directory lookups, in pure Axle.

Distinct from std/process::env* (which queries the inherited env
block by name). These are conventional locations the user's shell
has agreed on: home, temp, config. Each returns "" if the
platform can't determine the path so callers don't have to catch.

Every lookup here is a read of the inherited environment plus a
string join, so all of it is Axle. The one thing that diverges per
OS is which variables carry the convention, and that is a value —
match target::os, whose arms all typecheck everywhere — rather
than a declaration that exists on one target only.

A variable set to the empty string counts as unset throughout:
it names no directory, so it must not shadow the fallback behind it.
A value is never cut: std/process::getEnv grows its buffer until the
value fits, because a cut path names a different directory and would be
acted on.

Cost: one environment lookup per variable consulted, plus the buffer
getEnv reads it into, and nothing is cached — a program that reads a
directory in a loop should hold the answer itself. None of the five
results carries a trailing separator.

Free functions

Type	Method and description
`string`	__envValue(name : string) : string The value of `name`, or `""` when it is unset, empty, or unreadable. The three collapse on purpose: each leaves the caller with no directory, and `std/env` has no error to carry the difference in. `std/process::hasEnv` is the surface that tells "set to empty" from "absent".
`string`	__envEither(first : string, second : string) : string The value of the first of two variables that is set to something non-empty, `""` when neither is.
`string`	__join(base : string, tail : string) : string `base` and `tail` joined by the host's separator, or `""` when `base` is empty — a relative tail is not a directory the caller can use, and `""` is what every lookup here answers for "the host does not say". A concatenation rather than `Path::join`: `Path` emits `/` on output whatever it was given, and these lookups answer in the host's own spelling, which is what a caller hands back to the OS. The separator itself is `std::sys::fileSeparator`, not a second copy of the same fact.
`string`	homeDir() : string The current user's home directory; `""` if undeterminable.
`string`	__windowsHome() : string `%USERPROFILE%`, else `%HOMEDRIVE%%HOMEPATH%` — the split spelling NT still populates when the joined one is absent. Neither half names a directory on its own, so both must be present for the fallback to answer.
`string`	tempDir() : string The system temporary directory; `""` if undeterminable. On Windows this is the environment order `GetTempPathW` itself consults, minus its last resort of the Windows directory — which an ordinary user cannot write to, so it would be a worse answer than none. Unlike that entry point, the result carries no trailing separator.
`string`	__windowsTempDir() : string `%TMP%`, then `%TEMP%`, then `%USERPROFILE%`.
`string`	__unixTempDir() : string `$TMPDIR`, then the location every unix guarantees.
`string`	configDir() : string Per-user config directory (`%APPDATA%` / `$XDG_CONFIG_HOME` / `~/Library/Application Support`); `""` if undeterminable.
`string`	cacheDir() : string Per-user cache directory following the host convention; `""` if undeterminable.
`string`	dataDir() : string Per-user data directory following the host convention; `""` if undeterminable.
`string`	__xdgDir(variable : string, fallback : string) : string The XDG variable when it names something, the conventional path under `$HOME` otherwise.
`string`	currentExe() : string Absolute path to the currently-running executable. Throws `IOException` when the platform can't resolve it (unlike the directory lookups above, this has no meaningful default). The four refusals are kept apart here — `std/sysinfo::exePath` folds them onto `""` — because this surface throws and so has somewhere to carry the reason. Two of the four are actionable, and a caller told only "it failed" cannot tell which it is looking at.

Method detail

#__envValue

__envValue(name : string) : string

The value of name, or "" when it is unset, empty, or unreadable.

The three collapse on purpose: each leaves the caller with no
directory, and std/env has no error to carry the difference in.
std/process::hasEnv is the surface that tells "set to empty" from
"absent".

Parameters

name environment variable to read

#__envEither

__envEither(first : string, second : string) : string

The value of the first of two variables that is set to something
non-empty, "" when neither is.

Parameters

first variable consulted first

second variable consulted when first names nothing

#__join

__join(base : string, tail : string) : string

base and tail joined by the host's separator, or "" when base
is empty — a relative tail is not a directory the caller can use, and
"" is what every lookup here answers for "the host does not say".

A concatenation rather than Path::join: Path emits / on output
whatever it was given, and these lookups answer in the host's own
spelling, which is what a caller hands back to the OS. The separator
itself is std::sys::fileSeparator, not a second copy of the same
fact.

Parameters

base directory the join starts from

tail path appended below it, already separator-joined

#homeDir

homeDir() : string

The current user's home directory; "" if undeterminable.

#__windowsHome

__windowsHome() : string

%USERPROFILE%, else %HOMEDRIVE%%HOMEPATH% — the split spelling NT
still populates when the joined one is absent. Neither half names a
directory on its own, so both must be present for the fallback to
answer.

#tempDir

tempDir() : string

The system temporary directory; "" if undeterminable.

On Windows this is the environment order GetTempPathW itself
consults, minus its last resort of the Windows directory — which an
ordinary user cannot write to, so it would be a worse answer than
none. Unlike that entry point, the result carries no trailing
separator.

#__windowsTempDir

__windowsTempDir() : string

%TMP%, then %TEMP%, then %USERPROFILE%.

#__unixTempDir

__unixTempDir() : string

$TMPDIR, then the location every unix guarantees.

#configDir

configDir() : string

Per-user config directory (%APPDATA% / $XDG_CONFIG_HOME / ~/Library/Application Support); "" if undeterminable.

#cacheDir

cacheDir() : string

Per-user cache directory following the host convention; "" if undeterminable.

#dataDir

dataDir() : string

Per-user data directory following the host convention; "" if undeterminable.

#__xdgDir

__xdgDir(variable : string, fallback : string) : string

The XDG variable when it names something, the conventional path under
$HOME otherwise.

Parameters

variable XDG environment variable carrying the override

fallback path below $HOME the spec defaults to

#currentExe

currentExe() : string ! IOException

Absolute path to the currently-running executable. Throws
IOException when the platform can't resolve it (unlike the
directory lookups above, this has no meaningful default).

The four refusals are kept apart here — std/sysinfo::exePath folds
them onto "" — because this surface throws and so has somewhere to
carry the reason. Two of the four are actionable, and a caller told
only "it failed" cannot tell which it is looking at.