The Env builtin library gives Adesh access to environment variables, user/system directories, platform and process metadata, and command-line arguments — all through a single Env namespace. Directory and executable queries return Path instances so they chain fluently with the Path and FS libraries, and a runtime "environment" layer backs .env file support.
Namespace
| Name | What it provides |
|---|
Env | The namespace: environment variables, .env files, directories, platform info, and command-line args |
Importing the library
Every method is static — there is no Env() instance.
import Env;
let home = Env.home();
let config = Env.home().join(".adesh").join("config.toml");
if Env.contains("JAVA_HOME") {
print("Java installed: " + Env.get("JAVA_HOME"));
}
print("OS: " + Env.os());
print("Args: " + str(Env.arguments()));
Environment Variables
| Method | Description | Returns |
|---|
get(key) | Value of key, or null if not set | string | null |
getOrDefault(key, default = null) | Value of key, else default | string |
set(key, value) | Set or update key | void |
setIfAbsent(key, value) | Set key only when missing; true if set | boolean |
remove(key) / unset(key) | Remove key (aliases) | void |
contains(key) / has(key) / exists(key) | Whether key is set (aliases) | boolean |
clear() | Clear all runtime-set variables | void |
variables() / environ() / toObject() | All key-value pairs as an object (aliases) | object |
keys() | All variable names | array |
values() | All variable values | array |
count() | Number of visible variables | int |
getMany(keys) | Object with only the requested keys that exist | object |
filter(prefix) | Object of variables whose key starts with prefix | object |
filterKeys(prefix) | Array of variable names starting with prefix | array |
import Env;
print("PATH: " + str(Env.get("PATH")));
if Env.contains("JAVA_HOME") {
print("Java installed at: " + str(Env.get("JAVA_HOME")));
} else {
print("JAVA_HOME environment variable is not set.");
}
Env.set("APP_MODE", "production");
print(Env.get("APP_MODE"));
print(Env.getOrDefault("APP_MODE", "dev"));
Env.remove("APP_MODE");
print(Env.get("APP_MODE"));
import Env;
Env.set("DEMO_MODE", "test");
Env.set("DEMO_REGION", "us-east");
print(Env.getMany(["DEMO_MODE", "DEMO_REGION", "NOPE"]));
print(Env.filter("DEMO_"));
print(Env.filterKeys("DEMO_"));
print(Env.setIfAbsent("DEMO_MODE", "x"));
print(Env.setIfAbsent("DEMO_NEW", "x"));
.env File Support
The runtime keeps a separate "runtime environment" layer. Env.load populates it from a .env file, and Env.get consults runtime-loaded values first, then the OS.
| Method | Description | Returns |
|---|
fromFile(path = ".env") | Read a .env file into an object | object |
getFromFile(key, default = null, path = ".env") | Read a single key from a .env file | string |
load(path = ".env", overwrite = false) / loadFromFile(...) | Load a .env file into the runtime env (aliases) | int |
runtimeLoad(objectOrPath, overwrite = false) | Load variables from an object or file into the runtime env | int |
runtimeVariables() | All runtime-stored variables | object |
runtimeGet(key) | Value from the runtime env | string |
runtimeHas(key) | Whether a runtime variable exists | boolean |
import Env;
let data = Env.fromFile(".env");
for k in data {
print(k + " = " + str(data[k]));
}
let n = Env.runtimeLoad({
"MY_APP_HOST": "127.0.0.1",
"MY_APP_PORT": "8080"
});
print("Loaded " + str(n) + " variable(s)");
print(Env.runtimeGet("MY_APP_HOST"));
print(Env.runtimeHas("MY_APP_PORT"));
Standard Directories
All directory methods return a Path instance, so they chain with Path and FS.
| Method | Returns the… | Returns |
|---|
currentDirectory() | Current working directory | Path |
setCurrentDirectory(path) | — (changes the working directory) | void |
home() | User home directory | Path |
desktop() / documents() / downloads() | Desktop / Documents / Downloads | Path |
pictures() / music() / videos() | Pictures / Music / Videos | Path |
public() | Public shared directory | Path |
tempDirectory() | System temp directory | Path |
userCacheDirectory() | User cache dir (e.g. AppData/Local) | Path |
userConfigDirectory() | User config dir (e.g. AppData/Roaming) | Path |
import Env;
import FS;
let config = Env.home()
.join(".adesh")
.join("config.toml");
print("Config Path: " + config.toString());
print("Config Parent: " + config.parent().toString());
print("FS Exists Check: " + str(FS.exists(config)));
Executable
| Method | Returns |
|---|
executable() | Absolute path to the running script/binary as Path |
executableDirectory() | Parent directory of the running script/binary as Path |
executableName() | File name of the running script/binary |
import Env;
let exePath = Env.executable();
print("Executable Path: " + exePath.toString());
let exeDir = Env.executableDirectory();
print("Executable Parent Directory: " + exeDir.toString());
| Method | Description |
|---|
os() / platform() | OS identifier: "windows", "linux", "macos", "wasm" |
architecture() / arch() | CPU architecture: "x86_64", "aarch64", "x86", "wasm32" |
hostname() / username() / userId() / shell() | System identity |
processId() / parentProcessId() / processTitle() | Process metadata |
osType() / osVersion() / osFamily() / osRelease() / osDescription() | OS name, version, family, release, and description |
cpuCount() / pagesize() / endianness() / machineId() | Hardware metadata |
totalMemory() / freeMemory() / usedMemory() | Memory in bytes |
memoryUsage() | { total, free, used, percent } |
uptime() / systemUptime() | Process / system uptime in seconds |
loadAverage() | Load averages [1m, 5m, 15m] |
userInfo() | { username, userId, userGid, home, shell } |
systemInfo() | One object with all of the above |
commandLine() | Full command line string |
import Env;
print("OS: " + Env.os());
print("Arch: " + Env.architecture());
print("Hostname: " + Env.hostname());
print("PID: " + str(Env.processId()));
let mem = Env.memoryUsage();
print("Total: " + str(mem.total) + " bytes");
print("Free: " + str(mem.free) + " bytes");
print("Used: " + str(mem.used) + " bytes");
print("Used %: " + str(mem.percent));
The systemInfo() object exposes every field at once — os, osType, osVersion, osFamily, osRelease, osDescription, arch, platform, hostname, username, userId, userGid, pid, ppid, shell, cpuCount, totalMemory, freeMemory, processUptime, systemUptime, loadavg, endianness, pagesize, processTitle, machineId, userHome, userCache, userConfig, tempDir, currentDir, and currentExe.
| Method | Returns true on… |
|---|
isWindows() | Windows |
isLinux() | Linux |
isMacOS() | macOS |
isWasm() | WebAssembly |
isUnix() | Any non-Windows, non-WASM platform (Linux/macOS) |
Runtime & Separators
| Method | Description |
|---|
languageVersion() / compilerVersion() / runtimeVersion() | Version strings ("1.0.0") |
version() | { language, compiler, runtime } |
pathSeparator() / pathListSeparator() | ";" on Windows, ":" on Unix |
fileSeparator() | "\\" on Windows, "/" on Unix |
lineSeparator() / eol() | "\r\n" on Windows, "\n" on Unix |
Command-Line Arguments
| Method | Description | Returns |
|---|
arguments() / args() / argv() | Command-line arguments (excluding the executable) | array |
argumentCount() / argc() / argsCount() | Count of arguments | int |
arg(index) | 0-based argument; null when out of bounds | string | null |
argsSlice(start) | Arguments from start onward | array |
argsJoin(sep = " ") | Join all arguments with sep | string |
argsIndexOf(value) | Index of first argument equal to value, or -1 | int |
execName() | Executable name | string |
parseArgs() | Parse into { flags, positionals } | object |
argGet(name, default = null) | Value of parsed flag name | string | null |
argHas(name) | Whether parsed flag name is present | boolean |
import Env;
print("Executable name: " + Env.executableName());
print("Argument count: " + str(Env.argumentCount()));
print("Arguments: " + str(Env.arguments()));
print(Env.argsSlice(1));
print(Env.argsJoin("|"));
print(Env.argsIndexOf("file.txt"));
let parsed = Env.parseArgs();
print(str(parsed));
print(Env.argGet("name"));
print(Env.argHas("name"));
Flags support --key=value, --key, -k, and grouped short flags (-abc). Values are strings; flag-only entries come back as true.
Bare builtin parity
The Env class also exposes env(key, default), envFromFile(path), envFileGet(key, default, path), envRuntimeLoad(objectOrPath, overwrite), envRuntimeGet(key), envRuntimeHas(key), and envRuntimeAll() — names that mirror the global bare builtins. Env.get consults runtime-loaded values first, then the OS environment.
Complete example
A config-path builder that combines Env with Path/FS, and a system-info report.
import Env;
import FS;
print("--- Config path ---");
let config = Env.home().join(".adesh").join("config.toml");
print("Config: " + config.toString());
print("Exists: " + str(FS.exists(config)));
print("--- System info ---");
let info = Env.systemInfo();
print("OS: " + info.os + " (" + info.arch + ")");
print("Host: " + info.hostname + " / " + info.username);
print("PID: " + str(info.pid) + ", uptime " + str(info.processUptime) + "s");
print("Mem: " + str(info.totalMemory) + " bytes total");
print("--- Env variables ---");
Env.set("MY_MODE", "debug");
print("MY_MODE = " + str(Env.get("MY_MODE")));
print("Count: " + str(Env.count()));
Env.remove("MY_MODE");
Notes & edge cases
- Static-only: every
Env method is static; there is no instance to construct.
- Runtime env precedence: variables loaded via
Env.load/Env.runtimeLoad shadow the OS environment in Env.get.
- Path integration: directory/executable methods return
Path objects — chain .join(), .parent(), etc., and pass them straight to FS.
setCurrentDirectory accepts a Path or a string and changes the process working directory.
parseArgs returns { positionals, flags }; flag values are strings and bare flags are true. Note: flags consumed by the CLI itself (e.g. --run, --jit) never reach the script.
- Aliases: many methods have multiple names for parity with the global bare builtins (
unset, has, exists, environ, toObject, argv, argc, …) — they are interchangeable.
- Separators are platform-dependent:
";" vs ":", "\\" vs "/", "\r\n" vs "\n".
Source & examples
- Implementation:
src/stdlib/Env.adesh (backed by src/runtime/stdlib_src/system/args.rs)
- Runnable examples:
examples/Libraries/env/ (get_variable.adesh, set_variable.adesh, bulk_variables.adesh, env_file.adesh, user_directories.adesh, platform.adesh, system_info.adesh, arguments.adesh, arguments_advanced.adesh, executable.adesh, current_directory.adesh, home_directory.adesh, path_integration.adesh)