adaptiveconfiguration 1.0.0.beta01

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40a0689cda0cd8ceb25859afd3c06379667fb296d3a2a90dbf027f00d8fb6454
+  data.tar.gz: cf253ace46d9f2d634a9b578653c16a12e6909c517c53cd19d0b584e17111819
+SHA512:
+  metadata.gz: f2af0a82072944057dca43e2c4a294c42cdb140e1433e2fdedd7d353e92df0d97e6e9736b45e00d7e391d7f7bb40336b6b631626e972f7d1e4d10888b3abf0b9
+  data.tar.gz: 04a3bee03bffff23ab8b13157b2e5c7fd589d435f18870f709b4c176342d402fdf6f9bf16ed4734fc7172e5d07385808fda56fcf36287fd170bf5799d8af6a1a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Endless International
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,559 @@
+# AdaptiveConfiguration
+
+**AdaptiveConfiguration** is a powerful and flexible Ruby gem that allows you to define a DSL 
+(Domain-Specific Language) for structured and hierarchical configurations. It is ideal for defining 
+complex configurations for various use cases, such as API clients, application settings, or 
+any scenario where structured configuration is needed. 
+
+In addition AdaptiveConfiguration can be more generally used to transform and validate JSON data 
+from any source such as network request or API reponse.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'adaptiveconfiguration'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install adaptiveconfiguration
+```
+
+## Usage
+
+### Requiring the Gem
+
+To start using the `adaptiveconfiguration` gem, simply require it in your Ruby application:
+
+```ruby
+require 'adaptiveconfiguration'
+```
+
+### Defining Configurations with AdaptiveConfiguration
+
+AdaptiveConfiguration permits the caller to define a domain specific language +Builder+ 
+specifying parameters, parameter collections, and related options. This builder can then 
+be used to build or validate the configuration using the domain specific language. 
+
+---
+
+## Parameters
+
+**Parameters** are the basic building blocks of your configuration. They represent individual 
+settings or options that you can define with specific types, defaults, and other attributes.
+
+When defining a parameter, you specify its name and optionally type, default and alias.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+# define a configuration structure with parameters
+configuration = AdaptiveConfiguration::Builder.new do
+  parameter :api_key, String
+  parameter :version, String, default: '1.0'
+end
+
+# build the configuration and set values
+result = configuration.build! do
+  api_key 'your-api-key'
+end
+
+# access the configuration values
+puts result[:api_key]   # => "your-api-key"
+puts result[:version]   # => "1.0"
+```
+
+**Notes:**
+
+- **Defining Parameters:**
+  - `parameter :api_key, String` defines a parameter named `:api_key` with the type `String`.
+  - `parameter :version, String, default: '1.0'` defines a parameter with a default value.
+- **Building the Configuration:**
+  - `configuration.build!` creates a context where you can set values for the parameters.
+  - Inside the block, `api_key 'your-api-key'` sets the value of `:api_key`.
+- **Accessing Values:**
+  - `result[:api_key]` retrieves the value of `:api_key`.
+  - If a parameter has a default and you don't set it, it uses the default value.
+
+---
+
+## Groups
+
+**Groups** allow you to organize related parameters into nested structures. This is useful for 
+logically grouping settings and creating hierarchical configurations.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+configuration = AdaptiveConfiguration::Builder.new do
+  parameter :api_key, String
+  group :chat_options do
+    parameter :model, String, default: 'claude-3'
+    parameter :max_tokens, Integer, default: 1000
+    parameter :temperature, Float, default: 0.5
+    parameter :stream, TrueClass
+  end
+end
+
+result = configuration.build! do
+  api_key 'your-api-key'
+  chat_options do
+    temperature 0.8
+    stream true
+  end
+end
+
+# Accessing values
+puts result[:api_key]                     # => "your-api-key"
+puts result[:chat_options][:model]        # => "claude-3"
+puts result[:chat_options][:temperature]  # => 0.8
+puts result[:chat_options][:stream]       # => true
+```
+
+**Notes:**
+
+- **Defining a Group:**
+  - `group :chat_options do ... end` defines a group named `:chat_options`.
+  - Inside the group, you can define parameters that belong to that group.
+- **Setting Values in Groups:**
+  - In the build block, you can set values for parameters within groups by nesting blocks.
+  - `chat_options do ... end` allows you to set parameters inside the `:chat_options` group.
+- **Accessing Values:**
+  - You access group parameters by chaining the keys: `result[:chat_options][:model]`.
+
+---
+
+## Array Parameters
+
+**Array Parameters** allow you to define parameters that can hold multiple values. This is 
+useful when you need to collect lists of items, such as headers, tags, or multiple 
+configuration entries.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+configuration = AdaptiveConfiguration::Builder.new do
+  parameter :api_key, String
+  group :request_options do
+    parameter :headers, String, array: true
+  end
+end
+
+result = configuration.build! do
+  api_key 'your-api-key'
+  request_options do
+    headers ['Content-Type: application/json', 'Authorization: Bearer token']
+  end
+end
+
+# Accessing array parameter
+puts result[:request_options][:headers]
+# => ["Content-Type: application/json", "Authorization: Bearer token"]
+```
+
+**Notes:**
+
+- **Defining an Array Parameter:**
+  - `parameter :headers, String, array: true` defines `:headers` as an array parameter of type `String`.
+- **Setting Values:**
+  - You can assign an array of values to `headers`.
+- **Accessing Values:**
+  - The values are stored as an array, and you can access them directly.
+
+---
+
+## The `:as` Option
+
+The `:as` option allows you to map the parameter's name in your DSL to a different key in the 
+resulting configuration. This is useful when you need to conform to specific key names required 
+by APIs or other systems, while still using friendly method names in your configuration blocks.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+configuration = AdaptiveConfiguration::Builder.new do
+  parameter :api_key, String, as: :apiKey
+  group :user_settings, as: :userSettings do
+    parameter :user_name, String, as: :userName
+  end
+end
+
+result = configuration.build! do
+  api_key 'your-api-key'
+  user_settings do
+    user_name 'john_doe'
+  end
+end
+
+# Accessing values with mapped keys
+puts result[:apiKey]                    # => "your-api-key"
+puts result[:userSettings][:userName]  # => "john_doe"
+```
+
+**Notes:**
+
+- **Using the `:as` Option:**
+  - `parameter :apiKey, String, as: :api_key` defines a parameter that you set using `apiKey`, 
+     but it's stored as `:api_key` in the result.
+  - Similarly, `group :userSettings, as: :user_settings` maps the group name.
+- **Setting Values:**
+  - In the build block, you use the original names (`apiKey`, `userSettings`), but the values 
+    are stored under the mapped keys.
+- **Accessing Values:**
+  - You access the values using the mapped keys (`:api_key`, `:user_settings`, `:user_name`).
+
+---
+
+## Default Values
+
+The `default` option allows you to specify a default value for a parameter. If you do not set 
+a value for that parameter during the build phase, it automatically uses the default.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+configuration = AdaptiveConfiguration::Builder.new do
+  parameter :api_key, String, default: 'default-api-key'
+  group :settings do
+    parameter :timeout, Integer, default: 30
+    parameter :retries, Integer, default: 3
+  end
+end
+
+result = configuration.build! do
+  # No need to set api_key or settings parameters unless you want to override defaults
+end
+
+# Accessing default values
+puts result[:api_key]              # => "default-api-key"
+puts result[:settings][:timeout]   # => 30
+puts result[:settings][:retries]   # => 3
+```
+
+**Notes:**
+
+- **Defining Defaults:**
+  - Parameters like `:api_key` have a default value specified with `default: 'default-api-key'`.
+- **Building Without Setting Values:**
+  - If you do not provide values during the build phase, the defaults are used.
+- **Accessing Values:**
+  - The result contains the default values for parameters you didn't set.
+
+---
+
+## Type Conversion
+
+AdaptiveConfiguration automatically handles type conversion based on the parameter's specified 
+type. If you provide a value that can be converted to the specified type, it will do so. 
+If conversion fails, it raises a `TypeError`.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+configuration = AdaptiveConfiguration::Builder.new do
+  parameter :max_tokens, Integer
+  parameter :temperature, Float
+  parameter :start_date, Date
+end
+
+result = configuration.build! do
+  max_tokens '1500'       # String that can be converted to Integer
+  temperature '0.75'      # String that can be converted to Float
+  start_date '2023-01-01' # String that can be converted to Date
+end
+
+# Accessing converted values
+puts result[:max_tokens]   # => 1500 (Integer)
+puts result[:temperature]  # => 0.75 (Float)
+puts result[:start_date]   # => #<Date: 2023-01-01 ...>
+```
+
+**Notes:**
+
+- **Type Conversion:**
+  - AdaptiveConfiguration converts `'1500'` to `1500` (Integer).
+  - Converts `'0.75'` to `0.75` (Float).
+  - Converts `'2023-01-01'` to a `Date` object.
+- **Error Handling:**
+  - If you provide a value that cannot be converted, it raises a `TypeError`.
+
+---
+
+## Custom Converters
+
+You can define custom converters for your own types, allowing you to extend the framework's capabilities.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+# define a custom class
+class UpcaseString < String
+  def initialize( value )
+    super( value.to_s.upcase )
+  end
+end
+
+configuration = AdaptiveConfiguration::Builder.new do
+  convert( UpcaseString ) { | v | UpcaseString.new( v ) }
+  parameter :name, UpcaseString
+end
+
+result = configuration.build! do
+  name 'john doe'
+end
+
+# Accessing custom converted value
+puts result[:name]          # => "JOHN DOE"
+puts result[:name].class    # => UpcaseString
+```
+
+**Notes:**
+
+- **Defining a Custom Converter:**
+  - `convert( UpcaseString ) { | v | UpcaseString.new( v ) }` tells the builder how to convert 
+    values to `UpcaseString`.
+- **Using Custom Types:**
+  - `parameter :name, UpcaseString` defines a parameter of the custom type.
+- **Conversion Behavior:**
+  - When you set `name 'john doe'`, it converts it to `'JOHN DOE'` and stores it as an instance 
+    of `UpcaseString`.
+
+---
+
+Certainly! Let's expand the first paragraph and complete the explanation in the section you added to the README.
+
+---
+
+## Transforming and Validating JSON Data
+
+AdaptiveConfiguration can also be utilized to transform and validate JSON data. By defining parameters and groups 
+that mirror the expected structure of your JSON input, you can map and coerce incoming data into the desired format 
+seamlessly. 
+
+The `:as` option allows you to rename keys during this transformation process, ensuring that your data conforms to 
+specific API requirements or internal data models. Moreover, AdaptiveConfiguration provides built-in validation by 
+raising exceptions when the input data contains unexpected elements or elements of the wrong type, helping you 
+maintain data integrity and catch errors early in your data processing pipeline.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+# Define the expected structure of the JSON data
+configuration = AdaptiveConfiguration::Builder.new do
+  parameter :api_key, String
+  group :user, as: :user_info do
+    parameter :name, String
+    parameter :email, String
+    parameter :age, Integer
+  end
+  group :preferences, as: :user_preferences do
+    parameter :notifications_enabled, TrueClass
+    parameter :theme, String, default: 'light'
+  end
+end
+
+# sample JSON data as a Hash (e.g., parsed from JSON/YAML or API response
+input_data = {
+  'api_key' => 'your-api-key',
+  'user' => {
+    'name' => 'John Doe',
+    'email' => 'john@example.com',
+    'age' => '30'  # age is a String that should be converted to Integer
+  },
+  'preferences' => {
+    'notifications_enabled' => 'true',  # Should be converted to TrueClass
+    'theme' => 'dark'
+  },
+  'extra_field' => 'unexpected'  # This field is not defined in the configuration
+}
+
+# build the configuration context using the input data
+begin
+  
+  result = configuration.build!( input_data )
+
+  # Access transformed and validated data
+  puts result[:api_key]                      # => "your-api-key"
+  puts result[:user_info][:name]             # => "John Doe"
+  puts result[:user_info][:age]              # => 30 (Integer)
+  puts result[:user_preferences][:theme]     # => "dark"
+
+rescue TypeError => e
+  puts "Validation Error: #{e.message}"
+end
+```
+
+**Explanation:**
+
+- **Defining the Structure:**
+  - **Parameters and Groups:**
+    - We define a configuration that reflects the expected structure of the input JSON data.
+    - `parameter :api_key, String` defines the API key parameter.
+    - `group :user, as: :user_info` defines a group for user data, which will be transformed to the key `:user_info` in the result.
+    - Inside the `:user` group, we define parameters for `:name`, `:email`, and `:age`.
+    - `group :preferences, as: :user_preferences` defines a group for user preferences, transformed to `:user_preferences`.
+  - **Using the `:as` Option:**
+    - The `:as` option renames the group keys in the resulting configuration, allowing the internal DSL names to differ from the output keys.
+
+- **Building the Configuration Context:**
+  - **Using `build!`:**
+    - We use the `build!` method to enforce strict validation. If any type coercion fails or if unexpected elements are present, it raises an exception.
+  - **Setting Values from Input Data:**
+    - We set the values by extracting them from the `input_data` hash.
+    - For example, `api_key input_data['api_key']` sets the `:api_key` parameter.
+    - Within the `user` and `preferences` groups, we set the nested parameters accordingly.
+
+- **Type Conversion and Coercion:**
+  - **Automatic Conversion:**
+    - The gem attempts to coerce input values to the specified types.
+    - `'30'` (String) is converted to `30` (Integer) for the `:age` parameter.
+    - `'true'` (String) is converted to `true` (TrueClass) for `:notifications_enabled`.
+  - **Error Handling:**
+    - If the input value cannot be coerced to the specified type, a `TypeError` is raised.
+    - For instance, if `'thirty'` were provided for `:age`, it would raise a `TypeError` because it cannot be converted to an Integer.
+
+- **Validation:**
+  - **Unexpected Elements:**
+    - The `build!` method currently does not raise an exception for unexpected keys in the input data (like `'extra_field'`), but these keys are ignored.
+    - If you require strict validation against unexpected keys, additional validation logic would need to be implemented.
+  - **Type Enforcement:**
+    - The gem enforces that the values match the expected types, ensuring data integrity.
+    - This helps catch errors early, preventing invalid data from propagating through your application.
+
+- **Transformation:**
+  - **Key Renaming:**
+    - The use of the `:as` option transforms the internal parameter and group names to match the desired output keys.
+    - This is particularly useful when the input data keys do not align with the output format required by your application or when interfacing with external APIs.
+  - **Structuring Data:**
+    - By defining the configuration structure, you effectively map and reorganize the input data into a format that suits your needs.
+
+- **Accessing Transformed Data:**
+  - **Resulting Configuration:**
+    - The `result` object contains the transformed and validated data.
+    - You can access the data using the mapped keys, such as `result[:user_info][:name]`.
+  - **Usage in Application:**
+    - The validated and transformed data is now ready for use within your application, confident that it adheres to the expected structure and types.
+
+**Note:**
+
+- **Extending Validation:**
+  - If you need to validate against unexpected keys (e.g., to ensure there are no extra fields in the input data), you can extend the gem's functionality.
+  - This could involve comparing the keys in the input data with the defined parameters and raising an error if discrepancies are found.
+- **Flexible Handling:**
+  - For scenarios where you prefer not to raise exceptions on type coercion failures, you can use the `build` method instead of `build!`.
+  - The `build` method will attempt type coercion but will retain the original value if coercion fails, without raising an exception.
+
+
+By leveraging AdaptiveConfiguration in this way, you can create robust data transformation and validation pipelines that simplify handling complex JSON data structures, ensuring your application receives data that is correctly typed and structured.
+
+---
+
+## Complex Example with Nested Groups and Arrays
+
+Here's a comprehensive example that combines parameters, groups, array parameters, and defaults.
+
+### Example:
+
+```ruby
+require 'adaptiveconfiguration'
+
+configuration = AdaptiveConfiguration::Builder.new do
+  parameter :api_key, String
+  group :chat_options do
+    parameter :model, String, default: 'claude-3-5'
+    parameter :max_tokens, Integer, default: 2000
+    parameter :temperature, Float, default: 0.7
+    parameter :stream, TrueClass
+    parameter :stop_sequences, String, array: true
+
+    group :metadata do
+      parameter :user_id, String
+      parameter :session_id, String
+    end
+  end
+
+  group :message, as: :messages, array: true do
+    parameter :role, String
+    parameter :content, String
+  end
+end
+
+result = configuration.build! do
+  api_key 'your-api-key'
+
+  chat_options do
+    temperature 0.5
+    stop_sequences ['end', 'stop']
+    metadata do
+      user_id 'user-123'
+      session_id 'session-456'
+    end
+  end
+
+  message do
+    role 'system'
+    content 'You are a helpful assistant.'
+  end
+
+  message do
+    role 'user'
+    content 'Hello!'
+  end
+end
+
+# Accessing values
+puts result[:api_key]                            # => "your-api-key"
+puts result[:chat_options][:model]               # => "claude-3-5"
+puts result[:chat_options][:temperature]         # => 0.5
+puts result[:chat_options][:metadata][:user_id]  # => "user-123"
+puts result[:messages].map { | msg | msg[:content] }
+# => ["You are a helpful assistant.", "Hello!"]
+```
+
+**Notes:**
+
+- **Combining Concepts:**
+  - Parameters with defaults (`:model`, `:max_tokens`).
+  - Nested groups (`:chat_options`, `:metadata`).
+  - Array parameters (`:stop_sequences`, `:messages`).
+  - Using the `:as` option to map `:message` to `:messages`.
+- **Setting Values:**
+  - Override default values by providing new ones.
+  - Add multiple messages to the `:messages` array.
+- **Accessing Values:**
+  - Use nested keys to access deeply nested values.
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/EndlessInternational/adaptive-configuration](https://github.com/EndlessInternational/adaptive-configuration).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/adaptiveconfiguration.gemspec

@@ -0,0 +1,37 @@
+Gem::Specification.new do | spec |
+
+  spec.name          = 'adaptiveconfiguration'
+  spec.version       = '1.0.0.beta01'
+  spec.authors       = [ 'Kristoph Cichocki-Romanov' ]
+  spec.email         = [ 'rubygems.org@kristoph.net' ]
+
+  spec.summary       = <<~TEXT.gsub( "\n", " " ).strip
+    An elegant, lightweight and simple yet powerful gem for building structured configuration 
+    definitions.
+  TEXT
+  spec.description   = <<~TEXT.gsub( "\n", " " ).strip
+    AdaptiveConfiguration is an elegant, lightweight and simple, yet powerful Ruby gem that allows 
+    you to define a DSL (Domain-Specific Language) for structured and hierarchical configurations. 
+    It is ideal for defining complex configurations for various use cases, such as API clients, 
+    application settings, or any scenario where structured configuration is needed. 
+
+    In addition AdaptiveConfiguration can be more generally used to transform and validate JSON 
+    data from any source such as from a network request or API reponse.
+  TEXT
+
+  spec.license       = 'MIT'
+  spec.homepage      = 'https://github.com/EndlessInternational/adaptive_configuration'
+  spec.metadata = {
+    'source_code_uri'   => 'https://github.com/EndlessInternational/adaptive_configuration',
+    'bug_tracker_uri'   => 'https://github.com/EndlessInternational/adaptive_configuration/issues',
+#    'documentation_uri' => 'https://github.com/EndlessInternational/adaptive_configuration'
+  }
+
+  spec.required_ruby_version = '>= 3.0'
+  spec.files         = Dir[ "lib/**/*.rb", "LICENSE", "README.md", "adaptiveconfiguration.gemspec" ]
+  spec.require_paths = [ "lib" ]
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'debug', '~> 1.9'
+
+end

data/lib/adaptive_configuration/builder.rb

@@ -0,0 +1,61 @@
+require_relative 'group_builder'
+require_relative 'context'
+
+# types must be included to support conversation
+require 'time'
+require 'date'
+require 'uri'
+
+module AdaptiveConfiguration 
+  class Builder < GroupBuilder
+
+    DEFAULT_CONVERTERS = {
+
+      Date        => ->( v ) { v.respond_to?( :to_date ) ? v.to_date : Date.parse( v.to_s ) },
+      Time        => ->( v ) { v.respond_to?( :to_time ) ? v.to_time : Time.parse( v.to_s ) },
+      URI         => ->( v ) { URI.parse( v.to_s ) },
+      String      => ->( v ) { String( v ) },
+      Integer     => ->( v ) { Integer( v ) },
+      Float       => ->( v ) { Float( v ) },
+      Rational    => ->( v ) { Rational( v ) },
+      Array       => ->( v ) { Array( v ) },
+      TrueClass   => ->( v ) { 
+        case v
+        when Numeric 
+          v.nonzero? ? true : nil 
+        else
+          v.to_s.match(  /\A\s*(true|yes)\s*\z/i ) ? true : nil 
+        end
+      },
+      FalseClass  => ->( v ) {  
+        case v
+        when Numeric 
+          v.zero? ? false : nil 
+        else
+          v.to_s.match(  /\A\s*(false|no)\s*\z/i ) ? false : nil 
+        end
+      }
+
+    }
+
+    def initialize
+      super
+      @converters = DEFAULT_CONVERTERS.dup 
+    end
+
+    def convert( klass, &block )
+      @converters[ klass ] = block 
+    end
+
+    def build!( values = nil, &block )
+      context = AdaptiveConfiguration::Context.new( 
+        values,
+        converters: @converters, 
+        definitions: @definitions 
+      )
+      context.instance_eval( &block ) if block
+      context
+    end
+
+  end
+end

data/lib/adaptive_configuration/configurable.rb

@@ -0,0 +1,20 @@
+require_relative 'builder'
+
+module AdaptiveConfiguration
+	module Configurable
+
+    def configuration( &block )
+      @configuration_builder ||= AdaptiveConfiguration::Builder.new 
+      @configuration_builder.instance_eval( &block )
+      @configuration_builder
+    end
+
+    def configure( attributes = nil, &block )
+      raise RuntimeError, "The adapter configuration has not been defined." \
+        if @configuration_builder.nil?
+      configuration = @configuration_builder.build!( attributes, &block )
+    end
+
+  end
+end
+

data/lib/adaptive_configuration/context.rb

@@ -0,0 +1,170 @@
+module AdaptiveConfiguration
+  class Context < BasicObject
+
+    def initialize( values = nil, definitions:, converters: )
+
+      values = values ? values.transform_keys( &:to_sym ) : {}
+      
+      @converters = converters&.dup 
+      @definitions = definitions&.dup 
+      @values = {}
+      
+      @definitions.each do | key, definition |
+        name = definition[ :as ] || key 
+        if definition[ :type ] == :group
+          context = Context.new( 
+            values[ key ] || {},
+            converters: @converters, definitions: definition[ :definitions ], 
+          )
+          @values[ name ] = context unless context.empty?
+        elsif definition.key?( :default )
+          @values[ name ] = definition[ :array ] ? 
+            ::Kernel.method( :Array ).call( definition[ :default ] ) : 
+            definition[ :default ]
+          # note: this is needed to know when an array paramter which was initially assigned
+          #       to a default should be replaced rather than appended
+          definition[ :default_assigned ] = true
+        end
+        self.__send__( key, values[ key ] ) if values[ key ]
+      end
+
+    end
+
+    def []( key )
+      @values[ key ]
+    end
+
+    def []=( key, value )
+      @values[ key ] = value
+    end
+
+    def each( &block )
+      @values.each( &block )
+    end
+
+    def merge( hash )
+      self.to_h.merge( hash )
+    end
+
+    def empty?
+      @values.empty?
+    end
+
+    def to_h
+      recursive_to_h = ->( object ) do
+        case object
+        when ::AdaptiveConfiguration::Context
+          recursive_to_h.call( object.to_h )
+        when ::Hash
+          object.transform_values { | value | recursive_to_h.call( value ) }
+        when ::Array
+          object.map { | element | recursive_to_h.call( element ) }
+        else
+          object.respond_to?( :to_h ) ? object.to_h : object
+        end
+      end
+
+      recursive_to_h.call( @values )
+    end
+
+    def to_s
+      inspect
+    end
+
+    def to_yaml
+      self.to_h.to_yaml
+    end
+
+    def inspect
+      @values.inspect
+    end
+
+    def class
+      ::AdaptiveConfiguration::Context
+    end
+
+    def is_a?( klass )
+      klass == ::AdaptiveConfiguration::Context || klass == ::BasicObject
+    end
+
+    alias :kind_of? :is_a?
+
+    def method_missing( method, *args, &block )
+
+      if @definitions.key?( method )
+
+        definition = @definitions[ method ]
+        name = definition[ :as ] || method
+
+        unless definition[ :array ] 
+          if definition[ :type ] == :group
+            context = 
+              @values[ name ] || 
+              Context.new( converters: @converters, definitions: definition[ :definitions ] )
+            context.instance_eval( &block ) if block
+            @values[ name ] = context 
+          else
+            value = args.first
+            value = _convert_value!( definition[ :type ], method, value ) if definition[ :type ] 
+            @values[ name ] = value
+          end
+        else
+          @values[ name ] = definition[ :default_assigned ] ? 
+            ::Array.new : 
+            @values[ name ] || ::Array.new
+          if definition[ :type ] == :group
+            context = Context.new( converters: @converters, definitions: definition[ :definitions ] )
+            context.instance_eval( &block ) if block
+            @values[ name ] << context 
+          else
+            values = ::Kernel.method( :Array ).call( args.first )
+            if type = definition[ :type ]
+              values = values.map { | v | _convert_value!( type, method, v ) } 
+            end
+            @values[ name ].concat( values )
+          end
+        end
+
+        definition[ :default_assigned ] = false
+        @values[ name ]
+
+      else
+        super
+      end
+
+    end
+
+    def respond_to?( method, include_private = false )
+      @definitions.key?( method ) || self.class.instance_methods.include?( method ) 
+    end
+
+    def respond_to_missing?( method, include_private = false )
+      @definitions.key?( method ) || self.class.instance_methods.include?( method ) 
+    end
+
+    private; def _convert_value!( klass, key, value )
+      return value unless klass && value
+
+      types =::Kernel.method( :Array ).call( klass ) 
+      result = nil
+
+      types.each do | type |
+        result = 
+          ( ( value.respond_to?( :is_a? ) && value.is_a?( type ) ) ? value : nil ) ||
+          @converters[ klass ].call( value ) rescue nil 
+        break if result 
+      end
+
+      if result.nil?
+        types_names = types.map( &:name ).join( ', ' )
+        ::Kernel.raise ::TypeError, <<~TEXT.gsub( /\s+/, ' ' ).strip
+          The key #{key} expects a value of type #{types_names} but received an 
+          incompatible #{value.class.name}.
+        TEXT
+      end
+
+      result
+    end
+
+  end
+end    

data/lib/adaptive_configuration/group_builder.rb

@@ -0,0 +1,42 @@
+require_relative 'context'
+
+module AdaptiveConfiguration 
+  class GroupBuilder
+
+    attr_reader :definitions
+
+    def initialize( &block )
+      @definitions = {}
+      self.instance_eval( &block ) if block_given?
+    end
+
+    def parameter( name, *args )
+      name = name.to_sym 
+      options = nil
+
+      raise NameError, "The parameter #{name} cannot be used." \
+        if AdaptiveConfiguration::Context.instance_methods.include?( name )
+
+      if args.first.is_a?( ::Hash )
+        # when called without type: parameter :stream, as: :streams
+        options = args.first
+      else
+        # when called with type: parameter :stream, Boolean, as: :streams
+        options = args[ 1 ] || {}
+        options[ :type ] = args.first
+      end
+      
+      @definitions[ name ] = options
+    end
+
+    def group( name, options = {}, &block )
+      builder = GroupBuilder.new
+      builder.instance_eval( &block ) if block
+      @definitions[ name ] = options.merge( { 
+        type: :group, 
+        definitions: builder.definitions 
+      } )
+    end
+
+  end
+end

data/lib/adaptive_configuration.rb

@@ -0,0 +1,2 @@
+require_relative 'adaptive_configuration/builder'
+require_relative 'adaptive_configuration/configurable'

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: adaptiveconfiguration
+version: !ruby/object:Gem::Version
+  version: 1.0.0.beta01
+platform: ruby
+authors:
+- Kristoph Cichocki-Romanov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-09-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+description: AdaptiveConfiguration is an elegant, lightweight and simple, yet powerful
+  Ruby gem that allows  you to define a DSL (Domain-Specific Language) for structured
+  and hierarchical configurations.  It is ideal for defining complex configurations
+  for various use cases, such as API clients,  application settings, or any scenario
+  where structured configuration is needed.   In addition AdaptiveConfiguration can
+  be more generally used to transform and validate JSON  data from any source such
+  as from a network request or API reponse.
+email:
+- rubygems.org@kristoph.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- adaptiveconfiguration.gemspec
+- lib/adaptive_configuration.rb
+- lib/adaptive_configuration/builder.rb
+- lib/adaptive_configuration/configurable.rb
+- lib/adaptive_configuration/context.rb
+- lib/adaptive_configuration/group_builder.rb
+homepage: https://github.com/EndlessInternational/adaptive_configuration
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/EndlessInternational/adaptive_configuration
+  bug_tracker_uri: https://github.com/EndlessInternational/adaptive_configuration/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.19
+signing_key:
+specification_version: 4
+summary: An elegant, lightweight and simple yet powerful gem for building structured
+  configuration  definitions.
+test_files: []