Module env 

Environment-variable references in an app’s TOML files.

Every TOML file apiplant reads from an app directory — main.toml, each models/*.toml, each functions/*.toml — goes through expand_document before it is deserialized, so any string value may name variables:

[database]
url = "$DATABASE_URL"

[email]
api_key = "${SENDGRID_API_KEY}"

This is what lets a main.toml you commit hold no credentials: the file describes where the secret comes from, and the deployment supplies it.

The syntax

Written	Means
$VAR, ${VAR}	the variable’s value, or "" (with a warning) when unset
${VAR:-default}	the variable’s value, or default when unset or empty
$$	a literal $
$ followed by anything else	itself, unchanged

A name is a letter or _ followed by letters, digits or _. Anything that isn’t one — $19.99, US$, a$b — is left exactly as written, so text that merely contains a dollar sign needs no escaping and only a genuine ambiguity ($$USD) calls for $$.

Several references can appear in one string, which is the case that makes this worth having over a whole-value substitution:

url = "postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:${DB_PORT:-5432}/$DB_NAME"

Where it happens

On the parsed document, not the raw text: a value is substituted into a string that TOML has already produced, so a password containing " or \ can’t turn into a syntax error or, worse, into extra TOML. Keys are never expanded — a table named by the environment would make a file’s shape depend on the deployment, which is not what this is for.

Functions

expand

Expand $VAR, ${VAR}, ${VAR:-default} and $$ in one string.

expand_document

Expand every string value in a parsed TOML document, in place.

parse_toml

Parse a TOML file, expanding environment references in its string values.