dry-configurable

In dry-configurable, a Setting represents a single configuration entry. Each setting is defined by several key attributes that control how its value is stored, accessed, and transformed:

• name: The identifier for the setting.
• default: The initial value assigned to the setting.
• constructor: A proc or object used to transform the value (e.g., for type coercion).
• children: A collection of nested settings, making this setting a configuration group.
• mutable: A boolean indicating if the value can be modified in place. If a setting has children, it is automatically considered mutable.
• options: Additional metadata passed during definition.

Note that cloneable? is an alias for mutable?.

How you integrate Dry::Configurable determines where the configuration methods reside:

1. Extending (extend Dry::Configurable): Provides class-level configuration. You can define settings on the class itself and access them via MyClass.config or MyClass.setting.
2. Including (include Dry::Configurable): Provides instance-level configuration. The class-level config method is undefined; instead, configuration is managed on individual instances of the class.

When using dry-configurable, you may encounter specific error classes if the configuration state or inclusion logic is violated.

• Dry::Configurable::FrozenConfigError: Raised when attempting to modify a configuration that has already been frozen.
• Dry::Configurable::AlreadyIncludedError: Raised if include Dry::Configurable is called more than once on the same class (note: this constant is deprecated in favor of standard Ruby behavior or internal handling, but may still appear in legacy contexts).

The config method returns the configuration object for the class. This object is used to get or set the actual values for the settings defined via the setting method.

# Returns the Config object
MyService.config

# Example usage:
MyService.config.api_key = 'new_key'

You can retrieve a specific setting object from a Dry::Configurable::Settings collection by passing its name to the [] method. If the setting does not exist, it returns nil.

# Assuming 'settings' is an instance of Dry::Configurable::Settings
setting = settings[:my_setting_name]

The finalize! method is used to prepare the configuration for use, typically by resolving any dynamic settings and optionally freezing the configuration to prevent further modifications.

Use the freeze_values: keyword argument to determine if the individual values within the configuration should also be frozen.

• freeze_values: true: Freezes the configuration object and all its contained values.
• freeze_values: false (default): Freezes the configuration object but not necessarily the values themselves.

# Finalize and freeze the configuration to prevent further changes
MyClass.finalize!(freeze_values: true)

The configure method allows you to modify the configuration object of a class or instance. It yields the configuration object to a block, where you can set various settings. If the configuration has already been frozen (e.g., via finalize!), calling configure will raise a Dry::Configurable::FrozenConfigError.

# Assuming a class has included Dry::Configurable
MyClass.configure do |config|
  config.some_setting = 'value'
end

When using instance-level configuration (include Dry::Configurable), call finalize! on the instance after setting its configuration values. This ensures the configuration state is locked or prepared for use according to the internal lifecycle of the object.

app = App.new
app.config.database = 'sqlite:memory'
app.finalize!

When a class includes Dry::Configurable, you can access that specific instance's configuration object using the #config method. This returns a Dry::Configurable::Config object containing the settings defined for that instance.

# Assuming MyClass includes Dry::Configurable
instance = MyClass.new
config = instance.config

You can retrieve the current configuration values as a Hash using the values method or to_h.

• values: Returns a Hash where nested configurations remain as Dry::Configurable::Config instances.
• to_h: Returns a Hash where nested configurations are recursively converted into standard Hashes.

# Returns Hash with nested Config objects
hash_with_configs = config.values

# Returns Hash with nested Hashes
hash_with_hashes = config.to_h

Use the key?(name) method to check if a setting with a specific name has been defined in the collection. It returns true if the setting exists, and false otherwise.

if settings.key?(:api_key)
  # do something
end