configsl 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9cf52e102562625f71dabce8ff0f05d8d1a0d129e62584a80aae1abd4903585d
+  data.tar.gz: f59fcc77eb986087131fe84e6770bc667be007ef922cb77477ab54b840e1a75b
+SHA512:
+  metadata.gz: 49f9b7c79beae87c9aff4be256de82fafa0f5fe6e76f6243f48c25ded6c0363df8330874ddcb6b7f7719ed2fd9d5ea02d4598491acb1d359c151656d25f060fe
+  data.tar.gz: afec6d65e82afe81485aa89bf73878e1d95deb96dc04db343edbb9cec980332738743208994a3d57ee2bedfd8f69f124187c134d3fb137a83ee7581920b2eb4b

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+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.0.0
+
+Initial release.
+
+### Added
+
+- Simple DSL for defining configuration
+- JSON and YAML file reading support
+- Environment variable reading support
+- Formatting and validation of values
+
+[changelog]: https://keepachangelog.com/en/1.1.0/
+[versioning]: https://semver.org/spec/v2.0.0.html

data/Gemfile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+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'
+end
+
+group :test do
+  # activesupport 7.2 introduces a breaking change that causes the specs to
+  # fail.
+  gem 'activesupport', '~> 7.1.0'
+
+  gem 'coveralls_reborn', '~> 0.28'
+  gem 'factory_bot', '~> 6.4'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec-github', '~> 2.4'
+  gem 'simplecov', '~> 0.22'
+end

data/README.md

@@ -0,0 +1,105 @@
+# ConfigSL [![Coverage Status][badge-coverage]][coverage]
+
+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
+dependencies and additional cruft as possible. It is both modular and
+extensible, so you can use as little or as much as you need.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'configsl'
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+Or install it yourself as:
+
+```sh
+gem install configsl
+```
+
+## Usage
+
+You can start defining your configurations using two methods:
+
+1. Extend the included `ConfigSL::Config` base class
+2. Include the `ConfigSL` modules you want to use in you class
+
+### Using the included base class
+
+The `ConfigSL::Config` base class includes common functionality for working with
+configurations. Currently, the class provides the following features:
+
+- **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
+- **Validation**: Built-in validation for configuration options
+
+```ruby
+require 'configsl'
+
+class AppConfig < ConfigSL::Config
+    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
+end
+```
+
+### Including modules
+
+If you'd like to pick and choose the features you want to use, you can include
+modules individually. _Most_ modules can be included in any order, but the `DSL`
+module _**must**_ be included before any others.
+
+Additionally, you will need to implement `initialize` -- or some other method --
+that sets the configuration values by calling `set_value` for each option.
+
+```ruby
+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
+    end
+end
+```
+
+### A note about inheritance
+
+When working with multiple configuration classes, you'll likely want to use a
+base class. This could be the `ConfigSL::Config` class, or a custom class that
+includes the modules you need.
+
+While the modules you include are inherited by subclasses, any options you
+define via DSL are not. This is because these values are stored using _class
+instance variables_. As a result, if you have options that are shared between
+classes, they will need to be implemented in both.
+
+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-coverage]: https://coveralls.io/repos/github/jamesiarmes/configsl/badge.svg
+[coverage]: https://coveralls.io/github/jamesiarmes/configsl

data/lib/configsl/config.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+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 'validation'
+
+module ConfigSL
+  # Base class for configuration that includes common functionality.
+  class Config
+    include DSL
+    include Format
+    include FromEnvironment
+    include FromFile
+    include Validation
+
+    def initialize(params = {})
+      params.each do |name, value|
+        set_value(name, value)
+      end
+    end
+  end
+end

