configsl 1.0.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 996520d6a141a33f05a05cca3318e284646e1513b25ee4c0a4f40cfacc794922
-  data.tar.gz: 4c3df5cff5db3806c8e8423c0d6813bd2e180ccf05827b65a80e47f0aa99b29b
+  metadata.gz: bcb5d7709de6f2d5a3b019662fc01771cfb754ac1a4f234a7e760e20c40b159f
+  data.tar.gz: f94d74b4fd5976c935eb6fac512746ff529f55a7a2611e6c1760d70ba3695951
 SHA512:
-  metadata.gz: 0d2d5b158111e87a0de35946016c8bd29ed2fdd9b47f85ec72e4224ade52ae292ddbe84bbad7ac48cf0221a57f6fed14d05ff17e54a56a04dfed471078cfbff1
-  data.tar.gz: ae533574e3eb01cb827e71eb7319e7028fdd723eb546f85fd28d57bc27d21c76a007724ea075a6366420062fafe03acdc09059ba763168ce19ba4350216760c7
+  metadata.gz: 658ed24bbaf0efb17956713c48df37cd02b46b954386547a8258b4f20088e1306c9056918ac036e4e1c951f62c8b40dc85e77e22ae6b394411399ea7f5c86a72
+  data.tar.gz: 0411a560f507de254e92ca98268913ec9ffead15e31d715b4e4ad15ff62c9622f84d7f1fd346454f26e4d31b598439e7fb8632c8bddac685b3c1076be5b1ddaf

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog][changelog], and this project adheres
 to [Semantic Versioning][versioning].
 
+## [1.1.1]
+
+### Fixed
+
+- Reported gem version
+
+## [1.1.0]
+
+### Added
+
+- Support collections of configuration objects with the new `Collection` module
+- Add `ToHash` module for converting configuration objects to hashes using
+  `to_h`
+- Create setter methods for options
+- Added `Merge` module to merge parameters from multiple sources
+
+### Fixed
+
+- Renamed `@params` to `@configsl_params` to avoid collisions
+- Add `configsl_` prefix to more methods to avoid conflicts
+
+### Deprecated
+
+- `FileSupport.find_file` is deprecated; use `configsl_find_file` instead
+- `FileSupport.find_file_format` is deprecated; use `configsl_find_file_format`
+  instead
+
 ## [1.0.2]
 
 ### Added

data/Gemfile

@@ -6,20 +6,20 @@ gemspec
 
 group :development do
   gem 'rake', '~> 13.2'
-  gem 'rubocop', '~> 1.65'
-  gem 'rubocop-factory_bot', '~> 2.26'
-  gem 'rubocop-rake', '~> 0.6'
-  gem 'rubocop-rspec', '~> 3.0'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-factory_bot', '~> 2.27'
+  gem 'rubocop-md', '~> 2.0'
+  gem 'rubocop-performance', '~> 1.25'
+  gem 'rubocop-rake', '~> 0.7'
+  gem 'rubocop-rspec', '~> 3.5'
 end
 
 group :test do
-  # activesupport 7.2 introduces a breaking change that causes the specs to
-  # fail.
-  gem 'activesupport', '~> 7.1.0'
+  gem 'activesupport', '~> 8.1'
 
   gem 'coveralls_reborn', '~> 0.28'
-  gem 'factory_bot', '~> 6.4'
+  gem 'factory_bot', '~> 6.5'
   gem 'rspec', '~> 3.13'
-  gem 'rspec-github', '~> 2.4'
+  gem 'rspec-github', '~> 3.0'
   gem 'simplecov', '~> 0.22'
 end

data/README.md

@@ -1,4 +1,4 @@
-# ConfigSL [![Gem Version](https://badge.fury.io/rb/configsl.svg)](https://badge.fury.io/rb/configsl) [![Coverage Status][badge-coverage]][coverage] [![Code Checks](https://github.com/jamesiarmes/configsl/actions/workflows/checks.yaml/badge.svg?branch=main)](https://github.com/jamesiarmes/configsl/actions/workflows/checks.yaml)
+# ConfigSL [![Gem Version][badge-version]][rubygems] [![Coverage Status][badge-coverage]][coverage] [![Code Checks][badge-checks]][checks]
 
 ConfigSL is a simple Domain-Specific Language (DSL) module for configuration.
 It is designed to provide a declarative way to define configuration, with as few
