yodel

Yodel is a type-safe configuration loader for Gleam that handles JSON, YAML, and TOML configs with automatic format detection, environment variable resolution, and an intuitive dot-notation API for accessing your config values.

import yodel

let ctx = yodel.load("config.toml")
yodel.get_string(ctx, "foo.bar") // "fooey"

Yodel can resolve placeholders in the configuration content, using environment variables.

Placeholders are defined as ${foo} where foo is the placeholder key.
Placeholders can have default values like ${foo:bar} where bar is the default value.
Placeholders can be nested like ${foo:${bar}} where bar is another placeholder key.

# system environment variables
echo $FOO # "fooey"
echo $BAR # <empty>

# config.toml
foo = "${FOO}"
bar = "${BAR:default}"

import yodel

let ctx = case yodel.load("config.toml") {
  Ok(ctx) -> ctx
  Error(e) -> Error(e) // check your config!
}

yodel.get_string(ctx, "foo") // "fooey"
yodel.get_string(ctx, "bar") // "default"

Yodel makes it easy to access configuration values in your Gleam code.

Access values from your configuration using dot-notation.
Get string, integer, float, and boolean values from the configuration.
Optional return default values if the key is not found.

Types

Context

</>

The Context type, representing a configuration context. This is the main type used to hold configuration values. It is opaque, meaning you cannot access the properties directly. Use the provided functions to access the configuration values.

pub type Context =
  context.Context

Format

</>

The format of the configuration file. Defaults to Auto.

pub type Format =
  options.Format

ResolveMode

</>

The Resolve Mode to use, either resolve_strict or resolve_lenient. resolve_strict will fail if any placeholder is unresolved. resolve_lenient, the default, will preserve unresolved placeholders.

pub type ResolveMode =
  options.ResolveMode

Constants

auto_format

</>

pub const auto_format: Format

Attempt to automatically detect the format of the configuration file.

If the input is a file, we first try to detect the format from the file extension. If that fails, we try to detect the format from the content of the file.

If the input is a string, we try to detect the format from the content.

If Auto Detection fails, an error will be returned because we can’t safely proceed. If this happens, try specifying the format using as_json, as_toml, as_yaml, or with_format.

This is the default.

json_format

</>

pub const json_format: Format

Parse the configuration file as JSON.

lenient_resolve

</>

pub const lenient_resolve: ResolveMode

Lenient Resolve Mode - Preserve unresolved placeholders.

This means ${foo} will remain as ${foo} if foo is not defined.

This is the default.

strict_resolve

</>

pub const strict_resolve: ResolveMode

Strict Resolve Mode - Fail if any placeholder is unresolved.

toml_format

</>

pub const toml_format: Format

Parse the configuration file as TOML.

yaml_format

</>

pub const yaml_format: Format

Parse the configuration file as YAML.

Functions

as_json

</>

pub fn as_json(options options: Options) -> Options

Set the format of the configuration file to JSON.

Example:

let ctx =
  yodel.default_options()
  |> yodel.as_json()
  |> yodel.load_with_options(my_config)

as_toml

</>

pub fn as_toml(options options: Options) -> Options

Set the format of the configuration file to TOML.

Example:

let ctx =
  yodel.default_options()
  |> yodel.as_toml()
  |> yodel.load_with_options(my_config)

as_yaml

</>

pub fn as_yaml(options options: Options) -> Options

Set the format of the configuration file to YAML.

Example:

let ctx =
  yodel.default_options()
  |> yodel.as_yaml()
  |> yodel.load_with_options(my_config)

auto_detect_format

</>

pub fn auto_detect_format(options options: Options) -> Options

Attempt to automatically detect the format of the configuration file.

If the input is a file, we first try to detect the format from the file extension. If that fails, we try to detect the format from the content of the file.

If the input is a string, we try to detect the format from the content.

If Auto Detection fails, an error will be returned because we can’t safely proceed. If this happens, try specifying the format using as_json, as_toml, as_yaml, or with_format.

Example:

let ctx =
  yodel.default_options()
  |> yodel.auto_detect_format()
  |> yodel.load_with_options(my_config)

default_options

</>

pub fn default_options() -> Options

The default options for loading a configuration file.

Default Options:

Format: auto_format
Resolve Enabled: True
Resolve Mode: lenient_resolve

Example:

let ctx =
  yodel.default_options()
  |> yodel.load_with_options("config.toml")

disable_resolve

</>

pub fn disable_resolve(options options: Options) -> Options

Disable placeholder resolution.

Example:

let ctx =
  yodel.default_options()
  |> yodel.disable_resolve()
  |> yodel.load_with_options("config.yaml")

enable_resolve

</>

pub fn enable_resolve(options options: Options) -> Options

Enable placeholder resolution.

Example:

let ctx =
  yodel.default_options()
  |> yodel.enable_resolve()
|> yodel.load_with_options("config.yaml")

get_bool

</>

pub fn get_bool(
  ctx: Context,
  key: String,
) -> Result(Bool, PropertiesError)

Get a boolean value from the configuration. If the value is not a boolean, an error will be returned.

Example:

case yodel.get_bool(ctx, "foo") {
  Ok(value) -> value // True
  Error(e) -> Error(e)
}

get_bool_or

</>

pub fn get_bool_or(
  ctx: Context,
  key: String,
  default: Bool,
) -> Bool

Get a boolean value from the configuration, or a default value if the key is not found.

Example:

let value = yodel.get_bool_or(ctx, "foo", False)

get_float

</>

pub fn get_float(
  ctx: Context,
  key: String,
) -> Result(Float, PropertiesError)

Get a float value from the configuration. If the value is not a float, an error will be returned.

Example:

