Cheatsheet

Quick reference for Cooper's public API. See the tutorial for a walkthrough, or CASC.md for the full language reference.

Load config

Cooper.load_file(path, opts \\ [])
#=> {:ok, term()} | {:error, Ichor.Error.t() | [Ichor.Error.t()]}

Cooper.load_string(source, opts \\ [])
#=> {:ok, term()} | {:error, Ichor.Error.t() | [Ichor.Error.t()]}

load_file/2 reads path and derives :root/import-cycle detection from it automatically — the ordinary way to load a real file. Caches by default (see Caching below); pass cache: false to opt out for one call. load_string/2 is for source that isn't (yet, or ever) in a file — pass :root explicitly if it uses bare (non-scheme://) imports; never caches, since there's no file to key one on.

Options

Guards

${?NAME} statement

Guards the one statement immediately after it (same line) — statement is skipped entirely (never evaluated, not evaluated-then-discarded) when NAME is unset or empty. See the tutorial for the full walkthrough, including caching/watch_env interaction.

.env files

On by default. Layers, later winning:

System.get_env/0 < .env < .env.<dotenv_env> < .env.local < :env

.env/.env.<dotenv_env>/.env.local are optional -- missing is never an error. :env, if passed, always wins for the names it defines, but doesn't isolate resolution from anything below it -- a name not in :env still falls through to .env/the real environment. Runs through the optional :dotenvy dependency — add {:dotenvy, "~> 1.1"} to your own mix.exs deps. See the tutorial for the full walkthrough.

Caching

Cooper.load_file(path, opts \\ [])

Cooper.Cache.invalidate(path)  #=> :ok
Cooper.Cache.clear()           #=> :ok

load_file/2 caches everything up to ${...} resolution by default, keyed by mtime (entry file + every transitively bare-imported file). ${...} itself always re-runs fresh, hit or miss. cache: false bypasses the cache for one call. A ${?NAME} guard's decision is baked in at populate time, refreshed only when the entry invalidates -- not per access, unlike an ordinary value read. See the tutorial for the full walkthrough.

Telemetry, both no-op-cost with zero attached handlers:

Built-in tags

!int(arg), !float(arg), !bool(arg), !duration(arg), !bytes(arg) — always registered, need no :tags entry. !duration(...) and a bare duration literal (500ms) both produce {:duration, nanoseconds}; !bytes(...) and a bare byte-size literal (512MiB) both produce {:bytes, count}.

IP addresses and CIDR

A bare 127.0.0.1/127.0.0.1/32 (CASC.md §6.7) literal resolves to %Cooper.IPv4{}; ::1/::1/128 resolves to %Cooper.IPv6{}. Both are validated at load time — an out-of-range octet, a malformed address, or a CIDR prefix outside 0..32/0..128 is a load-time error, not a crash or a silently-accepted value.

%Cooper.IPv4{address: :inet.ip4_address(), prefix: 0..32 | nil}
%Cooper.IPv6{address: :inet.ip6_address(), prefix: 0..128 | nil}

Cooper.IPv4.new(address, prefix \\ nil)   #=> {:ok, t()} | {:error, String.t()}
Cooper.IPv4.contains?(cidr, other)        #=> boolean() -- is `other` inside `cidr`'s block?
Cooper.IPv4.network(cidr)                 #=> the block's network address
Cooper.IPv4.broadcast(cidr)               #=> the block's broadcast address (IPv4 only -- IPv6 has no equivalent)
Cooper.IPv4.netmask(cidr)                 #=> the netmask implied by the block's prefix
Cooper.IPv4.first_host(cidr)              #=> first usable host address
Cooper.IPv4.last_host(cidr)               #=> last usable host address

Cooper.IPv6 has the identical API minus broadcast/1. Both implement String.Chars, rendering back in CASC's own literal syntax ("127.0.0.1/24"), including when embedded in an interpolated string.

Secrets

%Cooper.Secret{value: term(), redacted: String.t() | nil}

Cooper.Secret.reveal(secret)
#=> the real, fully unmasked value

Any key segment prefixed with * (*key, CASC.md §4.3) comes back wrapped in Cooper.Secret. inspect/1 and to_string/1 redact unconditionally — reveal/1 (or the :value field directly) is the only way to the real value.

• Whole-value secret (*password = "...") — :redacted is nil; inspect/to_string render the blanket "[~~REDACTED~~]" marker.
• Secret embedded in a larger interpolated string ("conn=%{database.password}") — only that portion redacts, not the whole string ("conn=[~~REDACTED~~]"); several secrets interpolated into one string each redact independently at their own position.
• Travels with the value, not just its declared path — a %{...} reference or a for ... from template that copies a secret value elsewhere in the tree copies the wrapping too; a tag (!int(...)) or index ([i]) applied to a secret-sourced value re-wraps its result.

Errors

Every stage returns {:error, Ichor.Error.t() | [Ichor.Error.t()]} on failure — never a raised exception. error.message is a human-readable string; error.stage says roughly where it came from:

Test-time injection

:resolvers/:import_schemes fully replace whatever they'd otherwise reach for — a plain function/map you supply, no global state involved:

Cooper.load_string(source,
  resolvers: %{"vault" => fn payload -> {:ok, "stub:" <> payload} end},
  import_schemes: %{"mem" => fn _rest -> {:ok, other_source} end}
)

:env is different — it's an override, not an isolation mechanism (see .env files). env: %{"DB_PASSWORD" => "test-secret"} guarantees DB_PASSWORD specifically, but any other ${...} a test's source reads still falls through to .env files and the real OS environment. Give every name the test depends on an explicit :env entry rather than relying on it being otherwise unset; dotenv: false additionally skips the .env file layers if a test needs to rule those out too.

Pipeline modules

Only relevant if you need to call a stage directly instead of going through Cooper.load_file/2/load_string/2: