env

Process environment variable access.

Naming convention: import the module under its bare name (import "env"), reach members with a backslash, and call methods in camelCase: env\someMethod.

Methods

get

Return the value of name, or "" if unset. Use lookup to tell unset from set-but-empty.

Signature: env\get(name) -> string¹ - source

Returns: string

lookup

Return (value, found); found is false when name is unset or stripped by the sandbox.

Signature: env\lookup(name) -> string, bool² - source

Returns: string, bool

set

Set name to value for this run: its later reads and the processes it starts see it, other runs in the same magus process do not.

Signature: env\set(name, value) - source

list

Return all environment variables as a name->value map.

Signature: env\list() -> map[string]string - source

Returns: map[string]string

unset

Remove name for this run, the counterpart of set.

Signature: env\unset(name) - source

expand

Replace $VAR and ${VAR} references in s with their values (sandbox-stripped names expand to "").

Signature: env\expand(s) -> string - source

Returns: string

home

Return the current user's home directory.

Signature: env\home() -> string - source

Returns: string

getOr

Return the value of name, or def when name is unset or stripped by the sandbox. Unlike get, an empty string is returned as-is - def only applies when the variable is absent.

Signature: env\getOr(name, def) -> string - source

Returns: string

require

Return the value of name, or raise when it is unset or stripped by the sandbox. The fail-fast complement to get/lookup: a CI magusfile that needs GITHUB_TOKEN states the requirement once instead of threading a lookup-then-fatal check through every caller. A set-but-empty variable satisfies the requirement (its empty value is returned).

Signature: env\require(name) -> string - source

Returns: string

parseDotenv

Parse .env-format content into a name->value map. Supports KEY=VALUE, blank lines, # comments, a leading export keyword, single/double quotes (double-quoted values honor \n \t " \ escapes), and inline comments after unquoted values. Pure: it does not touch the process environment.

Signature: env\parseDotenv(content) -> map[string]string - source

Returns: map[string]string

readDotenv

Read a .env file and return its name->value map (parse_dotenv over the file contents). Errors if the file cannot be read.

Signature: env\readDotenv(path) -> map[string]string - source

Returns: map[string]string

loadDotenv

Read a .env file and set each variable for this run, as set does, without overwriting names already set (the dotenv convention) or names the sandbox strips. A no-op in a recording/dry-run.

Signature: env\loadDotenv(path) - source