`env`

Environment variable management - get a variable with an optional default, set a variable, require a variable (error if absent), read as integer or boolean, read as a delimited list, load a .env file from a string or path, check presence, and snapshot common system variables.

Load with: use env

What this module does

env provides a clean, typed interface to environment variables. Raw environment access uses both the host-context binding (hp_env_get) and the system native (__sys_getenv), falling back through both before using the supplied default.

Beyond raw strings, env offers typed accessors for integers (envit), booleans (envbl), and comma-separated lists (envls). .env files are loaded with envld (from a string) or envlf (from a file path) - both strip comments and handle single- and double-quoted values.

All functions are also available via the env namespace object.

Quick example

use env

# Load a .env file at startup
env.file(".env")

# Get a variable with a default
host = env.get("DB_HOST", "localhost")

# Require a variable - errors if missing
key = env.req("API_KEY")

# Typed reads
port = env.int("PORT", "5432")  # integer
debug = env.bol("DEBUG", "false")  # boolean
tags = env.lst("TAGS", ",", [])  # list

# Set a variable
env.set("STAGE", "production")

# Check presence
prn(env.ok("REDIS_URL"))

Functions

Reading

envgt(key, default)

Gets the environment variable key. Checks the host context first, then __sys_getenv. Returns default (as a string) if the variable is absent or empty, or nil if no default is given. Also available as env.get(key, default).

envrq(key)

Like envgt but throws an error if the variable is absent or empty: "env: {key} required". Use for variables that must be set to run. Also available as env.req(key).

envok(key)

Returns tru if the variable is set and non-empty. Also available as env.ok(key).

Typed accessors

envit(key, default)

Gets the variable as an integer via int(). Returns the default integer if absent. Returns nil if the value is nil. Also available as env.int(key, default).

envbl(key, default)

Gets the variable as a boolean. Returns tru for "true", "1", "yes", or "on" (case-sensitive). Returns fls for anything else. Also available as env.bol(key, default).

envls(key, sep, default)

Gets the variable as a trimmed list, splitting on sep (default: ","). Returns default if the variable is absent. Also available as env.lst(key, sep, default).

Writing

envst(key, value)

Sets an environment variable via __sys_setenv. Also available as env.set(key, value).

.env file loading

envld(content)

Parses a .env file from a string. Skips blank lines and lines starting with #. Splits on the first =. Strips surrounding single or double quotes from values. Calls envst for each pair. Returns a map of {key: value} for all loaded variables. Also available as env.load(content).

envlf(path)

Reads the file at path and passes its contents to envld. Also available as env.file(path).

System snapshot

envdm()

Returns an object with common system environment variables: HOME, PATH, USER, SHELL, TERM. Missing variables appear as empty strings.

Notes

Variable lookup checks host context (hp_env_get) before the system environment - host-injected variables take priority.
Requires txt, trl, and host_run_ctx.