@@ -10,7 +10,7 @@ extensible, so you can use as little or as much as you need.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'configsl'
+gem 'configsl', '~> 1.1'
 ```
 
 And then execute:
@@ -37,26 +37,47 @@ You can start defining your configurations using two methods:
 The `ConfigSL::Config` base class includes common functionality for working with
 configurations. Currently, the class provides the following features:
 
+- **Collections**: Supports arrays and hashes of other configurations
 - **DSL**: The primary DSL for defining configuration options
 - **Format**: A simple way to enforce option value formatting
 - **FromEnvironment**: Load configuration from environment variables
 - **FromFile**: Load configuration from a file
+- **Merge**: Merge configuration from multiple sources
+- **ToHash**: Recursively convert the configuration to a hash
 - **Validation**: Built-in validation for configuration options
 
 ```ruby
 require 'configsl'
 
 class AppConfig < ConfigSL::Config
-    register_file_format :json
-    register_file_format :yaml
+  register_file_format :json
+  register_file_format :yaml
 
-    option :name, type: String, default: 'My App'
-    option :environment, type: Symbol, enum: %i[dev test prod], default: :dev,
-                         env_variable: 'RACK_ENV'
-    option :database, type: DatabaseConfig, required: true
+  option :name, type: String, default: 'My App'
+  option :environment, type: Symbol, enum: %i[dev test prod], default: :dev,
+                       env_variable: 'RACK_ENV'
+  option :database, type: DatabaseConfig, required: true
+
+  # Collect arrays or hashes into configuration objects. Automatically set a key
+  # on the collected configurations based on their index (arrays) or key
+  # (hashes).
+  option :hosts, type: Hash, collection: { type: HostConfig, key: :hostname }
+
+  # Use shorthand syntax if you don't need to set a key.
+  option :plugins, type: Array, collection: PluginConfig
 end
 ```
 
+You can load your configuration from different sources using the following
+methods:
+
+```ruby
+AppConfig.new(params) # Load from parameters
+AppConfig.from_file # Load from a file
+AppConfig.from_environment # Load from environment variables
+AppConfig.load # Merge from multiple sources
+```
+
 ### Including modules
 
 If you'd like to pick and choose the features you want to use, you can include
@@ -70,19 +91,19 @@ that sets the configuration values by calling `set_value` for each option.
 require 'configsl'
 
 class ApplicationConfig
-    include ConfigSL::DSL
-    include ConfigSL::Format
-    include ConfigSL::FromEnvironment
-
-    option :name, type: String, default: 'My App'
-    option :environment, type: Symbol, env_variable: 'RACK_ENV'
-    option :database, type: DatabaseConfig
-
-    def initialize(params = {})
-      params.each do |name, value|
-        set_value(name, value)
-      end
+  include ConfigSL::DSL
+  include ConfigSL::Format
+  include ConfigSL::FromEnvironment
+
+  option :name, type: String, default: 'My App'
+  option :environment, type: Symbol, env_variable: 'RACK_ENV'
+  option :database, type: DatabaseConfig
+
+  def initialize(params = {})
+    params.each do |name, value|
+      set_value(name, value)
     end
+  end
 end
 ```
 
@@ -101,5 +122,9 @@ It's important to note that this is not limited to your defined configuration
 options, but also methods such as `register_file_format` and
 `config_file_path`.
 
+[badge-checks]: https://github.com/jamesiarmes/configsl/actions/workflows/checks.yaml/badge.svg?branch=main
 [badge-coverage]: https://coveralls.io/repos/github/jamesiarmes/configsl/badge.svg
+[badge-version]: https://badge.fury.io/rb/configsl.svg
+[checks]: https://github.com/jamesiarmes/configsl/actions/workflows/checks.yaml
 [coverage]: https://coveralls.io/github/jamesiarmes/configsl
+[rubygems]: https://rubygems.org/gems/configsl