data/lib/configsl/dsl.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'exception'
+
+module ConfigSL
+  # DSL (Domain Specific Language) for defining configuration options.
+  #
+  # This module provides the base functionality for building configuration
+  # classes. It should be included before any other modules that provide
+  # additional functionality, such as formatting or validation.
+  #
+  # The class that includes this module will need to set the values for the
+  # options before they can be used. The easiest way to do this is to call
+  # `set_value` with each option and its value in the constructor.
+  #
+  # @example
+  #   def initialize(params = {})
+  #     params.each do |name, value|
+  #       set_value(name, value)
+  #     end
+  #   end
+  module DSL
+    # Include the class methods when the module is included.
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Returns the options hash for the class of the current instance.
+    #
+    # @return [Hash] The options hash.
+    def options
+      self.class.options
+    end
+
+    # Returns the values of all the options.
+    #
+    # @return [Array<Hash>] The values of all the options.
+    def values
+      options.each_key.to_h { |name| [name, get_value(name)] }
+    end
+
+    private
+
+    # Gets the value of an option.
+    #
+    # 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.
+    #
+    # @raise [InvalidOptionError] If the option is not defined.
+    def get_value(name)
+      raise InvalidOptionError, "Option #{name} is not defined" unless options.key?(name)
+
+      @params.fetch(name, options[name]&.[](:default))
+    end
+
+    # Sets the value of an option.
+    #
+    # @param name [Symbol] The name of the option.
+    # @param value [Object] The value to set.
+    # @return [Object] The value that was set for the option.
+    #
+    # @raise [InvalidOptionError] If the option is not defined.
+    def set_value(name, value)
+      raise InvalidOptionError, "Option #{name} is not defined" unless options.key?(name)
+
+      @params ||= {}
+      @params[name] = value
+    end
+
+    # Required class methods for the config DSL.
+    module ClassMethods
+      # Define an option for the class.
+      #
+      # The keys for the options hash will vary depending on the modules that
+      # have been included in your class.
+      #
+      # @param name [Symbol] The name of the option.
+      # @param opts [Hash] The options for the option.
+      # @return [void]
+      def option(name, opts = {})
+        options.merge!({ name => opts })
+        define_method(name) { get_value(name) }
+      end
+
+      # Returns the options hash for the class.
+      #
+      # @return [Hash] The options hash.
+      def options
+        @options ||= {}
+      end
+    end
+  end
+end

data/lib/configsl/exception.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ConfigSL
+  class InvalidOptionError < ArgumentError; end
+end

data/lib/configsl/file_format/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ConfigSL
+  module FileFormat
+    # Base class for file format support.
+    #
+    # @abstract Subclass and override `#read` and `.extensions` to implement a
+    # file format.
+    class Base
+      def initialize(file)
+        @file = file
+      end
+
+      # Extensions used to identify the file format.
+      #
+      # Values should be returned in order of preference.
+      #
+      # @return [Array<Symbol>] The extensions used to identify the file format.
+      def self.extensions
+        []
+      end
+
+      # Reads the file and returns a hash of configuration values.
+      #
+      # @return [Hash{Symbol => Object}]
+      #
+      # @raise [NotImplementedError] If not implemented.
+      def read
+        raise NotImplementedError, 'Not implemented'
+      end
+    end
+  end
+end

data/lib/configsl/file_format/json.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'base'
+
+module ConfigSL
+  module FileFormat
+    # Support for JSON files.
+    class Json < Base
+      def self.extensions
+        %i[json]
+      end
+
+      def read
+        ::JSON.parse(File.read(@file), symbolize_names: true).each do |name, value|
+          yield name, value if block_given?
+        end
+      end
+    end
+  end
+end

data/lib/configsl/file_format/yaml.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require_relative 'base'
+
+module ConfigSL
+  module FileFormat
+    # Support for YAML files.
+    class Yaml < Base
+      def self.extensions
+        %i[yaml yml]
+      end
+
+      def read
+        ::YAML.load_file(@file, symbolize_names: true).each do |name, value|
+          yield name, value if block_given?
+        end
+      end
+    end
+  end
+end

