env.expand
import env.expand
envdoes not re-export this module, so it is reached only by importing it directly.
Resolving the $ references inside a value.
The syntax is the shell’s, because that is what a .env file looks like
to everyone who has ever written one, and the modifiers are the four
from POSIX parameter expansion that earn their place in a configuration
file: a fallback, an override, and a demand.
Nothing here reads the environment itself. Every lookup goes through the
resolve function the caller supplies, which is what lets the loader
answer with the value a name is about to have rather than the one it has
now.
Functions
expand()
env.expand.expand(value: string, resolve: function) -> string
Replaces every $ reference in value with what resolve answers, and
returns the result.
resolve is called with one variable name and returns its value, or
nil when the name has none. Everything the caller wants to decide
about precedence, recursion and cycles is decided inside it.
The forms understood are $NAME, ${NAME}, and ${NAME} carrying one
of three modifiers:
| Written | Means |
|---|---|
${NAME:-fallback} | the value, or fallback when it is unset or empty |
${NAME-fallback} | the value, or fallback when it is unset |
${NAME:+instead} | instead when the value is set and not empty, otherwise nothing |
${NAME+instead} | instead when the value is set, otherwise nothing |
${NAME:?reason} | the value, or a MissingVariable carrying reason |
${NAME?reason} | the same, counting an empty value as set |
The text after a modifier is itself expanded, so
${HOST:-${FALLBACK_HOST}} does what it looks like. A $ that names
nothing stands for itself, and \$ is always a literal dollar sign.
Parameters
value(string)resolve(function)
Returns string
Raises EnvError when a reference is not closed or carries a
modifier that does not exist.
Raises MissingVariable when a ${NAME:?reason} reference finds
nothing.
2026, Richard Ore and Zuri contributors