data/lib/configsl/collection.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative 'format'
+
+module ConfigSL
+  # Support options as collections.
+  #
+  # This will format the values of the defined options when they are set on the
+  # config object. It will also format the values when they are retrieved, if
+  # they don't match their defined type.
+  #
+  # The default behavior is to cast the value as the defined type. If the value
+  # is nil, it will be returned as is.
+  #
+  # @example Use the shorthand syntax to define a collection with no additional
+  #   options
+  #
+  #   class TestConfig < ConfigSL::Config
+  #     include ConfigSL::Collection
+  #
+  #     option :subarray, type: Array, collection: SubConfig
+  #     option :subhash, type: Hash, collection: SubConfig
+  #   end
+  #
+  # @example Automatically set a key on the collection members based on their
+  #   index (arrays) or keys (hashes), unless the key is already set
+  #
+  #   class TestConfig < ConfigSL::Config
+  #     include ConfigSL::Collection
+  #
+  #     option :subarray, type: Array, collection: { type: SubConfig, key: :index }
+  #     option :subhash, type: Hash, collection: { type: SubConfig, key: :name }
+  #   end
+  module Collection
+    def self.included(base)
+      base.include(Format) unless base.include?(Format)
+      base.extend ClassMethods
+    end
+
+    # Class methods necessary for defining collection options.
+    module ClassMethods
+      # @see DSL#option
+      def option(name, opts = {})
+        # If the option was set using the shorthand syntax, convert it to an
+        # options hash for consistent handling.
+        opts[:collection] = { type: opts[:collection], key: nil } \
+          if opts[:collection].is_a?(Class)
+
+        super
+      end
+    end
+
+    private
+
+    # @see DSL#set_value
+    #
+    # @raise [InvalidValueError] If the value is not of the expected type.
+    def set_value(name, value)
+      configsl_option_exists!(name)
+      if configsl_collection?(name) &&
+         !value.nil? &&
+         !value.is_a?(options[name][:type])
+        # If the option is a collection, we want to make sure the value is of the
+        # expected type.
+        raise InvalidValueError,
+              "Invalid value type (#{value.class}) for collection " \
+              "option #{name}; expected #{options[name][:type]}"
+      end
+
+      super
+    end
+
+    # Determines if an option is a collection.
+    #
+    # @param option [Symbol] Option to check.
+    # @return [Boolean]
+    def configsl_collection?(option)
+      options[option].fetch(:collection, false) &&
+        [Array, Hash].include?(options[option][:type])
+    end
+
+    # Determines if the values in a collection have been collected.
+    #
+    # @param option [Symbol] Option being checked.
+    # @param values [Array, Hash] Values for the option.
+    # @return [Boolean]
+    def configsl_collected?(option, values)
+      return true if values.empty?
+
+      value = options[option][:type] == Array ? values.first : values.values.first
+      value.is_a?(options[option][:collection][:type])
+    end
+
+    # Collects values into an appropriate collection.
+    #
+    # @param option [Symbol] Option whose values are being collected.
+    # @param values [Array, Hash] Values to collect.
+    # @return [Array, Hash] Collected values as the defined type.
+    #
+    # @raise [InvalidValueError] If the values are not of the correct type.
+    def configsl_collect_values(option, values)
+      return values if configsl_collected?(option, values)
+
+      if values.is_a?(Hash)
+        configsl_collect_hash(option, values)
+      else
+        configsl_collect_array(option, values)
+      end
+    end
+
+    # Collect values for an array collection.
+    #
+    # @param option [Symbol] Option being processed.
+    # @param values [Array] Values to collect.
+    # @return [Array] Collected values.
+    def configsl_collect_array(option, values)
+      values.map.with_index do |value, index|
+        configsl_collect_value(option, value, index)
+      end
+    end
+
+    # Collect values for a hash collection.
+    #
+    # @param option [Symbol] Option being processed.
+    # @param values [Hash] Values to collect.
+    # @return [Hash] Collected values.
+    def configsl_collect_hash(option, values)
+      values.to_h do |key, value|
+        configsl_collect_value(option, [key, value], key)
+      end
+    end
+
+    # Collect a single value to be added to the collection.
+    #
+    # @param option [Symbol] Option whose value is being collected.
+    # @param value [Object] The value to be added to the collection.
+    # @return [Array, Hash]
+    def configsl_collect_value(option, value, index = nil)
+      is_array = options[option][:type] == Array
+      params = is_array ? value : value[1]
+      configsl_collection_key(params, options[option][:collection][:key], index)
+
+      config = options[option][:collection][:type].new(params)
+      is_array ? config : [value[0], config]
+    end
+
+    def configsl_collection_key(value, key, index)
+      return if key.nil? || index.nil?
+      return value[key] unless value[key].nil?
+
+      value[key] = index
+    end
+
+    # @see Format#format_value
+    def format_value(option, value)
+      return super unless configsl_collection?(option)
+
+      return configsl_collect_values(option, value) unless value.nil? || value.empty?
+
+      formatter = Format::FORMATTERS[options[option][:type]]
+      value.send(formatter)
+    end
+  end
+end

