API reference

why a load or read has no answer

One sentence saying what went wrong, naming keys, lines, and paths but never a value.

Whether a lenient load may record the problem and go on: a source that is absent or cannot be read, as opposed to one that is wrong.

a type one variable's text spells

a record read from environment variables

a record rendered with its secrets hidden

configuration with loaded variables over it

A file source with a blank path.

A file that does not exist; <1> is its path.

A file that could not be read; <1> is its path and <2> the system's reason.

Bytes that do not decode; <1> is the source and <2> the encoding.

A quoted value never closed; <1> is the source, <2> the line, and <3> the key.

Nothing found by discovery; <1> is every path looked for.

An environment name that could leave its directory; <1> is the name.

Options refused at the start of a load; <1> is every problem.

Keys with no value; <1> is every key.

A value of the wrong kind; <1> is the key and <2> the kind expected.

Settings a validator refused; <1> is every failed property with its code.

One failed property; <1> is its path and <2> the validator's code.

Given files combined with probing.

Given files combined with the cascade.

Sources combined with given files.

Sources combined with probing.

Sources combined with the cascade.

A negative probe depth.

An empty file list.

A view; <1> is the count of applied keys and <2> the sources read.

A view built from no source.

What separates items listed in one sentence.

What separates problems listed in one sentence.

The environment file read when none is named, and the root of every cascade name.

What ends the name of a layer kept to one machine.

The variables that name the environment for the cascade, asked in this order.

How many parent directories probing climbs unless told otherwise.

The character a byte-order mark decodes to, dropped from the start of a text.

The word that may precede a key when export syntax is on.

The spellings of each truth value, compared in lower case.

The characters no environment name may hold, because some platform refuses them in a file name.

The sequence that would let an environment name climb out of its directory.

The kind a whole-number read expects, as Malformed names it.

The kind a float read expects, as Malformed names it.

The kind a decimal read expects, as Malformed names it.

The kind a truth-value read expects, as Malformed names it.

What a redacted rendering shows in place of a secret field.

The characters of a configuration key that its variable spells as _.

the files to read and what was skipped

The files the options name, probe for, or cascade to, in reading order. An unsafe environment name is refused; finding nothing is refused when strict and recorded otherwise.

The first directory, from start up through levels parents, holding any of the names.

A path located against a directory: an absolute path as it is, a relative one joined to it.

The explicit name when it is not blank, else the first naming variable that is set and not blank, trimmed.

Whether a name can extend .env without leaving its directory: not blank, no .., and no character a file name cannot hold on some platform.

The cascade's file names in reading order: .env, .env.local, and with a name, .env.<name> and .env.<name>.local.

how an environment file's bytes spell text

The text the bytes spell. A UTF-8, UTF-32, or UTF-16 byte-order mark selects its encoding and is dropped; otherwise declared applies. Bytes that do not spell text answer None.

The encoding's conventional name.

The value with every $NAME and ${NAME} replaced by the known value of NAME, else its process value, else nothing. A $ after an odd run of backslashes is literal and every run before a $ is halved; an answered value is final text and is not expanded again.

The variable a field reads when no @env names one: the field's name in upper snake case, with _ before each upper-case letter that follows a lower-case letter or a digit.

The variable a configuration setting reads: its key in upper case with each . and - as _, the spelling the standard configuration reads from the environment.

one assignment, in file order

loaded values settled over the process

The known values with key set to value when overwriting or when the key is new.

Every entry of every layer kept in order by the overwrite rule.

The process values with each loaded value stored over them when overwriting or when the process value is unset or empty, and the stored keys in sorted order.

the reading rules the options set

a quote opened and never closed

entries and what later expansions know

The entries the lines assign, in order, with known grown by each one the overwrite rule keeps. Expansion reads known before process. A quote never closed answers its opening line, counted from 1, and its key.

The lines of a text split on \n, each without the \r that ends a CRLF line, and without a byte-order mark at the start of the text.

The whole number the text spells, with an optional sign, ignoring surrounding space.

The floating-point number the text spells, ignoring surrounding space.

The exact decimal number the text spells, ignoring surrounding space.

true or false in any letter case, ignoring surrounding space.

The merged values of the sources the options name, over the process environment as it is.

The merged values settled over the process environment as it is.

The merged values of the sources the options name, expanding over process instead of the process environment.

The merged values settled over process instead of the process environment.

a fluent chain ending in a read or load

every choice a load makes

Lenient, reading .env in the working directory as UTF-8, untrimmed, overwriting, with inline comments and without export syntax, expansion, probing, or the cascade.

Every reason the options cannot be followed, all at once.

options changed one choice at a time

The settings record bound from the variables by its derived Bind, once the validator accepts it; a refusal names each missing variable, the first malformed one, or each failed property.

The settings once the validator accepts them. Failures of Error severity refuse them as Invalid, naming each property and code but never the validator's message, which may quote a value; warnings and notes do not refuse.

a file path, text, or bytes

The name a problem gives the source: its path, or the label it was given.

The source's lines, split on \n or \r\n, after decoding its bytes in encoding unless a byte-order mark says otherwise.

The template with each <n> replaced by the nth value, counting from 1, in one pass: text taken from a value is never filled again. A slot without a value is kept as written.

a settled view whose values stay hidden

The loaded values settled over the process values: each replaces a process value when overwriting, or when the process value is unset or empty.

The process environment alone, read once.

The value of a key that is set and not empty.

Whether a key is set and not empty.

The value of a key, or Missing naming it.

The whole number a key holds, or Missing or Malformed naming it.

The whole number a key holds, when it is set and spells one.

The floating-point number a key holds, or Missing or Malformed naming it.

The floating-point number a key holds, when it is set and spells one.

The exact decimal number a key holds, or Missing or Malformed naming it.

The exact decimal number a key holds, when it is set and spells one.

The truth value a key holds, or Missing or Malformed naming it.

The truth value a key holds, when it is set and spells one.

The value of a key wrapped so that rendering it shows a placeholder, or Missing naming it.

Nothing when every key is set and not empty, else Missing with every absent key in the order asked.

The launch giving the child process every applied key and its value.

How many keys were applied from which sources, without any value.