data/lib/configsl/file_support.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module ConfigSL
+  class FileFormatError < ArgumentError; end
+  class FileNotFoundError < ArgumentError; end
+
+  # Support for common file operations.
+  #
+  # This module provides limited functionality itself, but instead provides
+  # basic support for configuration files that is leveraged by other modules.
+  #
+  # Including this modules adds the following DSL methods to your class:
+  #
+  # - config_file_path: Set the default path to look for configuration files
+  # - config_file_name: Set the default file name to look for configuration
+  #   files, without extension
+  # - register_file_format: Add support for a file format
+  module FileSupport
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Required class methods to support file operations.
+    module ClassMethods
+      # The default name to use for the configuration file.
+      #
+      # @param filename [String] The name of the configuration file.
+      # @return [String] The name of the configuration file.
+      def config_file_name(filename = nil)
+        @config_file_name = filename unless filename.nil?
+        @config_file_name ||= 'config'
+      end
+
+      # The default path to use for the configuration file.
+      #
+      # @param path [String] The path to the configuration file.
+      # @return [String] The path to the configuration file.
+      def config_file_path(path = nil)
+        @config_file_path = path unless path.nil?
+        @config_file_path ||= '.'
+      end
+
+      # The file extensions supported by this configuration.
+      #
+      # @param format [Symbol] Optional format to get the extensions for. If
+      #   specified, only returns the extensions for that format.
+      # @return [Array<String>]
+      def file_extensions(format: nil)
+        @config_file_formats ||= {}
+        if format
+          return @config_file_formats[format][:extensions] if @config_file_formats.key?(format)
+
+          raise FileFormatError, "File format not found: #{format}"
+        end
+
+        @config_file_formats.values.map { |o| o[:extensions] }.flatten
+      end
+
+      # Register support for a file format.
+      #
+      # @param format [Symbol] The format to register.
+      # @param opts [Hash] The options for the format.
+      # @option opts [Class] :class The class to use for the format. Defaults to
+      #   ConfigSL::FileFormat::`format`, where `format` is capitalized.
+      # @option opts [Array<String>] :extensions File extensions for the format.
+      #   defaults to those defined in `opts[:class]`.
+      def register_file_format(format, opts = {})
+        @config_file_formats ||= {}
+        opts[:class] ||= ConfigSL::FileFormat.const_get(format.capitalize)
+        opts[:extensions] ||= opts[:class].extensions
+
+        @config_file_formats[format] = opts
+      end
+
+      private
+
+      # Find the configuration file based on the default path, name, and defined
+      # formats.
+      #
+      # The returned files are ordered based on how their formats are defined.
+      # For example:
+      #
+      #   register_file_format :yaml
+      #   register_file_format :json
+      #
+      # would result in the YAML file being returned first if both are found.
+      #
+      # @param path [String] Optional path to look for the file. If provided,
+      #   this method will raise an error the exact file is not found.
+      # @param format [Symbol] Optional format to look for the file in. If
+      #   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)
+        paths = Dir.glob(
+          path.nil? ? "#{config_file_name}.{#{file_extensions(format:).join(',')}}" : path,
+          base: path.nil? ? config_file_path : nil
+        )
+
+        raise FileNotFoundError, 'No configuration file found!' if paths.empty?
+
+        paths.map { |p| File.join(config_file_path, p) }
+      end
+
+      # Find the format for a file given its extension.
+      #
+      # @param extension [String] The file extension to get the format for.
+      # @return [Symbol] The format for the file.
+      #
+      # @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)
+        raise FileFormatError, 'No file formats have been defined' if @config_file_formats.nil?
+
+        extension = extension.sub(/^\./, '').to_sym
+        (@config_file_formats || {}).each do |format, opts|
+          return format if opts[:extensions].include?(extension)
+        end
+
+        raise FileFormatError, "No file format found for extension: #{extension}"
+      end
+    end
+  end
+end

data/lib/configsl/format.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'facets/boolean'
+
+module ConfigSL
+  class FormatError < ArgumentError; end
+
+  # Format option values.
+  #
+  # 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.
+  #
+  # @todo Should we add an option to cast nil?
+  module Format
+    FORMATTERS = {
+      Array => :to_a,
+      FalseClass => :to_b,
+      Hash => :to_h,
+      Integer => :to_i,
+      String => ->(v) { v.to_s.encode('utf-8') },
+      Symbol => :to_sym,
+      TrueClass => :to_b
+    }.freeze
+
+    private
+
+    def get_value(name)
+      value = super
+      format_value(name, value)
+    end
+
+    def set_value(name, value)
+      raise InvalidOptionError, "Option #{name} is not defined" unless options.key?(name)
+
+      super(name, format_value(name, value))
+    end
+
+    def format_value(option, value)
+      return value if value.nil? || value.is_a?(options[option][:type])
+
+      apply_formatter(value, options[option][:type])
+    rescue StandardError => e
+      raise FormatError, "Value for #{option} is not compatible with " \
+                         "#{options[option][:type]}: #{e.message}"
+    end
+
+    def apply_formatter(value, formatter)
+      if FORMATTERS.key?(formatter)
+        return value.send(FORMATTERS[formatter]) if FORMATTERS[formatter].is_a?(Symbol)
+        return FORMATTERS[formatter].call(value) if FORMATTERS[formatter].is_a?(Proc)
+      end
+
+      formatter.new(value)
+    end
+  end
+end

