ExkPasswd.Config (ExkPasswd v0.1.1)

View Source

Modern schema-driven configuration system for password generation.

This module provides a flexible, extensible configuration approach that supports:

  • Declarative schema validation
  • Composition and merging
  • Custom validators via behaviours
  • Runtime extensibility through meta field
  • Protocol-based transformations

Examples

# Create from keyword list
{:ok, config} = Config.new(num_words: 4, separator: "-")

# Create from map
{:ok, config} = Config.new(%{num_words: 4})

# Compose from another config
{:ok, config} = Config.new(base_config, num_words: 5)

# Raise on error
config = Config.new!(num_words: 4, separator: "-")

# With custom validators
config = Config.new!(
  num_words: 4,
  validators: [MyApp.CustomValidator]
)

# With metadata for plugins
config = Config.new!(
  num_words: 3,
  meta: %{plugin_data: "custom"}
)

Summary

Types

case_transform()
substitution_mode()
t()

Functions

add_validator(config, validator_module)

Add a custom validator to the configuration.

get_meta(config, key, default \\ nil)

Get metadata from the config's meta field.

merge(base, overrides)

Merge two configurations, with the second taking precedence.

merge!(base, overrides)

Merge two configurations, raising on validation errors.

new(opts \\ [], overrides \\ [])

Create a new configuration from keyword list, map, or another config.

new!(opts \\ [], overrides \\ [])

Create a new configuration, raising on validation errors.

put_meta(config, key, value)

Put metadata into the config's meta field.

Types

case_transform()

@type case_transform() ::
  :none | :alternate | :capitalize | :invert | :lower | :upper | :random

substitution_mode()

@type substitution_mode() :: :none | :always | :random

t()

@type t() :: %ExkPasswd.Config{
  case_transform: case_transform(),
  dictionary: atom(),
  digits: {non_neg_integer(), non_neg_integer()},
  meta: map(),
  num_words: pos_integer(),
  padding: map(),
  separator: String.t(),
  substitution_mode: substitution_mode(),
  substitutions: %{required(String.t()) => String.t()},
  validators: [module()],
  word_length: Range.t(),
  word_length_bounds: Range.t() | nil
}

Functions

add_validator(config, validator_module)

@spec add_validator(t(), module()) :: t()

Add a custom validator to the configuration.

Parameters

  • config - The configuration to modify
  • validator_module - Module implementing ExkPasswd.Validator behaviour

Returns

Updated configuration with validator added.

Examples

config = Config.add_validator(config, MyApp.CustomValidator)

get_meta(config, key, default \\ nil)

@spec get_meta(t(), atom(), any()) :: any()

Get metadata from the config's meta field.

Parameters

  • config - The configuration
  • key - Metadata key
  • default - Default value if key not found

Returns

The metadata value or default.

Examples

value = Config.get_meta(config, :emoji_mode, false)

merge(base, overrides)

@spec merge(t(), keyword() | map()) :: {:ok, t()} | {:error, String.t()}

Merge two configurations, with the second taking precedence.

Parameters

  • base - Base configuration (Config struct, preset atom, or preset string)
  • overrides - Keyword list or map of overrides

Returns

  • {:ok, config} if valid
  • {:error, reason} if validation fails

Examples

{:ok, config} = Config.merge(base_config, num_words: 5)

# Merge with validation
{:ok, config} = Config.merge(base_config, %{separator: "-"})

merge!(base, overrides)

@spec merge!(t(), keyword() | map()) :: t()

Merge two configurations, raising on validation errors.

Parameters

  • base - Base configuration
  • overrides - Keyword list or map of overrides

Returns

The merged Config struct.

Raises

ArgumentError if validation fails.

Examples

config = Config.merge!(base_config, num_words: 5)

new(opts \\ [], overrides \\ [])

@spec new(
  keyword() | map() | t(),
  keyword()
) :: {:ok, t()} | {:error, String.t()}

Create a new configuration from keyword list, map, or another config.

Parameters

  • opts - Keyword list, map, or existing Config struct
  • overrides - Additional keyword list to merge (when first arg is Config)

Returns

  • {:ok, config} if valid
  • {:error, reason} if validation fails

Examples

{:ok, config} = Config.new(num_words: 4, separator: "-")

{:ok, config} = Config.new(%{num_words: 4})

# Merge with existing config
{:ok, config2} = Config.new(config, num_words: 5)

# Validation error
{:error, msg} = Config.new(num_words: 0)

new!(opts \\ [], overrides \\ [])

@spec new!(
  keyword() | map() | t(),
  keyword()
) :: t()

Create a new configuration, raising on validation errors.

Parameters

  • opts - Keyword list, map, or existing Config struct
  • overrides - Additional keyword list to merge

Returns

The validated Config struct.

Raises

ArgumentError if validation fails.

Examples

config = Config.new!(num_words: 4, separator: "-")

config = Config.new!(existing_config, separator: "_")

# Raises ArgumentError
Config.new!(num_words: 0)

put_meta(config, key, value)

@spec put_meta(t(), atom(), any()) :: t()

Put metadata into the config's meta field.

Useful for storing plugin-specific or application-specific data.

Parameters

  • config - The configuration to modify
  • key - Metadata key
  • value - Metadata value

Returns

Updated configuration.

Examples

config = Config.put_meta(config, :emoji_mode, true)
config = Config.put_meta(config, :custom_data, %{foo: "bar"})