data/lib/configsl/config.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
+require_relative 'collection'
 require_relative 'dsl'
 require_relative 'file_format/json'
 require_relative 'file_format/yaml'
 require_relative 'format'
 require_relative 'from_environment'
 require_relative 'from_file'
+require_relative 'merge'
+require_relative 'to_hash'
 require_relative 'validation'
 
 module ConfigSL
@@ -15,7 +18,10 @@ module ConfigSL
     include Format
     include FromEnvironment
     include FromFile
+    include ToHash
     include Validation
+    include Collection
+    include Merge
 
     def initialize(params = {})
       params.each do |name, value|

data/lib/configsl/dsl.rb

@@ -46,13 +46,13 @@ module ConfigSL
     # If the option is not set, it will return the default value.
     #
     # @param name [Symbol] The name of the option.
-    # @return [Object] The value of the option.
+    # @return [Object, nil] The value of the option.
     #
     # @raise [InvalidOptionError] If the option is not defined.
     def get_value(name)
-      raise InvalidOptionError, "Option #{name} is not defined" unless options.key?(name)
+      configsl_option_exists!(name)
 
-      @params.fetch(name, options[name]&.[](:default))
+      configsl_params.fetch(name, options[name]&.[](:default))
     end
 
     # Sets the value of an option.
@@ -63,10 +63,27 @@ module ConfigSL
     #
     # @raise [InvalidOptionError] If the option is not defined.
     def set_value(name, value)
-      raise InvalidOptionError, "Option #{name} is not defined" unless options.key?(name)
+      configsl_option_exists!(name)
 
-      @params ||= {}
-      @params[name] = value
+      configsl_params[name] = value
+    end
+
+    # Validates that an option exists for the current configuration class.
+    #
+    # @param name [Symbol] Name of the option to validate.
+    #
+    # @raise [InvalidOptionError] If the option is not defined.
+    def configsl_option_exists!(name)
+      return if options.key?(name)
+
+      raise InvalidOptionError, "Option #{name} is not defined"
+    end
+
+    # Returns the params hash for the class of the current instance.
+    #
+    # @return [Hash] The params hash.
+    def configsl_params
+      @configsl_params ||= {}
     end
 
     # Required class methods for the config DSL.
@@ -80,8 +97,10 @@ module ConfigSL
       # @param opts [Hash] The options for the option.
       # @return [void]
       def option(name, opts = {})
-        options.merge!({ name => opts })
+        options[name] = opts
+
         define_method(name) { get_value(name) }
+        define_method("#{name}=") { |val| set_value(name, val) }
       end
 
       # Returns the options hash for the class.

data/lib/configsl/exception.rb

@@ -2,4 +2,5 @@
 
 module ConfigSL
   class InvalidOptionError < ArgumentError; end
+  class InvalidValueError < ArgumentError; end
 end

data/lib/configsl/file_support.rb

@@ -72,8 +72,6 @@ module ConfigSL
         @config_file_formats[format] = opts
       end
 
-      private
-
       # Find the configuration file based on the default path, name, and defined
       # formats.
       #
@@ -91,7 +89,7 @@ module ConfigSL
       #   provided, will only match files of the given format. Ignored if `path`
       #   is provided.
       # @return [Array<String>] Array of matching files.
