Alaja.Config (Alaja v2.3.0)

Configuration management for Alaja CLI applications.

Values are read from ~/.config/alaja/alaja.conf on first access and kept in the Application environment for the lifetime of the process. set/2 writes through to both the in-memory store and the conf file.

In addition to the JSON config file, environment variables prefixed with ALAJAX_ override persisted values at load time. The mapping is mechanical: ALAJAX_COLOR_DEPTH overrides :color_depth, ALAJAX_THEME_ACTIVE overrides :theme_active. This lets CI shells and one-off scripts override the on-disk config without rewriting it.

Usage

Alaja.Config.get(:color_depth, :truecolor)
Alaja.Config.set(:color_depth, :xterm256)
Alaja.Config.all()

Summary

Functions

all()

Returns all configuration values (merged defaults + env + file).

config_file_path()

Returns the path to the config file.

get(key, default \\ nil)

Gets a configuration value with fallback.

list_themes()

Returns available theme names.

load!(path, opts \\ [])

Loads configuration from path and overlays ALAJAX_* env vars.

load_theme(name)

Loads a theme by name.

lookup_theme_color(key)

Looks up a color key in the currently active theme.

set(key, value)

Sets a configuration value.

Functions

all()

@spec all() :: keyword()

Returns all configuration values (merged defaults + env + file).

config_file_path()

@spec config_file_path() :: String.t()

Returns the path to the config file.

get(key, default \\ nil)

@spec get(atom(), any()) :: any()

Gets a configuration value with fallback.

list_themes()

@spec list_themes() :: [String.t()]

Returns available theme names.

load!(path, opts \\ [])

@spec load!(
  String.t(),
  keyword()
) :: :ok

Loads configuration from path and overlays ALAJAX_* env vars.

The on-disk JSON content is parsed into a map and each key is written to Application env. Env vars win over the file content: for every {"ALAJAX_X" => :foo} mapping, if the env var is set and non-empty, its value (cast through cast_env_value/2) is written last and therefore wins.

Pass skip_env: true to skip the env var overlay — useful in tests that need deterministic, file-only behaviour regardless of the BEAM-wide env state.

Missing files, malformed JSON, and parse errors are all swallowed silently — Config must never crash an escript at startup. Returns :ok once the overlay has been applied.

Example

iex> Alaja.Config.load!("/path/that/does/not/exist.json")
:ok

load_theme(name)

@spec load_theme(String.t()) :: {:ok, map()} | {:error, term()}

Loads a theme by name.

lookup_theme_color(key)

@spec lookup_theme_color(String.t()) ::
  {:ok, {integer(), integer(), integer()}} | :error

Looks up a color key in the currently active theme.

This is the public API used by the Pote theme resolver bridge: "theme:<key>" lookups in Pote.Orchestrator end up here when Alaja is the running app, so e.g. alaja separator --color "theme:ternary" resolves to the actual ternary color of the active theme, not Pote's hardcoded default palette.

Returns {:ok, {r, g, b}} on hit, :error on miss (key absent or theme file unreadable).

set(key, value)

@spec set(atom(), any()) :: :ok

Sets a configuration value.

If the key is in the list of persistent keys it is also written to ~/.config/alaja/alaja.conf. Always updates the in-memory store.