case yodel.get_float(ctx, "foo") {
  Ok(value) -> value // 42.0
  Error(e) -> Error(e)
}

get_float_or

</>

pub fn get_float_or(
  ctx: Context,
  key: String,
  default: Float,
) -> Float

Get a float value from the configuration, or a default value if the key is not found.

Example:

let value = yodel.get_float_or(ctx, "foo", 42.0)

get_format

</>

pub fn get_format(options options: Options) -> Format

Get the format of the configuration file.

Example:

let format = yodel.get_format(options)

get_int

</>

pub fn get_int(
  ctx: Context,
  key: String,
) -> Result(Int, PropertiesError)

Get an integer value from the configuration. If the value is not an integer, an error will be returned.

Example:

case yodel.get_int(ctx, "foo") {
  Ok(value) -> value // 42
  Error(e) -> Error(e)
}

get_int_or

</>

pub fn get_int_or(ctx: Context, key: String, default: Int) -> Int

Get an integer value from the configuration, or a default value if the key is not found.

Example:

let value = yodel.get_int_or(ctx, "foo", 42)

get_resolve_mode

</>

pub fn get_resolve_mode(options options: Options) -> ResolveMode

Get the resolve mode.

Example:

let mode = yodel.get_resolve_mode(options)

get_string

</>

pub fn get_string(
  ctx: Context,
  key: String,
) -> Result(String, PropertiesError)

Get a string value from the configuration. If the value is not a string, an error will be returned.

Example:

case yodel.get_string(ctx, "foo") {
  Ok(value) -> value // "bar"
  Error(e) -> Error(e)
}

get_string_or

</>

pub fn get_string_or(
  ctx: Context,
  key: String,
  default: String,
) -> String

Get a string value from the configuration, or a default value if the key is not found.

Example:

let value = yodel.get_string_or(ctx, "foo", "default")

is_resolve_enabled

</>

pub fn is_resolve_enabled(options options: Options) -> Bool

Check if placeholder resolution is enabled.

Example:

case yodel.is_resolve_enabled(options) {
  True -> "Resolution is enabled"
  False -> "Resolution is disabled"
}

load

</>

pub fn load(from input: String) -> Result(Context, ConfigError)

Load a configuration file.

This function will read the config content, detect the format, resolve the placeholders, parse the config content, returning a Context if successful.

input can be a file path or a string containing the configuration content.

Example:

let ctx = yodel.load("config.toml")

let content = "foo: bar" // yaml content
let ctx = yodel.load(content)

load_with_options

</>

pub fn load_with_options(
  with options: Options,
  from input: String,
) -> Result(Context, ConfigError)

Load a configuration file with options.

This function will use the provided options to read and parse the config content, returning a Context if successful.

parse_bool

</>

pub fn parse_bool(
  ctx: Context,
  key: String,
) -> Result(Bool, PropertiesError)

Parse a bool value from the configuration.

If the value is not a bool, it will be converted to a bool. An error will be returned if the value is not a bool or cannot be converted to a bool.

Example:

case yodel.parse_bool(ctx, "foo") {
  Ok(value) -> value // True
  Error(e) -> Error(e)
}

parse_float

</>

pub fn parse_float(
  ctx: Context,
  key: String,
) -> Result(Float, PropertiesError)

Parse a float value from the configuration.

If the value is not a float, it will be converted to a float. An error will be returned if the value is not a float or cannot be converted to a float.

Example:

case yodel.parse_float(ctx, "foo") {
  Ok(value) -> value // 99.999
  Error(e) -> Error(e)
}

parse_int

</>

pub fn parse_int(
  ctx: Context,
  key: String,
) -> Result(Int, PropertiesError)

Parse an integer value from the configuration.

If the value is not an integer, it will be converted to an integer. An error will be returned if the value is not an integer or cannot be converted to an integer.

Example:

case yodel.parse_int(ctx, "foo") {
  Ok(value) -> value // 42
  Error(e) -> Error(e)
}

parse_string

</>

pub fn parse_string(
  ctx: Context,
  key: String,
) -> Result(String, PropertiesError)

Parse a string value from the configuration.

If the value is not a string, it will be converted to a string. An error will be returned if the value is not a string or cannot be converted to a string.

Example:

case yodel.parse_string(ctx, "foo") {
  Ok(value) -> value // "42"
  Error(e) -> Error(e)
}

with_format

</>

pub fn with_format(
  options options: Options,
  format format: Format,
) -> Options

Set the format of the configuration file.

Example:

let ctx =
  yodel.default_options()
  |> yodel.with_format(yodel.json_format)
  |> yodel.load_with_options("config.json")

with_lenient_resolve

</>

pub fn with_lenient_resolve(options options: Options) -> Options

Set the resolve mode to lenient.

Example:

let ctx =
  yodel.default_options()
  |> yodel.with_lenient_resolve()
  |> yodel.load_with_options(my_config)

with_resolve_enabled

</>

pub fn with_resolve_enabled(
  options options: Options,
  enabled enabled: Bool,
) -> Options

Enable or disable placeholder resolution.

Example:

let ctx =
  yodel.default_options()
  |> yodel.with_resolve_enabled(False)
  |> yodel.load_with_options("config.yaml")

with_resolve_mode

</>

pub fn with_resolve_mode(
  options options: Options,
  mode mode: ResolveMode,
) -> Options

Set the resolve mode.

Example:

let ctx =
  yodel.default_options()
  |> yodel.with_resolve_mode(yodel.strict_resolve)
  |> yodel.load_with_options("config.json")

with_strict_resolve

</>

pub fn with_strict_resolve(options options: Options) -> Options

Set the resolve mode to strict.

Example:

let ctx =
  yodel.default_options()
  |> yodel.with_strict_resolve()
  |> yodel.load_with_options(my_config)