-      def find_file(path: nil, format: nil)
+      def configsl_find_file(path: nil, format: nil)
         paths = Dir.glob(
           path.nil? ? "#{config_file_name}.{#{file_extensions(format:).join(',')}}" : path,
           base: path.nil? ? config_file_path : nil
@@ -99,7 +97,7 @@ module ConfigSL
 
         raise FileNotFoundError, 'No configuration file found!' if paths.empty?
 
-        paths.map { |p| File.join(config_file_path, p) }
+        path.nil? ? paths.map { |p| File.join(config_file_path, p) } : paths
       end
 
       # Find the format for a file given its extension.
@@ -109,7 +107,7 @@ module ConfigSL
       #
       # @raise [FileFormatError] If no file formats have been defined.
       # @raise [FileFormatError] If no file format is found for the extension.
-      def find_file_format(extension)
+      def configsl_find_file_format(extension)
         raise FileFormatError, 'No file formats have been defined' if @config_file_formats.nil?
 
         extension = extension.sub(/^\./, '').to_sym
@@ -119,6 +117,28 @@ module ConfigSL
 
         raise FileFormatError, "No file format found for extension: #{extension}"
       end
+
+      private
+
+      # Deprecated: Use configsl_find_file instead.
+      def find_file(path: nil, format: nil)
+        warn '[ConfigSL] DEPRECATION WARNING: ' \
+             '`find_file` is deprecated. ' \
+             'Use `configsl_find_file` instead. ' \
+             "Called from: #{caller(1..1).first}",
+             category: :deprecated
+        configsl_find_file(path:, format:)
+      end
+
+      # Deprecated: Use configsl_find_file_format instead.
+      def find_file_format(extension)
+        warn '[ConfigSL] DEPRECATION WARNING: ' \
+             '`find_file_format` is deprecated. ' \
+             'Use `configsl_find_file_format` instead. ' \
+             "Called from: #{caller(1..1).first}",
+             category: :deprecated
+        configsl_find_file_format(extension)
+      end
     end
   end
 end

data/lib/configsl/format.rb

@@ -39,6 +39,10 @@ module ConfigSL
       super(name, format_value(name, value))
     end
 
+    # Formats a value based on its option definition.
+    #
+    # @param option [Symbol] Option whose value is being formatted.
+    # @param value [Object] Value for the option.
     def format_value(option, value)
       return value if value.nil? || value.is_a?(options[option][:type])
 

data/lib/configsl/from_environment.rb

@@ -21,6 +21,28 @@ module ConfigSL
       base.from_environment_prefix ''
     end
 
+    def self.configsl_source_name
+      :environment
+    end
+
+    # Loads the configuration parameters from environment variables.
+    #
+    # @param klass [Class] The class loading the configuration.
+    # @param opts [Hash] Options for loading the configuration.
+    # @option opts [Boolean] :defaults Whether to populate default values,
+    #   defaults to `true`
+    # @return [Hash] Loaded configuration parameters.
+    def self.configsl_load_params(klass, opts = {})
+      klass.options.each_with_object({}) do |(name, option_opts), hash|
+        env_var = option_opts[:env_variable] || name.to_s.upcase
+        if ENV.key?(env_var)
+          hash[name] = ENV[env_var]
+        elsif opts[:defaults]
+          hash[name] = option_opts[:default]
+        end
+      end
+    end
+
     # Class methods necessary for loading configuration from the environment.
     module ClassMethods
       # Set the prefix for environment variables.
@@ -34,10 +56,7 @@ module ConfigSL
       #
       # @return [self] The new config object
       def from_environment
-        params = options.transform_values do |opts|
-          ENV.fetch(opts[:env_variable], opts[:default])
-        end
-
+        params = FromEnvironment.configsl_load_params(self, defaults: true)
         new(params)
       end
 

data/lib/configsl/from_file.rb

@@ -32,6 +32,46 @@ module ConfigSL
       base.extend(ClassMethods)
     end
 
+    def self.configsl_source_name
+      :file
+    end
+
+    # Loads the configuration parameters from a file.
+    #
+    # @param klass [Class] The class loading the configuration.
+    # @param opts [Hash] Options for loading the configuration.
+    # @option opts [String] :path Optional path to the file to load; uses the
+    #   default path and filename if not specified.
+    # @option opts [Symbol] :format Optional format to use for the file; uses
+    #   the file extension if not specified.
+    # @option opts [Boolean] :defaults Whether to populate default values,
+    #   defaults to `true`.
+    # @return [Hash] Loaded configuration parameters.
+    def self.configsl_load_params(klass, opts = {})
+      formats = klass.instance_variable_get(:@config_file_formats) || {}
+      return {} if formats.empty?
+
+      path = opts[:path] || klass.configsl_find_file.first
+      format = opts[:format] || klass.configsl_find_file_format(File.extname(path))
+      data = formats[format][:class].new(path).read
+
+      populate_defaults(klass, data) if opts[:defaults]
+      data
+    end
+
+    # Populates default values for unset options.
+    #
+    # @param klass [Class] The class loading the configuration.
+    # @param data [Hash] Configuration parameters.
+    def self.populate_defaults(klass, data)
+      klass.options.each do |name, option_opts|
+        name_sym = name.to_sym
+        next if data.key?(name_sym) || data.key?(name.to_s)
+
+        data[name_sym] = option_opts[:default]
+      end
+    end
+
     # Required class methods for loading config files.
     module ClassMethods
       # Loads configuration from a file.
@@ -46,10 +86,8 @@ module ConfigSL
       #   file extension if not specified.
       # @return [self]
       def from_file(path = nil, format: nil)
-        path ||= find_file.first
-        format ||= find_file_format(File.extname(path))
-        file = @config_file_formats[format][:class].new(path)
-        new(file.read)
+        params = FromFile.configsl_load_params(self, path:, format:, defaults: true)
+        new(params)
       end
     end
   end

data/lib/configsl/merge.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module ConfigSL
+  # Support merging configurations from multiple sources based on precedence.
+  module Merge
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Class methods to manage precedence and loading of sources.
+    module ClassMethods
+      # Load config from all available sources and merge them in order.
+      #
+      # @param params [Hash] Configuration parameters to merge in at the highest
+      #   precedence.
+      # @param source_options [Hash] Optional per-source configuration options.
+      # @return [self] Configuration object with merged parameters.
+      def load(params = {}, source_options = {})
+        merged_params = configsl_load_merged_params(params, source_options)
+        new(merged_params)
+      end
+
+      # Set or get precedence order
+      #
+      # @param sources [Array<Symbol>] List of sources in order of priority,
+      #   highest to lowest precedence.
+      # @return [Array<Symbol>] Full list of sources in precedence order.
+      def precedence(*sources)
+        sources = sources.flatten
+        if sources.any?
+          configsl_validate_precedence_sources(sources)
+          @precedence = sources
+        else
+          @precedence || configsl_default_precedence
+        end
+      end
+
+      # Return the available sources dynamically discovered from ancestors
+      #
+      # @return [Array<Symbol>]
+      def configsl_available_sources
+        [:params] + ancestors.select { |ancestor| ancestor.respond_to?(:configsl_source_name) }
+                             .map(&:configsl_source_name)
+      end
+
+      private
+
+      # Returns the default precedence order.
+      #
+      # +:params+ has the highest precedence, followed by included sources in
+      # the order they were included.
+      #
+      # @return [Array<Symbol>] Default source precedence order.
+      def configsl_default_precedence
+        # Ancestors are listed in reverse order of inclusion, so we filter
+        # modules that are config sources and reverse the array to order them by
+        # inclusion.
+        modules = ancestors.select { |ancestor| ancestor.respond_to?(:configsl_source_name) }
+        [:params] + modules.reverse.map(&:configsl_source_name)
+      end
+
+      # Loads configs from all available sources and merges them in order.
+      #
+      # @param params [Hash] Configuration parameters to merge in at the highest
+      #   precedence.
+      # @param opts [Hash] Optional per-source configuration options.
+      # @return [Hash] Merged parameters.
+      def configsl_load_merged_params(params = {}, opts = {})
+        params = params.is_a?(Hash) ? params.transform_keys(&:to_sym) : {}
+        sources = { params: params }
+
+        configsl_load_sources(sources, opts)
+        configsl_merge_sources_by_precedence(sources)
+      end
+
+      # Loads configuration data from all registered config sources.
+      #
+      # If an explicit precedence has been defined, only sources configured in
+      # the chain will be loaded.
+      #
+      # @param sources [Hash{Symbol => Hash}] Hash for loaded sources.
+      # @param opts [Hash] Optional per-source configuration options.
+      def configsl_load_sources(sources, opts = {})
+        ancestors.each do |ancestor|
+          next unless ancestor.respond_to?(:configsl_source_name)
+
+          source_name = ancestor.configsl_source_name.to_sym
+          next unless precedence.include?(source_name)
+
+          source_opts = opts[source_name] || {}
+          sources[source_name] ||=
+            ancestor.configsl_load_params(self, source_opts)
+        end
+      end
+
+      # Merges all loaded configuration sources in precedence order.
+      #
+      # @param sources [Hash{Symbol => Hash}] Loaded configuration hashes.
+      # @return [Hash] Merged configuration parameters.
+      def configsl_merge_sources_by_precedence(sources)
+        merged = {}
+        precedence.reverse_each do |source|
+          merged.merge!(sources[source] || {})
+        end
+
+        merged
+      end
+
+      # Validates that all specified precedence sources are available.
+      #
+      # @param sources [Array<Symbol>] The sources to validate.
+      #
+      # @raise [ArgumentError] If any source is invalid.
+      def configsl_validate_precedence_sources(sources)
+        invalid = sources - configsl_available_sources
+        return if invalid.empty?
+
+        msg = "Invalid precedence sources: #{invalid.join(', ')}. " \
+              "Available: #{configsl_available_sources.join(', ')}"
+        raise ArgumentError, msg
+      end
+    end
+  end
+end

data/lib/configsl/to_hash.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ConfigSL
+  # Converts a configuration value to a hash structure.
+  module ToHash
+    def to_h
+      configsl_params.to_h { |k, v| [k, configsl_serialize_value(v)] }
+    end
+
+    private
+
+    # Recursively serializes configuration values.
+    #
+    # @param val [Object] Value to serialize.
+    # @return [Object] Serialized value.
+    def configsl_serialize_value(val)
+      case val
+      when nil then nil
+      when Array then configsl_serialize_array(val)
+      when Hash then configsl_serialize_hash(val)
+      else val.respond_to?(:to_h) ? val.to_h : val
+      end
+    end
+
+    # Serializes array values.
+    #
+    # @param array [Array] Array to serialize.
+    # @return [Array] Serialized array.
+    def configsl_serialize_array(array)
+      array.map { |item| configsl_serialize_value(item) }
+    end
+
+    # Serializes hash values.
+    #
+    # @param hash [Hash] Hash to serialize.
+    # @return [Hash] Serialized hash.
+    def configsl_serialize_hash(hash)
+      hash.transform_values { |item| configsl_serialize_value(item) }
+    end
+  end
+end

data/lib/configsl/version.rb

@@ -2,6 +2,6 @@
 
 # :nocov:
 module ConfigSL
-  VERSION = '1.0.2'
+  VERSION = '1.1.1'
 end
 # :nocov:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: configsl
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.1
 platform: ruby
 authors:
 - James I. Armes
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-15 00:00:00.000000000 Z
+date: 2026-07-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: facets
@@ -36,6 +36,7 @@ files:
 - Gemfile
 - README.md
 - lib/configsl.rb
+- lib/configsl/collection.rb
 - lib/configsl/config.rb
 - lib/configsl/dsl.rb
 - lib/configsl/exception.rb
@@ -47,6 +48,8 @@ files:
 - lib/configsl/format.rb
 - lib/configsl/from_environment.rb
 - lib/configsl/from_file.rb
+- lib/configsl/merge.rb
+- lib/configsl/to_hash.rb
 - lib/configsl/validation.rb
 - lib/configsl/version.rb
 homepage: https://github.com/jamesiarmes/configsl
@@ -58,7 +61,7 @@ metadata:
   homepage_uri: https://github.com/jamesiarmes/configsl
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/jamesiarmes/configsl
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -66,7 +69,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -74,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.9
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A simple DSL for declarative configuration in ruby.
 test_files: []