module

Hwaro::Utils::EnvSubstitutor

Constants

PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*(?:\{[^}]*\}[^}]*)*))?\}|\$([A-Za-z_][A-Za-z0-9_]*)\b/

Combined regex: matches ${VAR}, ${VAR:-default}, or bare $VAR in a single pass. This avoids double-substitution where a replaced value could contain $-patterns.

Group 1: braced var name (from ${VAR} or ${VAR:-default}) Group 2: default value (from ${VAR:-default}, nil when absent) Group 3: bare var name (from $VAR)

NOTE: Nested ${...} in default values is not supported. Default values may contain } as long as it's inside balanced braces.

Class methods

substitute(input : String) : Tuple(String, Array(String))

Substitute environment variables in the given string. Returns the substituted string and a list of missing variable names.

Semantics (aligned with POSIX shell):

  • ${VAR} → value if set (even empty), original text + warning if unset
  • ${VAR:-default} → value if set AND non-empty, otherwise default
  • $VAR → value if set (even empty), original text + warning if unset
Source
substitute_toml(input : String) : Tuple(String, Array(String))

Substitute placeholders in a TOML document without letting a value change its TOML syntax. substitute splices text blindly, which config loading cannot afford: a value holding " broke the load, a \ was re-read as an escape (C:\new turned into a newline) and a $VAR in a # comment was substituted and warned about.

  • inside a basic string an environment value is escaped, so it lands as exactly the characters the variable holds;
  • a ${VAR:-default} default is inserted as written: it is TOML the author already escaped;
  • a bare placeholder (paginate = ${N}) is still inserted raw, so numbers, booleans and whole values keep working;
  • comments are never substituted.
Source
substitute_with_warnings(input : String, source : String = "config") : String

Substitute and log warnings for missing variables

Source