data/lib/configsl/from_environment.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ConfigSL
+  # Load configuration from the environment.
+  #
+  # This module provides a way to load configuration values from environment
+  # variables. It checks for a variables using the name of the option, in upper
+  # snake case (e.g. `MY_OPTION`). You can add a prefix to all variable names
+  # using `from_environment_prefix`.
+  #
+  #   from_environment_prefix 'DATABASE_'
+  #   option :host, default: 'localhost'
+  #
+  # You can override the variable name for individual options by setting
+  # `env_variable`.
+  #
+  #   option :host, default: 'localhost', env_variable: 'DB_HOST'
+  module FromEnvironment
+    def self.included(base)
+      base.extend ClassMethods
+      base.from_environment_prefix ''
+    end
+
+    # Class methods necessary for loading configuration from the environment.
+    module ClassMethods
+      # Set the prefix for environment variables.
+      #
+      # @param prefix [String] The prefix for the environment variables.
+      def from_environment_prefix(prefix)
+        @from_environment_prefix = prefix
+      end
+
+      # Create a new instance of the class using values from the environment.
+      #
+      # @return [self] The new config object
+      def from_environment
+        params = options.transform_values do |opts|
+          ENV.fetch(opts[:env_variable], opts[:default])
+        end
+
+        new(params)
+      end
+
+      # Ensure each option has an environment variable defined.
+      def option(name, opts = {})
+        opts[:env_variable] ||= "#{@from_environment_prefix}#{name.to_s.upcase}"
+        super
+      end
+    end
+  end
+end

data/lib/configsl/from_file.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'file_support'
+
+module ConfigSL
+  # Load configuration from a file.
+  #
+  # This module provides a way to load configuration values from a file. It
+  # searches for files based on a default path, name, and one or more file
+  # formats.
+  #
+  # When multiple files are found, they will be sorted based on the order their
+  # formats are defined, and the first file will be loaded.
+  #
+  # For example:
+  #
+  #   config_file_path 'config'
+  #   config_file_name 'config'
+  #
+  #   register_file_format :yaml
+  #   register_file_format :json
+  #
+  # will search for files in the `config` directory, with the name `config`, and
+  # with the extensions `.yaml`, `.yml` and `.json`. If both `config.yaml` and
+  # `config.json` are found, `config.yaml` will be loaded.
+  #
+  # This module depends on the `FileSupport` module and will it include it your
+  # class if it has not been so already.
+  module FromFile
+    def self.included(base)
+      base.include(FileSupport) unless base.include?(FileSupport)
+      base.extend(ClassMethods)
+    end
+
+    # Required class methods for loading config files.
+    module ClassMethods
+      # Loads configuration from a file.
+      #
+      # If no path is specified, uses the file file that matches the default
+      # path, name, and file formats. If multiple files are found, they will be
+      # sorted based on the order the file formats are defined, adn the first
+      # file will be load.
+      #
+      # @param path [String] Optional path to the file to load.
+      # @param format [Symbol] Optional format to use for the file. Uses the
+      #   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)
+      end
+    end
+  end
+end

data/lib/configsl/validation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ConfigSL
+  class ValidationError < RuntimeError; end
+
+  # Validates configuration options.
+  #
+  # This will check that all required options are set. Additionally, you can
+  # set `enum` to an array of valid values for an option.
+  #
+  #   option :state, type: String, required: true, enum: %w[on off]
+  #
+  # @todo Implement custom validations.
+  module Validation
+    # Determine if the configuration is valid.
+    #
+    # @return [Boolean]
+    def valid?
+      options.keys.all? { |name| option_valid?(name) }
+    end
+
+    # Validate the configuration and raise an error if it is invalid.
+    #
+    # @raise [ValidationError] If the configuration is invalid.
+    def validate!
+      raise ValidationError, 'Invalid configuration' unless valid?
+    end
+
+    private
+
+    # Validates a single option.
+    #
+    # @param name [Symbol] The name of the option.
+    # @return [Boolean]
+    def option_valid?(name)
+      valid = !options[name][:required] || get_value(name)
+      valid &&= options[name][:enum].include?(get_value(name)) if options[name][:enum]
+
+      valid
+    end
+  end
+end

data/lib/configsl.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'configsl/config'
+
+module ConfigSL
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: configsl
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- James I. Armes
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-09-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: facets
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: A simple, modular, extensible DSL for configuration.
+email: jamesiarmes@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+files:
+- CHANGELOG.md
+- Gemfile
+- README.md
+- lib/configsl.rb
+- lib/configsl/config.rb
+- lib/configsl/dsl.rb
+- lib/configsl/exception.rb
+- lib/configsl/file_format/base.rb
+- lib/configsl/file_format/json.rb
+- lib/configsl/file_format/yaml.rb
+- lib/configsl/file_support.rb
+- lib/configsl/format.rb
+- lib/configsl/from_environment.rb
+- lib/configsl/from_file.rb
+- lib/configsl/validation.rb
+homepage: https://github.com/jamesiarmes/configsl
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/jamesiarmes/configsl/issues
+  changelog_uri: https://github.com/jamesiarmes/configsl/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/jamesiarmes/configsl
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/jamesiarmes/configsl
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: A simple DSL for declarative configuration in ruby.
+test_files: []