config_files 0.1.7 → 0.2.1

data/README.md

@@ -1,38 +1,261 @@
-*Description*
+# ConfigFiles
 
-Since it no longer just deals with yaml files as an input, *blackrat_yaml_config* has been renamed to *config_files*
-Configuration file manager.
+[![CI](https://github.com/blackrat/config_files/workflows/CI/badge.svg)](https://github.com/blackrat/config_files/actions)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%202.7.0-ruby.svg)](https://www.ruby-lang.org/en/downloads/)
+[![Gem Version](https://badge.fury.io/rb/config_files.svg)](https://badge.fury.io/rb/config_files)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-*Features*
+Load configuration files from multiple directories and merge them together. Supports YAML, JSON, and other formats.
 
-Searches for first match in multiple directories for configuration file
-Allows for dynamically updated or static config files
+## Features
 
-*Example*
+- Load configs from multiple directories
+- Merge YAML, JSON, and other file formats
+- Directory precedence (first directory wins)
+- Static (cached) or dynamic (reloaded) config files
+- Returns `HashWithIndifferentAccess` for easy key access
 
-    require 'config_files'
+## Installation
 
-    class Dummy
-      include ConfigFiles #mixin the config_directories and config_files generators
+Add to your Gemfile:
 
-      #search directories (in order). The system will search for the file in the following directories
-      config_directories :etc=>['~/.dummy','/opt/dummy/config','/etc/default/dummy','/etc']
+```ruby
+gem 'config_files'
+```
 
-      #The dummy.yml and another_yaml_file.yml will be pre-loaded.
-      static_config_files :dummy, :another_yaml_file
+Or install it:
 
-      #yet_another_yaml_file.yml will be read every time the .yet_another_yaml_file method is accessed.
-      dynamic_config_files :yet_another_yaml_file
+```bash
+gem install config_files
+```
 
-      def use_config
-        some_method(Dummy.dummy[:key]) #extract the constant values from the :key in dummy.yml
-        another_method(Dummy.yet_another_yaml_file[:another_key]) #extract the constant value from the :another_key in yet_another_yaml_file.yml
-      end
+## Usage
 
-    end
+```ruby
+require 'config_files'
 
+class MyApp
+  include ConfigFiles
+  
+  # Search these directories in order (first wins)
+  config_directories etc: [
+    'config/production',
+    'config/staging',
+    'config/defaults'
+  ]
+  
+  # Load these config files
+  static_config_files :database, :app_settings
+  dynamic_config_files :feature_flags
+end
 
+# Use the configs
+MyApp.database[:host]           # => "prod-db.example.com"
+MyApp.app_settings[:debug]      # => false
+MyApp.feature_flags[:new_ui]    # => true (reloaded each time)
+```
 
-*Todo*
+## How it works
 
-Allow for different keys to be stored in files in different subdirectories to allow for overridable defaults
+The gem searches for config files in each directory you specify. If you have:
+
+```
+config/production/database.yml
+config/staging/database.yml
+config/defaults/database.yml
+```
+
+And you configure directories as `['config/production', 'config/staging', 'config/defaults']`, then:
+
+1. It loads all three files
+2. Merges them together
+3. Values from `production` override `staging` and `defaults`
+4. Values from `staging` override `defaults`
+5. Returns the merged result
+
+## Multiple file formats
+
+You can mix YAML and JSON files:
+
+```
+config/
+├── app.yml     # YAML format
+├── app.json    # JSON format
+└── app.conf    # Other formats
+```
+
+All files with the same base name get merged together. Files are processed alphabetically, so `app.json` loads before `app.yml`.
+
+## Static vs Dynamic
+
+```ruby
+class AppConfig
+  include ConfigFiles
+  config_directories etc: ['config']
+  
+  # Static: loaded once and cached
+  static_config_files :database
+  
+  # Dynamic: reloaded from disk each time
+  dynamic_config_files :feature_flags
+end
+
+AppConfig.database        # Fast (cached)
+AppConfig.feature_flags   # Slower (reads from disk)
+```
+
+Use static for configs that don't change. Use dynamic for configs that might change while your app is running.
+
+## Directory precedence
+
+Earlier directories in the list win:
+
+```ruby
+config_directories etc: [
+  'config/production',   # Highest priority
+  'config/staging',      # Medium priority
+  'config/defaults'      # Lowest priority
+]
+```
+
+So if `production/app.yml` has `debug: false` and `defaults/app.yml` has `debug: true`, the result will have `debug: false`.
+
+## Configuration merging
+
+Configs are deep-merged. Given these files:
+
+```yaml
+# config/defaults/app.yml
+database:
+  host: localhost
+  port: 5432
+  pool_size: 5
+app:
+  debug: true
+  name: MyApp
+```
+
+```yaml
+# config/production/app.yml
+database:
+  host: prod-db.example.com
+  pool_size: 20
+app:
+  debug: false
+```
+
+The result is:
+
+```ruby
+{
+  database: {
+    host: "prod-db.example.com",  # from production
+    port: 5432,                   # from defaults
+    pool_size: 20                 # from production
+  },
+  app: {
+    debug: false,                 # from production
+    name: "MyApp"                 # from defaults
+  }
+}
+```
+
+## Custom directory keys
+
+You can use different directory sets:
+
+```ruby
+class AppConfig
+  include ConfigFiles
+  
+  config_directories(
+    etc: ['config/app', '/etc/myapp'],
+    secrets: ['secrets/production', 'secrets/shared']
+  )
+  
+  static_config_files :database    # searches in 'etc' directories
+end
+
+# Access the directory paths
+AppConfig.etc_dir      # => ["/full/path/to/config/app", "/etc/myapp"]
+AppConfig.secrets_dir  # => ["/full/path/to/secrets/production", ...]
+```
+
+## Error handling
+
+Missing files and directories are ignored:
+
+```ruby
+class AppConfig
+  include ConfigFiles
+  
+  config_directories etc: [
+    'config/nonexistent',  # ignored
+    'config/existing'      # used
+  ]
+  
+  static_config_files :missing_file
+end
+
+AppConfig.missing_file  # => {} (empty hash)
+```
+
+## Testing
+
+Run the tests:
+
+```bash
+bundle exec rake test
+```
+
+Test with multiple Ruby versions:
+
+```bash
+./scripts/test_multiple_rubies.sh
+```
+
+The gem is tested on Ruby 2.7+ with ActiveSupport 6.1+. See [TESTING.md](TESTING.md) for details.
+
+## API
+
+### config_directories(hash)
+
+Define search directories:
+
+```ruby
+config_directories etc: ['dir1', 'dir2']
+```
+
+### static_config_files(*files)
+
+Load files once and cache them:
+
+```ruby
+static_config_files :database, :app_settings
+```
+
+### dynamic_config_files(*files)
+
+Reload files on each access:
+
+```ruby
+dynamic_config_files :feature_flags
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-feature`)
+3. Make your changes
+4. Run the tests (`bundle exec rake test`)
+5. Commit your changes (`git commit -am 'Add feature'`)
+6. Push to the branch (`git push origin my-feature`)
+7. Create a Pull Request
+
+## License
+
+MIT License. See [LICENCE.txt](LICENCE.txt) for details.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

data/Rakefile

@@ -1,8 +1,31 @@
+# frozen_string_literal: true
+
 require 'rake/testtask'
 
-Rake::TestTask.new do |t|
+Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end
+
+task default: :test
+
+desc "Run tests with verbose output"
+task :test_verbose do
+  sh "find test -name '*_test.rb' -exec bundle exec ruby {} \\;"
 end
 
-desc "Run tests"
-task :default => :test
+desc "Run tests for a specific Ruby version (for local testing)"
+task :test_ruby_version do
+  ruby_version = ENV['RUBY_VERSION'] || RUBY_VERSION
+  puts "Running tests with Ruby #{ruby_version}"
+  Rake::Task[:test].invoke
+end
+
+desc "Clean up test artifacts"
+task :clean do
+  FileUtils.rm_rf('test/format_test')
+  FileUtils.rm_rf('test/comprehensive')
+  FileUtils.rm_rf('test/order_test')
+end

data/TESTING.md

@@ -0,0 +1,226 @@
+# Testing ConfigFiles
+
+This document describes how to test the ConfigFiles gem across multiple Ruby versions and ActiveSupport versions.
+
+## Supported Versions
+
+### Ruby Versions
+- **Ruby 2.7+**: Full support with ActiveSupport 6.1+ and 7.0+
+- **Ruby 3.0+**: Full support with all ActiveSupport versions
+- **Ruby 3.1+**: Full support with all ActiveSupport versions including 7.1+ and 7.2+
+
+### ActiveSupport Versions
+- **ActiveSupport 6.1**: Compatible with Ruby 2.7+
+- **ActiveSupport 7.0**: Compatible with Ruby 2.7+
+- **ActiveSupport 7.1**: Compatible with Ruby 3.1+
+- **ActiveSupport 7.2**: Compatible with Ruby 3.1+
+
+## Testing Methods
+
+### 1. GitHub Actions (Recommended for CI/CD)
+
+The project uses GitHub Actions for automated testing across multiple Ruby and ActiveSupport versions.
+
+**Configuration**: `.github/workflows/ci.yml`
+
+**Features**:
+- Tests Ruby 2.7, 3.0, 3.1, 3.2, 3.3, and 3.4
+- Tests ActiveSupport 6.1, 7.0, 7.1, and 7.2
+- Automatically excludes incompatible combinations
+- Includes linting with RuboCop
+- Runs on every push and pull request
+
+### 2. Local Testing with Multiple Ruby Versions
+
+#### Using Multi-Manager Script (asdf/rbenv/rvm)
+
+```bash
+# The script automatically detects which Ruby version manager you have installed:
+# - asdf (recommended)
+# - rbenv 
+# - rvm
+
+# Install Ruby versions (choose your manager):
+# asdf: ./scripts/install_rubies_asdf.sh
+# rbenv: rbenv install 2.7.8 3.0.6 3.1.4 3.2.2 3.3.0 3.4.1
+# rvm: rvm install 2.7.8 3.0.6 3.1.4 3.2.2 3.3.0 3.4.1
+
+# Run the multi-Ruby test script
+./scripts/test_multiple_rubies.sh
+```
+
+This script will:
+- Auto-detect your Ruby version manager (asdf, rbenv, or rvm)
+- Check which Ruby versions are installed
+- Offer to install missing Ruby versions
+- Test each Ruby version with multiple ActiveSupport versions
+- Skip incompatible combinations
+- Provide a summary of results
+
+#### asdf-Specific Installation
+
+```bash
+# Install all Ruby versions at once with asdf
+./scripts/install_rubies_asdf.sh
+
+# Then run tests
+./scripts/test_multiple_rubies.sh
+```
+
+#### Using Docker
+
+```bash
+# Test all combinations using Docker
+./scripts/test_docker.sh
+
+# Test a specific Ruby version
+docker build --build-arg RUBY_VERSION=3.3 --build-arg ACTIVESUPPORT_VERSION="~> 7.0" -f docker/Dockerfile.test -t config_files_test .
+docker run --rm config_files_test
+```
+
+### 3. Single Version Testing
+
+#### Standard Testing
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake test
+
+# Run tests with verbose output
+bundle exec rake test_verbose
+
+# Run individual test files
+find test -name "*_test.rb" -exec bundle exec ruby {} \;
+```
+
+#### Testing with Specific ActiveSupport Version
+```bash
+# Create a custom Gemfile
+cat > Gemfile.custom << EOF
+source 'https://rubygems.org'
+gemspec
+gem 'activesupport', '~> 6.1.0'
+gem 'minitest', '~> 5.20'
+gem 'rake'
+EOF
+
+# Install and test
+BUNDLE_GEMFILE=Gemfile.custom bundle install
+BUNDLE_GEMFILE=Gemfile.custom bundle exec rake test
+```
+
+## Test Structure
+
+### Test Files
+- `test/config_files_test.rb` - Core functionality tests
+- `test/loader_factory_test.rb` - File loader tests
+- `test/multi_directory_test.rb` - Multi-directory functionality
+- `test/mixed_format_test.rb` - Mixed YAML/JSON format tests
+- `test/comprehensive_multi_directory_test.rb` - Complex scenarios
+
+### Test Data
+- `test/etc/` - Sample configuration files
+- `test/config/` - Additional test configurations
+- `test/local/` - Local override test files
+
+## Compatibility Testing
+
+### Ruby Version Compatibility
+
+The gem uses these Ruby features that affect compatibility:
+
+1. **Safe Navigation Operator (`&.`)** - Requires Ruby 2.3+
+2. **Keyword Arguments** - Requires Ruby 2.0+
+3. **ActiveSupport Dependencies** - Varies by version
+
+### ActiveSupport Compatibility
+
+Different ActiveSupport versions have different Ruby requirements:
+
+- ActiveSupport 5.2: Ruby 2.2.2+
+- ActiveSupport 6.0: Ruby 2.5.0+
+- ActiveSupport 6.1: Ruby 2.5.0+
+- ActiveSupport 7.0: Ruby 2.7.0+
+- ActiveSupport 7.1: Ruby 3.1.0+
+- ActiveSupport 7.2: Ruby 3.1.0+
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Safe Navigation Operator Error**
+   ```
+   undefined method `&' for nil:NilClass
+   ```
+   **Solution**: Use Ruby 2.3+ or replace `&.` with `&& obj.`
+
+2. **ActiveSupport Version Conflicts**
+   ```
+   Gem::ConflictError: Unable to activate activesupport
+   ```
+   **Solution**: Check Ruby/ActiveSupport compatibility matrix above
+
+3. **Minitest Version Issues**
+   ```
+   cannot load such file -- mutex_m
+   ```
+   **Solution**: Add `mutex_m` gem for Ruby 3.4+
+
+### Running Specific Test Combinations
+
+```bash
+# Test Ruby 3.3 with ActiveSupport 7.0
+RUBY_VERSION=3.3 ACTIVESUPPORT_VERSION="~> 7.0" ./scripts/test_combination.sh
+
+# Test with Docker
+docker build --build-arg RUBY_VERSION=3.3 --build-arg ACTIVESUPPORT_VERSION="~> 7.0" -f docker/Dockerfile.test -t test .
+docker run --rm test
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+The project automatically tests all supported combinations on:
+- Push to main/master branch
+- Pull requests
+- Manual workflow dispatch
+
+### Other CI Systems
+
+The testing approach can be adapted for other CI systems:
+
+- **GitLab CI**: Use similar matrix strategy with `.gitlab-ci.yml`
+- **CircleCI**: Use workflow matrix with different Ruby Docker images
+- **Jenkins**: Use pipeline with multiple Ruby environments
+
+## Performance Testing
+
+For performance testing across versions:
+
+```bash
+# Run benchmarks (if implemented)
+bundle exec rake benchmark
+
+# Memory usage testing
+bundle exec ruby -r memory_profiler test/memory_test.rb
+```
+
+## Contributing
+
+When adding new features:
+
+1. Ensure tests pass on all supported Ruby versions
+2. Add tests for new functionality
+3. Update compatibility documentation if needed
+4. Run the full test matrix before submitting PRs
+
+```bash
+# Quick local test
+bundle exec rake test
+
+# Full compatibility test
+./scripts/test_multiple_rubies.sh
+```

data/config_files.gemspec

@@ -1,25 +1,28 @@
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'config_files/version'
 
 Gem::Specification.new do |spec|
   spec.authors     = ['Paul McKibbin']
   spec.email       = ['pmckibbin@gmail.com']
-  spec.description = 'A configuration tool for using multiple configuration files with multiple formats by presenting them as a hash.'
+  spec.description = 'Configuration tool for cascading configuration files with multiple formats'
   spec.summary     = <<-SUMMARY
   ConfigFiles is a configuration file access tool. It parses multiple configuration files in multiple formats and
-  presents a consistent block to the application with options to cache or use the files dynamically
-SUMMARY
+  presents a consistent block to the application with options to cache or use the files dynamically. It uses a priority
+  directory ordering to find the files, and an alphabetical ordering to give precedence to the files in that directory.
+  SUMMARY
 
   spec.homepage    = 'https://github.com/blackrat/config_files'
   spec.files       = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
-  spec.test_files  = spec.files.grep(%r{^(test|spec|features)/})
   spec.name        = 'config_files'
   spec.require_paths = ['lib']
   spec.version     = ConfigFiles::VERSION
   spec.license     = 'MIT'
-  spec.date        = '2012-11-11'
+  spec.required_ruby_version = '>= 2.7.0'
 
-  spec.add_runtime_dependency 'activesupport', '>=2.2.1'
-  spec.add_development_dependency 'rake'
-end
+  spec.add_dependency 'activesupport', '>= 6.1', '< 8.0'
+  spec.add_dependency 'rexml', '~> 3.2'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/docker/Dockerfile.test

@@ -0,0 +1,32 @@
+ARG RUBY_VERSION=3.3
+FROM ruby:${RUBY_VERSION}-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy gemspec and version file first for better caching
+COPY config_files.gemspec ./
+COPY lib/config_files/version.rb ./lib/config_files/
+
+# Copy Gemfile if it exists
+COPY Gemfile* ./
+
+# Install gems
+ARG ACTIVESUPPORT_VERSION="~> 7.0"
+RUN echo "gem 'activesupport', '${ACTIVESUPPORT_VERSION}'" >> Gemfile.docker && \
+    echo "gem 'minitest', '~> 5.20'" >> Gemfile.docker && \
+    echo "gem 'mutex_m'" >> Gemfile.docker && \
+    echo "gem 'rake'" >> Gemfile.docker && \
+    BUNDLE_GEMFILE=Gemfile.docker bundle install
+
+# Copy the rest of the application
+COPY . .
+
+# Run tests
+CMD ["sh", "-c", "BUNDLE_GEMFILE=Gemfile.docker bundle exec rake test"]

data/lib/config_files/file_factory.rb

@@ -1,14 +1,18 @@
+# frozen_string_literal: true
+
 module ConfigFiles
   class FileFactory
     class << self
       private
+
       def loader(file_name, options)
-        LoaderFactory.(file_name, options)
+        LoaderFactory.call(file_name, options)
       end
 
       public
-      def call(file_name, options={})
-        loader(file_name, options).(file_name)
+
+      def call(file_name, options = {})
+        loader(file_name, options).call(file_name)
       end
     end
   end

data/lib/config_files/loader_factory.rb

@@ -1,19 +1,24 @@
+# frozen_string_literal: true
+
 module ConfigFiles
   class LoaderFactory
     class << self
-      public
-      def call(file_name, options={include_default: true})
+      def call(file_name, options = { include_default: true })
         new(options).call(file_name)
       end
     end
 
     private
+
     attr_reader :options
 
     def default_loaders
       {
-        Loaders::Yaml => ['yaml', 'yml'],
-        Loaders::Json =>  ['json']
+        Loaders::Yaml => %w[yaml yml],
+        Loaders::Json => ['json'],
+        Loaders::Conf => ['conf'],
+        Loaders::Ini => ['ini'],
+        Loaders::Xml => ['xml'],
       }
     end
 
@@ -25,7 +30,7 @@ module ConfigFiles
       {
         include_default: true,
         default_loader: Loaders::Yaml,
-        loaders: default_loaders
+        loaders: default_loaders,
       }
     end
 
@@ -37,16 +42,20 @@ module ConfigFiles
       options[:loaders]
     end
 
-    def initialize(options) #Note the check below is necessary, because we only want to do it if it is explicity set
-      @options=default_options.merge(options)
-      if include_default_loaders?
-        @options[:loaders]=default_loaders.merge(loaders)
-      end
+    # Note the check below is necessary, because we only want to do it if it is explicity set
+    def initialize(options)
+      @options = default_options.merge(options)
+      return unless include_default_loaders?
+
+      @options[:loaders] = default_loaders.merge(loaders)
     end
 
     public
+
     def call(file_name)
-      loaders.detect{|_, extensions| extensions.include?(::File.extname(file_name).strip.downcase[1..-1])}&.first || default_loader
+      loaders.detect do |_, extensions|
+        extensions.include?(::File.extname(file_name).strip.downcase[1..])
+      end&.first || default_loader
     end
   end
 end