envspec

Documentation

Overview

Package envspec parses and evaluates the entries of a clawk.mod `env ( … )` block — the small expression language that maps a guest-side environment variable to a host variable, a literal, or a host variable with a fallback.

The grammar deliberately mirrors POSIX-shell / docker-compose parameter expansion, so there is nothing new to learn:

NAME                       passthrough — export NAME = host $NAME
                           (empty if unset; a warning is logged)
NAME = ${HOST}             alias      — export NAME = host $HOST
NAME = ${HOST:-default}    default if HOST is unset OR empty
NAME = ${HOST-default}     default if HOST is unset (empty kept)
NAME = ${HOST:?message}    hard error if HOST is unset OR empty
NAME = ${HOST?message}     hard error if HOST is unset
NAME = literal             literal constant, no host lookup
NAME = "literal"           quoted literal (spaces / special chars)

A bare or quoted right-hand side is always a literal; host variables are referenced only through ${…}. This removes the "is that a value or a variable name?" ambiguity that a bare-name alias syntax hits the moment defaults enter the picture.

Entries round-trip through their canonical String() form, which is what the template parser stores and what Parse reads back — so clawk.mod's env list stays a plain []string end to end (dedup, union, and JSON persistence never need to know about the structure).

Index

• func Quote(v string) string
• func Unquote(s string) (string, error)
• func ValidateName(s string) error
• type Op
• type Spec
  • func Parse(entry string) (Spec, error)
  • func (s Spec) Resolve(lookup func(string) (string, bool)) (value string, warnUnset bool, err error)
  • func (s Spec) String() string

Functions

func Quote

func Quote(v string) string

Quote renders v as a double-quoted string using the same escape set the clawk.mod lexer understands (\" \\ \n \t).

func Unquote

func Unquote(s string) (string, error)

Unquote is the inverse of Quote. It requires a leading and trailing double quote.

func ValidateName

func ValidateName(s string) error

ValidateName enforces the POSIX shell variable-name shape. Lowercase is allowed on purpose — names like http_proxy are legitimate.

Types

type Op

type Op uint8

Op is how a Spec combines its host variable and its literal argument.

const (
	// OpPassthrough exports the host variable's value, or empty (with a
	// warning) when it is unset. Covers both `NAME` and `NAME = ${HOST}`.
	OpPassthrough Op = iota
	// OpDefaultUnset uses Arg when the host variable is unset; a set but
	// empty value is kept. `${HOST-arg}`.
	OpDefaultUnset
	// OpDefaultEmpty uses Arg when the host variable is unset OR empty.
	// `${HOST:-arg}`.
	OpDefaultEmpty
	// OpRequiredUnset fails resolution when the host variable is unset.
	// `${HOST?arg}` (arg is the error message).
	OpRequiredUnset
	// OpRequiredEmpty fails resolution when the host variable is unset OR
	// empty. `${HOST:?arg}`.
	OpRequiredEmpty
	// OpLiteral exports Arg verbatim with no host lookup.
	OpLiteral
)

type Spec

type Spec struct {
	Name string // guest variable to export (always a valid env name)
	Host string // host variable to read; "" exactly when Op == OpLiteral
	Arg  string // default value, error message, or literal — per Op
	Op   Op
}

Spec is one parsed env entry.

func Parse

func Parse(entry string) (Spec, error)

Parse reads one canonical entry (see the package doc) into a Spec. It is the single source of truth for the grammar: the template parser calls it to validate at parse time, and the sandbox layer calls it again to evaluate at manifest-build time.

func (Spec) Resolve

func (s Spec) Resolve(lookup func(string) (string, bool)) (value string, warnUnset bool, err error)

Resolve evaluates the spec against a host-env lookup (os.LookupEnv in production; a fake in tests). warnUnset reports a bare passthrough whose host variable is unset — the caller logs it and exports empty, preserving the historical behavior. A required-but-missing variable returns an error instead.

func (Spec) String

func (s Spec) String() string

String returns the canonical, re-parseable text for the spec. Parse(s.String()) == s for every valid Spec.