Skip to content
This repository was archived by the owner on Nov 13, 2026. It is now read-only.

Latest commit

 

History

History
67 lines (51 loc) · 6.93 KB

expansion.md

File metadata and controls

67 lines (51 loc) · 6.93 KB

Choosing an expansion setup

Expansion is how ${VAR} references become values. You choose three things: which read call, which operator in the file, and which options (escape dialect, environment fallback, command substitution).

On this page: Which read call · Which operator · Which options · If X, use Y · Pitfalls · Related

Which read call

Call Returns On a failing ${VAR:?…} Use for Guide Example
f.Get(key) the raw value, references intact never fails anything you write back expansion, step 1 ExampleFile_Get
f.GetExpanded(key) one value, resolved; (value, found, err) returns a *RequiredError reading one value the way a consumer sees it expansion, step 1 ExampleFile_GetExpanded
f.ExpandedMap() every active key, resolved stops at the first error, returns no map handing the whole configuration to a binder expansion, step 7 ExampleFile_ExpandedMap
dotenv.Read(path) Open + ExpandedMap same as ExpandedMap a program that only consumes configuration reading, step 1 ExampleRead

Which operator

All operators are Docker Compose's. "Empty" means set to "".

You want Write Unset Empty Set to x Example
the value ${VAR} or $VAR "" "" x ExampleFile_GetExpanded
a default when it is missing or empty ${VAR:-d} d d x ExampleFile_GetExpanded_operators
a default only when it is missing ${VAR-d} d "" x same
an alternative when it has a value ${VAR:+alt} "" "" alt same
an alternative when it is set at all ${VAR+alt} "" alt alt same
to fail loudly when missing or empty ${VAR:?msg} error error x ExampleRequiredError
to fail loudly only when missing ${VAR?msg} error "" x same
a literal $ $$ — — — ExampleFile_GetExpanded_dollar
no expansion at all for this value single quotes or backticks: '${VAR}' — — — ExampleFile_GetExpanded_literal

Operators nest: ${A:-${B:-c}} works, and so do chains (C=${B} where B=${A}) (ExampleFile_GetExpanded_nesting).

Which options

Option Default Turn it on when Guide Example
WithEscapes(EscapeExtended) on your files use \n, \t, \r inside double quotes as escapes syntax, step 9 ExampleWithEscapes
WithEscapes(EscapeCompose) off Docker Compose reads the same file, or values hold Windows paths or regexes where \n must stay two characters syntax, step 9 ExampleEscapeCompose
WithLookup(fn) off references the file does not define should come from somewhere else, such as os.LookupEnv; the file always wins plugins, step 1 ExampleWithLookup
WithCommandSubstitution(true) off you trust the file and want $(command) to run through sh -c expansion, step 9 ExampleWithCommandSubstitution_order
WithCommandRunner(fn) off you want $(command) but only through your own runner (an allow-list, a sandbox, a fake in tests); installing it turns substitution on expansion, step 9 ExampleWithCommandRunner_allowList

If X, use Y

  • If you write the value back to a file, use Get. GetExpanded output saved to disk flattens the reference for good.
  • If a value must be present for the program to work, write ${VAR:?message} in the file, and match the error with errors.As(err, &re) where re is a *dotenv.RequiredError. The two ? forms are the only operators that produce an error.
  • If a value may legitimately be empty, use the forms without a colon (-, +, ?); the colon forms treat empty like unset.
  • If the file comes from somewhere you do not control (a repository, an image, a teammate), keep command substitution off. With it on, reading the file runs shell commands.
  • If you need $(command) in tests, use WithCommandRunner with a fake runner, never the real shell (ExampleWithCommandRunner).
  • If Docker Compose reads the same file, use EscapeCompose; see Options for your kind of app.

Pitfalls

  • A failing command expands to "" with no error, as a shell does inside a value. A command that must succeed needs a check in your runner.
  • WithCommandRunner(nil) turns on the real sh -c, the same as WithCommandSubstitution(true).
  • A key that refers to itself sees the line above it, as in Docker Compose. A=1 followed by A=${A}2 gives 12; ZONE=${ZONE:-x} with no earlier ZONE asks your Lookuper, then gives x (ExampleFile_GetExpanded_selfReference). In library v0.1.1 and earlier these gave 22 and "".
  • Cycles terminate but can leave text. A reference that re-enters a variable already being expanded sees only the lines above, then the Lookuper, else ""; the rest of each value stays, so A=a${B} with B=b${A} gives A = ab (ExampleFile_GetExpanded_nesting).
  • Forward references differ from Compose. A reference to a key defined further down resolves here; Compose reads top to bottom and leaves it unset.
  • Names stop at characters that are not part of a bare name. $spring.url reads $spring followed by .url; use ${spring.url}. ${MY-KEY} reads as the - operator on MY (ExampleFile_GetExpanded_names).
  • A backslash never escapes a $. Use $$.

Related