ace-config 0.1.0.beta.rc1b

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 673610da9904345d9482fa26d53c0717ef5bb3aa5a5bd7124d2ff5cf64b36a2f
+  data.tar.gz: 1b7036dcfba77239068380f9912b7a2efe0fb596e0534eebcfb329dbef58bad8
+SHA512:
+  metadata.gz: 96a2009741d8ce31cc20fb5a9a1ac22874ef9d1b67170f720826896fb364799cf7986231cd2d9a9babf3cfe07b594e67277197527eb5858661e7cbd2370e8675
+  data.tar.gz: 0d32fe09d35a104bc697a8e3e2d84286215ab7a15409ee0c54cbb4e7326a9aab7ba5e2f9afa8910b3cb66d1e0b75f3d679c929fee7c42f1d53e5067d1573a2b0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-09-12
+
+- Preview Candidate 0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 yurigitsu
+
+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,382 @@
+# ace-config
+
+Ruby gem created to simplify managing application configurations and enhance the development of other gems that require configuration management. It offers a simple interface for defining, setting, and retrieving configuration options with type validation, helping ensure configurations are correct and reliable.
+
+- **ace-config** provides built-in support for importing and exporting configurations in JSON, YAML, and Hash formats, enhancing versatility. 
+
+- **ace-config** offers various built-in types like basic types, data structures, numeric types, and time types.
+
+- **ace-config** supports infinite nested configurations and 'classy' access providing a flexible and powerful configuration management solution.
+
+
+## Features
+
+- **Simple Configuration Management**: Easily define, set, and retrieve configuration options.
+- **Type Validation**: Ensure configurations are correct with built-in type validation.
+- **Multiple Formats**: Import and export configurations in JSON, YAML, and Hash formats.
+- **Nested Configurations**: Support for infinite nested configurations for complex applications.
+- **Classy Access**: Access configurations in a 'classy' manner for better organization and readability.
+- **Built-in Types**: Utilize various built-in types including basic types, data structures, numeric types, and time types.
+- **Extensible**: Easily extendable to accommodate custom configuration needs.
+
+## Table of Contents
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Configuration Container Usage](#configuration-container-usage)
+- [DSL Syntax](#dsl-syntax)
+- Typing
+  - [Define Configuration Validation](#set-configuration-type-validation)
+  - [Declaring Validation](#configure-type-validation)
+  - [Type Schema](#type_schema)
+  - [Built-in Types](#built-in-types)
+- Import:
+  - [Loading Configurations](#loading-configuration-data)
+  - [Loading from a JSON String](#loading-from-a-json-string)
+  - [Loading from a YAML File](#loading-from-a-yaml-file)
+- Export:  
+  - [Exporting Configurations](#exporting-configuration-data)
+  - [to_h](#to_h)
+  - [to_json](#to_json)
+  - [to_yaml](#to_yaml)
+- OSS
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Code of Conduct](#code-of-conduct)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add ace-config
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install ace-config
+```
+
+## Basic Usage
+
+```ruby
+require 'ace_config'
+
+module MyApp
+  include AceConfig
+end 
+
+MyApp.configure :settings do
+  config option: 42
+  config.int typed_opt_one: 42
+  config typed_opt_two: 4.2, type: :float  
+end
+
+MyApp.settings.option                 # => 42
+MyApp.settings.typed_opt_one          # => 42
+MyApp.settings.typed_opt_two          # => 4.2
+```
+
+### Basic Syntax
+```ruby
+MyApp.configure :settings do
+  config option: 42
+end
+```
+
+## Namespacing
+```ruby
+MyApp.configure :app do
+  configure :lvl_one do
+    config opt: 100
+    configure :lvl_two do
+      config opt: 200
+      configure :lvl_three do
+        config opt: 300
+        configure :lvl_four do
+          config opt: 400
+          configure :lvl_five do
+            config opt: 500
+            # NOTE: as deep as you want
+          end
+        end
+      end
+    end
+  end
+end
+
+MyApp.app.lvl_one.opt                                     # => 100
+MyApp.app.lvl_one.lvl_two.opt                             # => 200
+MyApp.app.lvl_one.lvl_two.lvl_three.opt                   # => 300
+MyApp.app.lvl_one.lvl_two.lvl_three.lvl_four.opt          # => 400
+MyApp.app.lvl_one.lvl_two.lvl_three.lvl_four.lvl_five.opt # => 500
+```
+
+### Configure Type Validation
+```ruby
+MyApp.configure :settings do
+  config custom_typed_opt_one: '42', type: :float
+end
+# => AceConfig::SettingTypeError
+```
+
+## Configuration Container Usage
+
+```ruby
+require 'ace_config'
+
+module MyGem
+  include AceConfig
+end 
+```
+
+### Declare configurations
+```ruby
+MyGem.configure :settings do
+  config :option
+  config.int :typed_opt_one
+  config :typed_opt_two, type: Integer
+  # NOTE: declare nested namespace with configure <symbol arg>
+  configure :nested do
+    config :option
+  end
+end
+```
+
+### Define configurations
+```ruby
+MyGem.settings do 
+  config option: 1
+  config typed_opt_one: 2
+  config typed_opt_two: 3 
+  # NOTE: access namespace via <.dot_access> 
+  config.nested do 
+    config option: 4
+  end
+end
+```
+
+### Define with DSL Syntax
+```ruby
+MyGem.settings do 
+  option 1
+  typed_opt_one 2
+  typed_opt_two 3 
+  # NOTE: access namespace via <block> 
+  nested do 
+    option 1
+  end
+end
+```
+
+### Get configurations
+```ruby
+MyGem.settings.option        # => 1
+MyGem.settings.typed_opt_one # => 2
+MyGem.settings.typed_opt_two # => 3
+MyGem.settings.nested.option # => 4
+```
+
+### Define Configuration Type Validation
+```ruby
+MyGem.settings do 
+  config.typed_opt_two: '1'
+end 
+# => AceConfig::SettingTypeError
+
+MyGem.settings do 
+  typed_opt_two '1'
+end 
+# => AceConfig::SettingTypeError
+```
+
+## Loading Configuration Data
+
+The `AceConfig` module allows you to load configuration data from various sources, including YAML and JSON. Below are the details for each option.
+
+- `json` (String)
+- `yaml` (String)
+- `hash` (Hash)
+- `schema` (Hash) (Optional) See: [Type Schema](#type_schema) and [Built-in Types](#built-in-types)
+
+### Loading from a JSON String
+
+You can load configuration data from a JSON string by passing the `json` option to the `configure` method.
+
+#### Parameters
+
+- `json` (String): A JSON string containing the configuration data.
+- `schema` (Hash) (Optional): A hash representing the type schema for the configuration data.
+
+#### Error Handling
+
+- If the JSON format is invalid, a `LoadDataError` will be raised with the message "Invalid JSON format".
+
+#### Example 1
+```ruby
+MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}').settings
+# => #<MyGem::Setting:0x00007f8c1c0b2a80 @options={:opt_one=>1, :opt_two=>2}>
+```
+
+#### Example 2
+```ruby
+MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}', schema: { opt_one: :int, opt_two: :str })
+# => AceConfig::SettingTypeError: Expected: <str>. Given: 2 which is <Integer> class.
+```
+
+#### Example 3
+```ruby
+MyGem.configure(:settings, json: '{"opt_one":1,"opt_two":2}', schema: { opt_one: :int, opt_two: :int })
+
+MyGem.settings do 
+  opt_one 1
+  opt_two "2"
+end
+# => AceConfig::SettingTypeError: Expected: <intstr>. Given: \"2\" which is <String> class.
+```
+
+### Loading from a YAML File
+
+You can also load configuration data from a YAML file by passing the `yaml` option to the `configure` method.
+
+#### Parameters
+
+- `yaml` (String): A file path to a YAML file containing the configuration data.
+- `schema` (Hash) (Optional): A hash representing the type schema for the configuration data.
+
+#### Error Handling
+
+- If the specified YAML file is not found, a `LoadDataError` will be raised with the message "YAML file not found".
+
+##### YAML File
+```yaml
+# settings.yml
+
+opt_one: 1
+opt_two: 2
+```
+
+#### Example 1
+```ruby
+MyGem.configure :settings, yaml: 'settings.yml' 
+# => #<MyGem::Setting:0x00006f8c1c0b2a80 @options={:opt_one=>1, :opt_two=>2}>
+```
+
+#### Example 2
+```ruby
+MyGem.configure :settings, yaml: 'settings.yml', schema: { opt_one: :int, opt_two: :str }
+# => AceConfig::SettingTypeError: Expected: <str>. Given: 2 which is <Integer> class.
+```
+
+#### Example 3
+```ruby
+MyGem.configure :settings, yaml: 'settings.yml', schema: { opt_one: :int, opt_two: :int }
+
+MyGem.settings do 
+  opt_one 1
+  opt_two "2"
+end
+# => AceConfig::SettingTypeError: Expected: <intstr>. Given: \"2\" which is <String> class.
+```
+
+## Exporting Configuration Data
+
+You can dump the configuration data in various formats using the following methods:
+
+### to_h
+```ruby
+MyGem.configure :settings do
+  config opt_one: 1
+  config opt_two: 2
+end
+
+MyGem.settings.to_json # => '{"opt_one":1,"opt_two":2}'
+```
+
+### to_json
+```ruby
+MyGem.configure :settings do
+  config opt_one: 1
+  config opt_two: 2
+end
+
+MyGem.settings.to_json # => '{"opt_one":1,"opt_two":2}'
+```
+
+### to_yaml
+```ruby
+MyGem.configure :settings do
+  config opt_one: 1
+  config opt_two: 2
+end
+
+MyGem.settings.to_yaml # => "---\nopt_one: 1\nopt_two: 2\n"
+``` 
+
+### type_schema
+```ruby
+MyGem.configure :settings do
+  config.int opt_one: 1
+  config.str opt_two: "2"
+end
+
+MyGem.settings.type_schema # => {:opt_one=>:int, :opt_two=>:str}
+```
+
+## Built-in Types
+
+### Base Types
+```ruby
+:int  => Integer
+:str  => String
+:sym  => Symbol
+:null => NilClass
+:any  => Object
+:true_class  => TrueClass
+:false_class => FalseClass
+```
+
+### Data Structures
+```ruby 
+:hash  => Hash
+:array => Array
+```
+### Numeric
+```ruby
+:big_decimal => BigDecimal,
+:float       => Float,
+:complex     => Complex,
+:rational    => Rational,
+```
+### Time 
+```ruby
+:date      => Date,
+:date_time => DateTime,
+:time      => Time,
+```
+### Composite
+```ruby
+:bool       => [TrueClass, FalseClass],
+:numeric    => [Integer, Float, BigDecimal],
+:kernel_num => [Integer, Float, BigDecimal, Complex, Rational],
+:chrono     => [Date, DateTime, Time]
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yurigitsu/ace-config. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/yurigitsu/ace-config/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the AceConfig project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yurigitsu/ace-config/blob/main/CODE_OF_CONDUCT.md).

data/ace-config.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "ace_config/version"
+
+Gem::Specification.new do |spec|
+  spec.name    = "ace-config"
+  spec.version = "0.1.0.beta.rc1b"
+  spec.authors = ["yurigitsu"]
+  spec.email   = ["yurigi.pro@gmail.com"]
+  spec.license = "MIT"
+
+  spec.summary     = "A flexible and easy-to-use configuration handling gem."
+  spec.description = "Managing, configurations with type validation, configirations load and export support."
+  spec.homepage    = "https://github.com/yurigitsu/#{spec.name}"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.files         = Dir["CHANGELOG.md", "LICENSE", "README.md", "ace-config.gemspec", "lib/**/*"]
+  spec.bindir        = "bin"
+  spec.executables   = []
+  spec.require_paths = ["lib"]
+
+  spec.metadata["repo_homepage"]     = "https://github.com/yurigitsu/"
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.add_dependency "bigdecimal", "~> 3.0"
+end

data/lib/ace_config/configuration.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+# AceConfig module provides functionality for managing configuration features.
+#
+# @example Using AceConfig in a class
+#   class MyApp
+#     include AceConfig
+#
+#     configure :settings do
+#       config api_key: "default_key"
+#       config max_retries: 3
+#     end
+#   end
+#
+#   MyApp.settings.api_key # => "default_key"
+#   MyApp.settings.max_retries # => 3
+module AceConfig
+  # Extends the base class with Configuration module methods
+  def self.included(base)
+    base.extend(Configuration)
+  end
+
+  # Isolated module handles isolated configurations.
+  #
+  # @example Using Isolated configurations
+  #   class ParentApp
+  #     include AceConfig::Isolated
+  #
+  #     configure :parent_settings do
+  #       config timeout: 30
+  #       config tries: 3
+  #     end
+  #   end
+  #
+  #   class ChildApp < ParentApp
+  #     parent_settings do
+  #       config tries: 4
+  #     end
+  #   end
+  #
+  #   ChildApp.parent_settings.timeout # => 30
+  #   ChildApp.parent_settings.tries # => 4
+  #   ParentApp.parent_settings.tries # => 3
+  module Isolated
+    # Extends the base class with Configuration and Configuration::Isolated module methods
+    def self.included(base)
+      base.extend(Configuration)
+      base.extend(Configuration::Isolated)
+    end
+  end
+
+  # This module handles configuration trees and loading data from various sources.
+  module Configuration
+    # Isolated module provides methods for handling isolated configurations.
+    module Isolated
+      # Configures an isolated config tree and tracks it
+      #
+      # @param config_tree_name [Symbol] The name of the configuration tree
+      # @param opts [Hash] Options for configuration
+      # @yield The configuration block
+      # @return [self]
+      #
+      # @example
+      #   configure :isolated_settings do
+      #     config api_url: "https://api.example.com"
+      #   end
+      #
+      #   # Example of accessing the configuration
+      #   puts MyApp.isolated_settings.api_url # => "https://api.example.com"
+      def configure(config_tree_name, opts = {}, &block)
+        super
+
+        @isolated_configs ||= []
+        @isolated_configs << config_tree_name
+
+        self
+      end
+
+      # Inherits isolated configurations to the base class
+      #
+      # @param base [Class] The inheriting class
+      #
+      # @example
+      #   class ChildClass < ParentClass
+      #     # Automatically inherits isolated configurations
+      #   end
+      #
+      #   # Example of accessing inherited configurations
+      #   puts ChildClass.parent_settings.timeout # => 30
+      def inherited(base)
+        super
+
+        @isolated_configs.each do |parent_config|
+          hash = __send__(parent_config).to_h
+          schema = __send__(parent_config).type_schema
+
+          base.configure parent_config, hash: hash, schema: schema
+        end
+      end
+    end
+
+    # Creates a class-level method for the configuration tree.
+    #
+    # This method allows you to define a configuration tree using a block
+    # or load configuration data from a hash, JSON, or YAML file.
+    #
+    # @param config_tree_name [Symbol, String] The name of the configuration method to be defined.
+    # @param opts [Hash] Optional options for loading configuration data.
+    # @option opts [Hash] :hash A hash containing configuration data.
+    # @option opts [String] :json A JSON string containing configuration data.
+    # @option opts [String] :yaml A file path to a YAML file containing configuration data.
+    # @option opts [Hash] :schema A hash representing the type schema for the configuration.
+    # @yield [Setting] A block that builds the configuration tree.
+    #
+    # @example Configuring with a block
+    #   configure :app_config do
+    #     config :username, value: "admin"
+    #     config :max_connections, type: :int, value: 10
+    #   end
+    #
+    # @example Loading from a hash
+    #   configure :app_config, hash: { username: "admin", max_connections: 10 }
+    #
+    # @example Loading from a JSON string
+    #   configure :app_config, json: '{"username": "admin", "max_connections": 10}'
+    #
+    # @example Loading from a YAML file
+    #   configure :app_config, yaml: 'config/settings.yml'
+    #
+    # @example Loading with a schema
+    #   configure :app_config, hash: { name: "admin", policy: "allow" }, schema: { name: :str, policy: :str }
+    def configure(config_tree_name, opts = {}, &block)
+      settings = block ? AceConfig::Setting.new(&block) : AceConfig::Setting.new
+
+      load_configs = load_data(opts) unless opts.empty?
+      settings.load_from_hash(load_configs, schema: opts[:schema]) if load_configs
+
+      define_singleton_method(config_tree_name) do |&tree_block|
+        tree_block ? settings.instance_eval(&tree_block) : settings
+      end
+    end
+
+    module_function
+
+    # Loads configuration data from various sources based on the provided options.
+    #
+    # @param opts [Hash] Optional options for loading configuration data.
+    # @option opts [Hash] :hash A hash containing configuration data.
+    # @option opts [String] :json A JSON string containing configuration data.
+    # @option opts [String] :yaml A file path to a YAML file containing configuration data.
+    # @return [Hash] The loaded configuration data.
+    # @raise [LoadDataError] If no valid data is found.
+    #
+    # @example Loading from a hash
+    #   load_data(hash: { key: "value" })
+    #
+    # @example Loading from a JSON string
+    #   load_data(json: '{"key": "value"}')
+    #
+    # @example Loading from a YAML file
+    #   load_data(yaml: 'config/settings.yml')
+    def load_data(opts = {})
+      data = opts[:hash] if opts[:hash]
+      data = JSON.parse(opts[:json]) if opts[:json]
+      data = YAML.load_file(opts[:yaml]) if opts[:yaml]
+      raise AceConfig::LoadDataError, "Invalid load source type" unless data
+
+      data
+    rescue JSON::ParserError
+      raise AceConfig::LoadDataError, "Invalid JSON format"
+    rescue Errno::ENOENT
+      raise AceConfig::LoadDataError, "YAML file not found"
+    end
+  end
+end

data/lib/ace_config/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# AceConfig module provides functionality for managing AceConfig features.
+module AceConfig
+  # Custom error raised when a setting type does not match the expected type.
+  #
+  # @example Raising an SettingTypeError
+  #   raise SettingTypeError.new(:int, "string")
+  #   # => raises SettingTypeError with message
+  #   # "Expected: <int>. Given: \"string\" which is <String> class."
+  class SettingTypeError < TypeError
+    # Initializes a new SettingTypeError.
+    #
+    # @param type [Symbol] The expected type.
+    # @param val [Object] The value that was provided.
+    def initialize(type, val)
+      super(type_error_msg(type, val))
+    end
+
+    # Generates the error message for the exception.
+    #
+    # @param type [Symbol] The expected type.
+    # @param val [Object] The value that was provided.
+    # @return [String] The formatted error message.
+    def type_error_msg(type, val)
+      "Expected: <#{type}>. Given: #{val.inspect} which is <#{val.class}> class."
+    end
+  end
+
+  # Custom error raised when a type definition is missing.
+  #
+  # @example Raising a TypeCheckerError
+  #   raise TypeCheckerError.new(:unknown_type)
+  #   # => raises TypeCheckerError with message "No type Definition for: <unknown_type> type"
+  class TypeCheckerError < StandardError
+    # Initializes a new TypeCheckerError.
+    #
+    # @param type [Symbol] The type that is missing a definition.
+    def initialize(type)
+      super(definition_error_msg(type))
+    end
+
+    # Generates the error message for the exception.
+    #
+    # @param type [Symbol] The type that is missing a definition.
+    # @return [String] The formatted error message.
+    def definition_error_msg(type)
+      "No type Definition for: <#{type}> type"
+    end
+  end
+
+  # Custom error raised when data loading fails.
+  class LoadDataError < StandardError; end
+end

data/lib/ace_config/setting.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+# AceConfig module provides functionality for managing AceConfig features.
+module AceConfig
+  # Setting class provides a configuration tree structure for managing settings.
+  #
+  # This class allows for dynamic configuration management, enabling
+  # the loading of settings from hashes, YAML, or JSON formats.
+  #
+  # @example Basic usage
+  #   settings = Setting.new do
+  #     config(:key1, value: "example")
+  #     config(:key2, type: :int)
+  #   end
+  #
+  class Setting
+    # Dynamically define methods for each type in TypeMap.
+    #
+    # @!method int(value)
+    #   Sets an integer configuration value.
+    #   @param value [Integer] The integer value to set.
+    #
+    # @!method string(value)
+    #   Sets a string configuration value.
+    #   @param value [String] The string value to set.
+    #
+    # ... (other type methods)
+    AceConfig::TypeMap.list_types.each do |type|
+      define_method(type.downcase) { |stng| config(stng, type: type) }
+    end
+
+    # Initializes a new Setting instance.
+    #
+    # @yield [self] Configures the instance upon creation if a block is given.
+    def initialize(&block)
+      @schema = {}
+      @config_tree = {}
+
+      instance_eval(&block) if block_given?
+    end
+
+    # Loads configuration from a hash with an optional schema.
+    #
+    # @param data [Hash] The hash containing configuration data.
+    # @param schema [Hash] Optional schema for type validation.
+    # @raise [NoMethodError] If a method corresponding to a key is not defined.
+    # @raise [SettingTypeError] If a value doesn't match the specified type in the schema.
+    #
+    # @example Loading from a hash with type validation
+    #   settings.load_from_hash({ name: "admin", max_connections: 10 }, schema: { name: :str, max_connections: :int })
+    def load_from_hash(data, schema: {})
+      data.each do |key, value|
+        key = key.to_sym
+        type = schema[key] if schema
+
+        if value.is_a?(Hash) || value.is_a?(Setting)
+          configure(key) { load_from_hash(value, schema: schema[key]) }
+        else
+          validate_setting!(value, type) if type
+
+          config(key => value, type: type)
+        end
+      end
+    end
+
+    # Configures a node of the configuration tree.
+    #
+    # @param node [Symbol, String] The name of the config node key.
+    # @yield [Setting] A block that configures the new node.
+    #
+    # @example Configuring a new node
+    #   settings.configure(:database) do
+    #     config(:host, value: "localhost")
+    #     config(:port, value: 5432)
+    #   end
+    def configure(node, &block)
+      if config_tree[node]
+        config_tree[node].instance_eval(&block)
+      else
+        create_new_node(node, &block)
+      end
+    end
+
+    # Configures a setting with a given name and type.
+    #
+    # @param setting [Symbol, Hash, nil] The name of the setting or a hash of settings.
+    # @param type [Symbol, nil] The expected type of the setting.
+    # @param opt [Hash] Additional options for configuration.
+    # @return [self] The current instance for method chaining.
+    # @raise [SettingTypeError] If the value does not match the expected type.
+    #
+    # @example Configuring a setting
+    #   settings.config(max_connections: 10, type: :int)
+    def config(setting = nil, type: nil, **opt)
+      return self if !setting && opt.empty?
+
+      stngs = setting || opt
+      stng = extract_setting_info(stngs)
+
+      stng_type = type || schema[stng[:name]] || :any
+      validate_setting!(stng[:value], stng_type)
+
+      set_configuration(stng[:name], stng[:value], stng_type)
+    end
+
+    # Returns the type schema of the configuration.
+    #
+    # @return [Hash] A hash representing the type schema.
+    # @example Retrieving the type schema
+    #   schema = settings.type_schema
+    def type_schema
+      {}.tap do |hsh|
+        config_tree.each do |k, v|
+          v.is_a?(AceConfig::Setting) ? (hsh[k] = v.type_schema) : hsh.merge!(schema)
+        end
+      end
+    end
+
+    # Converts the configuration tree into a hash.
+    #
+    # @return [Hash] The config tree as a hash.
+    # @example Converting to hash
+    #   hash = settings.to_h
+    def to_h
+      {}.tap do |hsh|
+        config_tree.each do |k, v|
+          hsh[k] = v.is_a?(AceConfig::Setting) ? v.to_h : v
+        end
+      end
+    end
+
+    # Converts the configuration tree into YAML format.
+    #
+    # @param dump [String, nil] Optional file path to dump the YAML.
+    # @return [String, nil] The YAML string or nil if dumped to a file.
+    # @example Converting to YAML
+    #   yaml_string = settings.to_yaml
+    #   settings.to_yaml(dump: "config.yml") # Dumps to a file
+    def to_yaml(dump: nil)
+      yaml = to_h.to_yaml
+      dump ? File.write(dump, yaml) : yaml
+    end
+
+    # Converts the configuration tree into JSON format.
+    #
+    # @return [String] The JSON representation of the configuration tree.
+    # @example Converting to JSON
+    #   json_string = settings.to_json
+    def to_json(*_args)
+      to_h.to_json
+    end
+
+    protected
+
+    # @return [Hash] The schema of configuration types.
+    attr_reader :schema
+
+    private
+
+    # @return [Hash] The tree structure of configuration settings.
+    attr_reader :config_tree
+
+    # Creates a new node in the configuration tree.
+    #
+    # @param node [Symbol] The name of the node to create.
+    # @yield [Setting] A block to configure the new setting.
+    # @return [Setting] The newly created setting node.
+    def create_new_node(node, &block)
+      new_node = AceConfig::Setting.new(&block)
+      config_tree[node] = new_node
+      define_node_methods(node)
+    end
+
+    # Defines singleton methods for the given node.
+    #
+    # @param node [Symbol] The name of the node to define methods for.
+    def define_node_methods(node)
+      define_singleton_method(node) do |*_args, &node_block|
+        if node_block
+          config_tree[node].instance_eval(&node_block)
+        else
+          config_tree[node]
+        end
+      end
+    end
+
+    # Extracts the setting information from the provided input.
+    #
+    # @param stngs [Symbol, Hash] The setting name or a hash containing the setting name and value.
+    # @return [Hash] A hash containing the setting name and its corresponding value.
+    def extract_setting_info(stngs)
+      val = nil
+      name = stngs if stngs.is_a?(Symbol)
+      name, val = stngs.to_a.first if stngs.is_a?(Hash)
+
+      { name: name, value: val }
+    end
+
+    # Validates the setting value against the expected type.
+    #
+    # @param stng_val [Object] The value of the setting to validate.
+    # @param stng_type [Symbol] The expected type of the setting.
+    # @raise [SettingTypeError] If the setting value does not match the expected type.
+    def validate_setting!(stng_val, stng_type)
+      is_valid = AceConfig::TypeChecker.call(stng_val, type: stng_type)
+      raise AceConfig::SettingTypeError.new(stng_type, stng_val) unless !stng_val || is_valid
+    end
+
+    # Sets the configuration for a given setting name, value, and type.
+    #
+    # @param stng_name [Symbol] The name of the setting to configure.
+    # @param stng_val [Object] The value to assign to the setting.
+    # @param stng_type [Symbol] The type of the setting.
+    def set_configuration(stng_name, stng_val, stng_type)
+      schema[stng_name] = stng_type
+      config_tree[stng_name] = stng_val
+      return if respond_to?(stng_name)
+
+      define_singleton_method(stng_name) do |value = nil, type: nil|
+        if value
+          config(**{ stng_name => value, type: type })
+        else
+          config_tree[stng_name]
+        end
+      end
+    end
+  end
+end

data/lib/ace_config/type_checker.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# AceConfig module provides functionality for managing AceConfig features.
+module AceConfig
+  # This class is responsible for type checking in the Ace configuration.
+  class TypeChecker
+    class << self
+      # Calls the appropriate validation method based on the type.
+      #
+      # @param value [Object] The value to validate.
+      # @param type [Symbol, Array<Symbol, Class>, Class] The type(s) to validate against.
+      # @return [Boolean] True if the value matches the type, false otherwise.
+      # @raise [TypeCheckerError] if the type is unsupported or not defined.
+      #
+      # @example
+      #   TypeChecker.call(1, type: :int) # => true
+      #   TypeChecker.call(1, type: :numeric) # => true
+      #   TypeChecker.call("hello", type: [:str, Integer]) # => true
+      #   TypeChecker.call(CustomClass.new, type: CustomClass) # => true
+      def call(value, type:, **_opts)
+        case type
+        when Symbol
+          base_type(value, fetch_type(type))
+        when Array
+          one_of(value, type)
+        else
+          custom_type(value, type)
+        end
+      end
+
+      # Validates if value matches the base type.
+      #
+      # @param value [Object] the value to validate
+      # @param type [Class] the type to validate against
+      # @return [Boolean] true if the value matches the base type
+      # @raise [TypeCheckerError] if the type is unsupported or not defined.
+      #
+      # @example
+      #   TypeChecker.base_type(1, Integer) # => true
+      #   TypeChecker.base_type(1, [:int, :float, :big_decimal]) # => true
+      def base_type(value, type)
+        type = fetch_type(type) if type.is_a?(Symbol)
+
+        type.is_a?(Array) ? one_of(value, type) : value.is_a?(type)
+      end
+
+      # Checks if value matches any type in the array.
+      #
+      # @param value [Object] the value to validate
+      # @param array_type [Array<Symbol, Class>] the array of types to validate against
+      # @return [Boolean] true if the value matches any type in the array
+      #
+      # @example
+      #   TypeChecker.one_of(1, [Integer, :str]) # => true
+      #   TypeChecker.one_of("hello", [Integer, String, :sym]) # => true
+      #   TypeChecker.one_of(nil, [:null, Integer, String]) # => true
+      #   TypeChecker.one_of(1.5, [:int, :float, :big_decimal]) # => true
+      def one_of(value, array_type)
+        array_type.any? { |type| type.is_a?(Symbol) ? base_type(value, type) : custom_type(value, type) }
+      end
+
+      # Validates if value is of the specified custom type.
+      #
+      # @param value [Object] the value to validate
+      # @param type [Class] the custom type to validate against
+      # @return [Boolean] true if the value is of the specified custom type
+      #
+      # @example
+      #   TypeChecker.custom_type(1, Integer) # => true
+      #   TypeChecker.custom_type(CustomClass.new, CustomClass) # => true
+      def custom_type(value, type)
+        value.is_a?(type)
+      end
+
+      # Fetches the basic type from the type map.
+      #
+      # @param type [Symbol] the type to fetch
+      # @return [Class] the corresponding basic type
+      # @raise [TypeCheckerError] if the type does not exist in TYPE_MAP
+      #
+      # @example
+      #   TypeChecker.fetch_type(:int) # => Integer
+      #   TypeChecker.fetch_type(:null) # => NilClass
+      #   TypeChecker.fetch_type(:bool) # => [:truthy, :falsy]
+      def fetch_type(type)
+        basic_type = TypeMap.get(type)
+        raise AceConfig::TypeCheckerError, type unless basic_type
+
+        basic_type
+      end
+    end
+  end
+end

data/lib/ace_config/type_map.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+
+# AceConfig module provides functionality for managing AceConfig features.
+module AceConfig
+  # A class that maps type symbols to their corresponding Ruby classes and provides
+  # predefined collections of type symbols for various categories.
+  #
+  # This class allows retrieval of Ruby classes based on type symbols and provides
+  # methods to access collections of specific type symbols such as booleans, numerics,
+  # and chronological types.
+  class TypeMap
+    TYPE_MAP = {
+      # base types
+      int: Integer,
+      str: String,
+      sym: Symbol,
+      null: NilClass,
+      true_class: TrueClass,
+      false_class: FalseClass,
+      # data structures
+      hash: Hash,
+      array: Array,
+      # numeric types
+      big_decimal: BigDecimal,
+      float: Float,
+      complex: Complex,
+      rational: Rational,
+      # time types
+      date: Date,
+      date_time: DateTime,
+      time: Time,
+      # any type
+      any: Object,
+      # composite types
+      bool: %i[true_class false_class],
+      numeric: %i[int float big_decimal],
+      kernel_num: %i[int float big_decimal complex rational],
+      chrono: %i[date date_time time]
+    }.freeze
+
+    # Retrieves the Ruby class associated with a given type symbol.
+    #
+    # @param type [Symbol] The type symbol to look up. Must be one of the keys in TYPE_MAP.
+    # @return [Class, nil] The corresponding Ruby class or nil if the type symbol is not found.
+    #
+    # @example
+    #   TypeMap.get(:int) # => Integer
+    #   TypeMap.get(:str) # => String
+    #   TypeMap.get(:unknown) # => nil
+    def self.get(type)
+      TYPE_MAP[type]
+    end
+
+    # Returns an array of all type symbols defined in TYPE_MAP.
+    #
+    # @return [Array<Symbol>] An array containing all keys from TYPE_MAP.
+    #
+    # @example
+    #   TypeMap.list_types # => [:int, :str, :sym, :null, :true_class, :false_class,
+    #                          :hash, :array, :big_decimal, :float, :complex,
+    #                          :rational, :date, :date_time, :time, :any,
+    #                          :bool, :numeric, :kernel_num, :chrono]
+    def self.list_types
+      TYPE_MAP.keys
+    end
+  end
+end

data/lib/ace_config/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AceConfig
+  VERSION = "0.1.0"
+end

data/lib/ace_config.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "ace_config/version"
+require "ace_config/errors"
+require "ace_config/type_map"
+require "ace_config/setting"
+require "ace_config/type_checker"
+require "ace_config/configuration"

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: ace-config
+version: !ruby/object:Gem::Version
+  version: 0.1.0.beta.rc1b
+platform: ruby
+authors:
+- yurigitsu
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-09-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Managing, configurations with type validation, configirations load and
+  export support.
+email:
+- yurigi.pro@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- ace-config.gemspec
+- lib/ace_config.rb
+- lib/ace_config/configuration.rb
+- lib/ace_config/errors.rb
+- lib/ace_config/setting.rb
+- lib/ace_config/type_checker.rb
+- lib/ace_config/type_map.rb
+- lib/ace_config/version.rb
+homepage: https://github.com/yurigitsu/ace-config
+licenses:
+- MIT
+metadata:
+  repo_homepage: https://github.com/yurigitsu/
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/yurigitsu/ace-config
+  changelog_uri: https://github.com/yurigitsu/ace-config/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/yurigitsu/ace-config
+  bug_tracker_uri: https://github.com/yurigitsu/ace-config/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.20
+signing_key:
+specification_version: 4
+summary: A flexible and easy-to-use configuration handling gem.
+test_files: []