Documentation
¶
Overview ¶
Package substitute resolves the ${variable} placeholders that devcontainer.json and feature configs use. The behavior is intended to match upstream's src/spec-common/variableSubstitution.ts so a spec that works under devcontainers/cli works here too.
Two phases are supported:
- Pre-container substitution (Substitute / Apply): resolves ${env:VAR}, ${localEnv:VAR}, ${localWorkspaceFolder}, ${containerWorkspaceFolder}, and ${devcontainerId}. Run before the container is created.
- Post-container substitution (ContainerSubstitute / ApplyContainer): resolves ${containerEnv:VAR}. Run once the container is created and its real env is known.
Anything that doesn't resolve is left in place so the caller can surface a clearer error than "blank value at ENV[FOO]=".
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Apply ¶
Apply runs Substitute over each string in a slice, returning a new slice. Convenience for the common case of substituting mounts / runArgs / etc.
func ApplyMap ¶
ApplyMap returns a new map with values substituted. Keys are not substituted (matches upstream — env keys and label keys are configuration identifiers, not user values).
func ContainerSubstitute ¶
func ContainerSubstitute(ctx ContainerContext, s string) string
ContainerSubstitute applies the second-phase substitution (only ${containerEnv:...}). Other variables are left alone — they should already have been resolved in the first pass.
func Substitute ¶
Substitute replaces every ${...} occurrence in s using ctx. Unrecognized variables are left intact (the regex match is preserved).
Types ¶
type ContainerContext ¶
ContainerContext is the second-phase context, available once the container exists and its environment can be observed.
type Context ¶
type Context struct {
// Platform is the host OS, used to keep env-var lookups
// case-insensitive on Windows. Empty defaults to runtime.GOOS.
Platform string
// LocalWorkspaceFolder is the absolute host path of the workspace.
LocalWorkspaceFolder string
// ContainerWorkspaceFolder is the path inside the container where
// the workspace will be mounted. Used by
// ${containerWorkspaceFolder}.
ContainerWorkspaceFolder string
// LocalEnv is the host environment. Populate from os.Environ() in
// CLI use; tests can pass an explicit map.
LocalEnv map[string]string
// IDLabels are the labels we'll set on the container so it can be
// rediscovered later. ${devcontainerId} is the sha256 of this map
// (sorted, base32, 52 chars) — same scheme as upstream.
IDLabels map[string]string
}
Context drives Substitute. Any field left zero/nil simply means "no value available for variables that reference it".
Source Files