complex_config 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a31f4ffa0d9542e26c19f2a3e6e664e996ebc69d4c700832159bbf4448d3e881
-  data.tar.gz: c81b874b5e802bb66b888727ed63c0573be0ee68e9b141d4ef54478b352d6406
+  metadata.gz: 344002a57feb04b6b964c0a22190b91eb6516329583141521bb28b1151801a12
+  data.tar.gz: c4827ea899280f0a61fb12aff86e38873e108146a21fddac406417b0a8aac838
 SHA512:
-  metadata.gz: 6de56cb12568bbb945ddc06fae9065e98de0e09ba48d18a7bb1c0ec05b47e5e8995f1413a46fb425f0e02392b427ad35f763dd7d668d00a0565ea998b85484f9
-  data.tar.gz: abb1787b14b12a6565134a95480cff03cc69efac45cbb455c6ddb774a5911fa891b90d91e02c6518b43817e3cc56b9880f8af40f22d213a8e6f5b03081ac375f
+  metadata.gz: 81baebce37c27193f528b07c5b5104d3527de3ece471df7493664832b53a5c69a24c120200e5814e34eeeeac9c31c4fbc28ede81ad8957f59cf98533bc40569d
+  data.tar.gz: b22c324308a9b432a1134cb357ab98b8656f00c72052d462fcbe7c7c5972b4f7583f29d1fa332c94be80225bd44ebbc4137e77b6b1d7a9f9ab2c87b35b67ac55

data/.github/workflows/static.yml

@@ -0,0 +1,51 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: [ "master" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+      - name: Generate Documentation
+        run: |
+          gem install gem_hadar
+          bundle install
+          rake doc
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'doc'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/CHANGES.md

@@ -1,3 +1,55 @@
+# Changes
+
+## 2026-07-10 v0.26.0
+
+### New Features
+
+- Added raw data decryption and CLI piping support via
+  `ComplexConfig::Provider#decrypt_data`.
+- Enhanced the `complex_config` CLI:
+    - Added `-k` flag to specify an explicit key file path.
+    - Added `-I` flag to enable streaming decryption from stdin directly to
+      stdout.
+- Introduced a GitHub Actions workflow (`static.yml`) for automated
+  documentation deployment to GitHub Pages using Ruby **3.4**.
+
+### Improvements & Changes
+
+- Renamed `ComplexConfig::Settings#attributes_update_if_nil` to
+  `ComplexConfig::Settings#attributes_update_if_undefined` to better reflect
+  that it preserves existing keys, including explicit `nil` overrides. A
+  deprecation layer was added to the old method.
+- Hardened the encryption CLI by replacing `Tempfile.open` with
+  `Tempfile.create` and adding a `.yml` suffix to temporary files for improved
+  editor syntax highlighting.
+- Updated dependencies:
+    - `gem_hadar` updated from **~> 2.10** to **>= 2.17.1**.
+    - `s.rubygems_version` updated from **4.0.2** to **4.0.10**.
+- Updated the Alpine build image to use stable Ruby **4.0** instead of
+  **4.0-rc**.
+- Added changelog configuration to the `Rakefile` using `GemHadar`.
+
+### Documentation
+
+- Expanded `README.md` with:
+  - A guide on securely comparing encrypted secrets using process
+    substitution and the `-I` flag.
+  - Examples for automation and piping using input redirection (`<`).
+  - Critical security warnings regarding plain-text secrets in version
+    control.
+  - Updated instructions for the `edit` command and `recrypt` backup
+    strategies.
+  - A link to the API documentation.
+- Added an `@example` block to `ComplexConfig::Provider#decrypt_config`
+  documenting the automatic appending of the `.enc` extension.
+
+### Tests
+
+- Added test cases in `spec/complex_config/provider_spec.rb` for
+  `ComplexConfig::Provider#decrypt_config`.
+- Expanded `spec/complex_config/settings_spec.rb` to cover `attributes_update`,
+  `attributes_update_if_undefined`, and the associated deprecation warning.
+
 ## 2025-12-19 v0.25.0
 
 - Added support for Ruby **4.0**-rc-alpine image in test matrix

data/README.md

@@ -6,6 +6,10 @@ This library makes your YAML configuration files available via a nice API. It
 also supports different configurations for each `RAILS_ENV` environment and
 using plugins to return more complex settings values. 🚀
 
+## Documentation
+
+Complete API documentation is available at: [GitHub.io](https://flori.github.io/complex_config/)
+
 ## Architecture Overview 🏗️
 
 ComplexConfig follows a well-defined architectural pattern with clear
@@ -269,8 +273,8 @@ plain text.
 
 ```ruby
 # Write encrypted configuration
-ComplexConfig::Provider.write_config('database', 
-  value: { password: 'secret_password' }, 
+ComplexConfig::Provider.write_config('database',
+  value: { password: 'secret_password' },
   encrypt: :random
 )
 # => Returns the random 128-bit master key as hexadecimal string.
@@ -334,22 +338,22 @@ easy access during development and deployment.
 - **Secure File Operations**: Encrypts/decrypts configuration files with
   automatic backup handling
 - **Edit Support**: Opens encrypted files in your preferred editor (`EDITOR`
-  environment variable or `vi` by default) 
+  environment variable or `vi` by default)
 - **Key Management**: Generates new encryption keys and supports key rotation
 - **Atomic Writes**: Uses secure file writing to prevent data corruption
 
 #### Usage Examples 📋
 
 ```bash
+# 🛡️ Safely edit an encrypted configuration file
+complex_config edit config/database.yml.enc
+
 # Encrypt a configuration file
 complex_config encrypt config/database.yml
 
-# Decrypt a configuration file  
+# Decrypt a configuration file
 complex_config decrypt config/database.yml.enc
 
-# Edit an encrypted configuration file
-complex_config edit config/database.yml.enc
-
 # Display decrypted content without writing to disk
 complex_config display config/database.yml.enc
 
@@ -360,17 +364,51 @@ complex_config new_key
 complex_config recrypt -o OLD_KEY -n NEW_KEY config/database.yml.enc
 ```
 
+#### Automation & Piping 🚀
+
+The `complex_config` tool can be used as a filter in shell pipelines by reading
+encrypted data from standard input via the `-I` flag. This is ideal for CI/CD
+pipelines or secret managers where keys are provided via environment variables
+or explicit paths.
+
+```bash
+# Decrypt a file using redirection
+< config/database.yml.enc complex_config decrypt -I
+
+# Decrypt using an explicit key file instead of environment variables
+< config/database.yml.enc complex_config decrypt -I -k config/database.yml.key
+```
+
+#### Advanced: Securely Comparing Encrypted Secrets 🧙‍♂️
+
+For the ultimate security workflow, you can combine process substitution with
+the piping feature to compare encrypted files without ever writing plain-text
+secrets to your disk. This is particularly useful for diffing a current secret
+against a previous version in Git history.
+
+```bash
+# Diff secrets in the current branch against those stored in the master branch
+diff --color -u <(git show master:config/secrets.yml.enc | complex_config decrypt -I) <(complex_config decrypt -O config/secrets.yml.enc)
+```
+
 #### Security Considerations ⚠️
 
 The script uses symmetric encryption for configuration files. When using
 encrypted configurations:
 
-1. **Key Management**: Store your encryption keys securely (never in version
+
+1. **Avoid Manual Decryption**: Strictly avoid using `complex_config decrypt`
+   to create plain-text copies of secrets on your filesystem. Plain-text secret
+   files are frequently committed to version control by accident (e.g., via
+   `git add .`), leading to catastrophic security breaches. Always use
+   `complex_config edit`, which uses a tempfile and avoids the creation of a
+   unencrypted copy in the repository.
+2. **Key Management**: Store your encryption keys securely (never in version
    control)
-2. **File Permissions**: Ensure encrypted `.enc` files have appropriate
+3. **File Permissions**: Ensure encrypted `.enc` files have appropriate
    permissions
-3. **Backup Strategy**: The `recrypt` command automatically creates backup
-   files
+4. **Backup Strategy**: The `recrypt` command automatically creates backup
+   files, you can delete them afterwards if everything worked.
 
 #### Integration with ComplexConfig 🔗
 

data/Rakefile

@@ -21,6 +21,14 @@ GemHadar do
   title       "#{name.camelize} -- configuration library"
   licenses    << 'Apache-2.0'
 
+  changelog do
+    filename 'CHANGES.md'
+  end
+
+  github_workflows(
+    'static.yml' => {}
+  )
+
   clobber 'coverage'
 
   dependency             'json'

data/VERSION

@@ -1 +1 @@
-0.25.0
+0.26.0

data/bin/complex_config

@@ -17,7 +17,7 @@ require 'tempfile'
 require 'fileutils'
 include FileUtils
 
-$opts = go 'o:n:IOh'
+$opts = go 'o:n:k:IOh'
 
 # The usage method displays help information and exits the program
 #
@@ -44,7 +44,9 @@ def usage(msg: 'Displaying help', rc: 0)
     Options are
 
       -c CONFIG_DIR  set CONFIG_DIR (default: "./config")
-      -I             read input from stdin instead of file (encrypt)
+      -k KEY_PATH    the path to the keyfile used if any (decrypt -I)
+      -I             read input from stdin instead of file (encrypt/decrypt)
+                     for decrypt this option implies -O
       -O             write output to stdout instead of file (decrypt)
       -h             this help
 
@@ -87,7 +89,7 @@ when 'edit'
   fn = fetch_filename
   catch :did_not_change do
     File.secure_write(fn + '.enc') do |f|
-      Tempfile.open('complex_config') do |t|
+      Tempfile.create(%w[ complex_config .yml ]) do |t|
         config = ComplexConfig::Provider.decrypt_config(fn)
         t.write config
         t.flush
@@ -104,10 +106,13 @@ when 'edit'
     end
   end
 when 'decrypt'
-  fn = fetch_filename
-  if $opts[?O]
+  if $opts[?I]
+    $stdout.puts ComplexConfig::Provider.decrypt_data($stdin.read, $opts[?k])
+  elsif $opts[?O]
+    fn = fetch_filename
     $stdout.puts ComplexConfig::Provider.decrypt_config(fn)
   else
+    fn = fetch_filename
     File.exist?(fn) and usage msg: "decrypted config #{fn.inspect} already exists", rc: 1
     File.secure_write(fn) do |f|
       f.write ComplexConfig::Provider.decrypt_config(fn)

data/complex_config.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: complex_config 0.25.0 ruby lib
+# stub: complex_config 0.26.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "complex_config".freeze
-  s.version = "0.25.0".freeze
+  s.version = "0.26.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -13,17 +13,17 @@ Gem::Specification.new do |s|
   s.email = "flori@ping.de".freeze
   s.executables = ["complex_config".freeze]
   s.extra_rdoc_files = ["README.md".freeze, "lib/complex_config.rb".freeze, "lib/complex_config/config.rb".freeze, "lib/complex_config/encryption.rb".freeze, "lib/complex_config/errors.rb".freeze, "lib/complex_config/key_source.rb".freeze, "lib/complex_config/plugins.rb".freeze, "lib/complex_config/plugins/enable.rb".freeze, "lib/complex_config/plugins/money.rb".freeze, "lib/complex_config/plugins/uri.rb".freeze, "lib/complex_config/provider.rb".freeze, "lib/complex_config/provider/shortcuts.rb".freeze, "lib/complex_config/proxy.rb".freeze, "lib/complex_config/railtie.rb".freeze, "lib/complex_config/rude.rb".freeze, "lib/complex_config/settings.rb".freeze, "lib/complex_config/shortcuts.rb".freeze, "lib/complex_config/tree.rb".freeze, "lib/complex_config/version.rb".freeze]
-  s.files = ["CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/complex_config".freeze, "complex_config.gemspec".freeze, "config/products.yml".freeze, "lib/complex_config.rb".freeze, "lib/complex_config/config.rb".freeze, "lib/complex_config/encryption.rb".freeze, "lib/complex_config/errors.rb".freeze, "lib/complex_config/key_source.rb".freeze, "lib/complex_config/plugins.rb".freeze, "lib/complex_config/plugins/enable.rb".freeze, "lib/complex_config/plugins/money.rb".freeze, "lib/complex_config/plugins/uri.rb".freeze, "lib/complex_config/provider.rb".freeze, "lib/complex_config/provider/shortcuts.rb".freeze, "lib/complex_config/proxy.rb".freeze, "lib/complex_config/railtie.rb".freeze, "lib/complex_config/rude.rb".freeze, "lib/complex_config/settings.rb".freeze, "lib/complex_config/shortcuts.rb".freeze, "lib/complex_config/tree.rb".freeze, "lib/complex_config/version.rb".freeze, "spec/complex_config/config_spec.rb".freeze, "spec/complex_config/encryption_spec.rb".freeze, "spec/complex_config/key_source_spec.rb".freeze, "spec/complex_config/plugins_spec.rb".freeze, "spec/complex_config/provider_spec.rb".freeze, "spec/complex_config/settings_spec.rb".freeze, "spec/complex_config/shortcuts_spec.rb".freeze, "spec/config/broken_config.yml".freeze, "spec/config/config.yml".freeze, "spec/config/config_with_alias.yml".freeze, "spec/config/empty_config.yml".freeze, "spec/config/legacy_classes.yml".freeze, "spec/config/master.key".freeze, "spec/config/with-key-file.yml.enc".freeze, "spec/config/with-key-file.yml.key".freeze, "spec/config/without-key-file.yml.enc".freeze, "spec/spec_helper.rb".freeze]
+  s.files = [".github/workflows/static.yml".freeze, "CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "VERSION".freeze, "bin/complex_config".freeze, "complex_config.gemspec".freeze, "config/products.yml".freeze, "lib/complex_config.rb".freeze, "lib/complex_config/config.rb".freeze, "lib/complex_config/encryption.rb".freeze, "lib/complex_config/errors.rb".freeze, "lib/complex_config/key_source.rb".freeze, "lib/complex_config/plugins.rb".freeze, "lib/complex_config/plugins/enable.rb".freeze, "lib/complex_config/plugins/money.rb".freeze, "lib/complex_config/plugins/uri.rb".freeze, "lib/complex_config/provider.rb".freeze, "lib/complex_config/provider/shortcuts.rb".freeze, "lib/complex_config/proxy.rb".freeze, "lib/complex_config/railtie.rb".freeze, "lib/complex_config/rude.rb".freeze, "lib/complex_config/settings.rb".freeze, "lib/complex_config/shortcuts.rb".freeze, "lib/complex_config/tree.rb".freeze, "lib/complex_config/version.rb".freeze, "spec/complex_config/config_spec.rb".freeze, "spec/complex_config/encryption_spec.rb".freeze, "spec/complex_config/key_source_spec.rb".freeze, "spec/complex_config/plugins_spec.rb".freeze, "spec/complex_config/provider_spec.rb".freeze, "spec/complex_config/settings_spec.rb".freeze, "spec/complex_config/shortcuts_spec.rb".freeze, "spec/config/broken_config.yml".freeze, "spec/config/config.yml".freeze, "spec/config/config_with_alias.yml".freeze, "spec/config/empty_config.yml".freeze, "spec/config/legacy_classes.yml".freeze, "spec/config/master.key".freeze, "spec/config/with-key-file.yml.enc".freeze, "spec/config/with-key-file.yml.key".freeze, "spec/config/without-key-file.yml.enc".freeze, "spec/spec_helper.rb".freeze]
   s.homepage = "https://github.com/flori/complex_config".freeze
   s.licenses = ["Apache-2.0".freeze]
   s.rdoc_options = ["--title".freeze, "ComplexConfig -- configuration library".freeze, "--main".freeze, "README.md".freeze]
-  s.rubygems_version = "4.0.2".freeze
+  s.rubygems_version = "4.0.10".freeze
   s.summary = "configuration library".freeze
   s.test_files = ["spec/complex_config/config_spec.rb".freeze, "spec/complex_config/encryption_spec.rb".freeze, "spec/complex_config/key_source_spec.rb".freeze, "spec/complex_config/plugins_spec.rb".freeze, "spec/complex_config/provider_spec.rb".freeze, "spec/complex_config/settings_spec.rb".freeze, "spec/complex_config/shortcuts_spec.rb".freeze, "spec/spec_helper.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.10".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, [">= 2.17.1".freeze])
   s.add_development_dependency(%q<rake>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<rspec>.freeze, [">= 0".freeze])

data/lib/complex_config/provider.rb

@@ -187,6 +187,12 @@ class ComplexConfig::Provider
   # The decrypt_config method retrieves decrypted configuration data from an
   # encrypted file
   #
+  # @example Decrypting a configuration file
+  #   provider = ComplexConfig::Provider
+  #   # Note: The method automatically appends '.enc' to the provided path
+  #   decrypted_yaml = provider.decrypt_config('config/database.yml')
+  #   puts decrypted_yaml if decrypted_yaml
+  #
   # @param pathname [String, Pathname] the path to the encrypted configuration
   #   file
   #
@@ -199,6 +205,23 @@ class ComplexConfig::Provider
     decrypt_config_case(pathname).first
   end
 
+  # The decrypt_data method decrypts raw ciphertext using the provider's key
+  # source
+  #
+  # This method bypasses filesystem lookups for the encrypted data itself,
+  # allowing decryption of raw bytes. It uses the provided pathname to resolve
+  # the encryption key; if no pathname is provided, it relies on environment
+  # variables or the master key.
+  #
+  # @param ciphertext [String] the encrypted data to decrypt
+  # @param pathname [String, nil] an optional path used to locate a key file (e.g., .key)
+  # @return [String, nil] the decrypted plain text, or nil if no valid key was found
+  def decrypt_data(ciphertext, pathname = nil)
+    ks = key_source(pathname)
+    return nil unless ks && ks.key
+    ComplexConfig::Encryption.new(ks.key_bytes).decrypt(ciphertext)
+  end
+
   # The encrypt_config method encrypts configuration data using a key source
   #
   # @param pathname [String, Pathname] the path to the configuration file to be
@@ -264,7 +287,7 @@ class ComplexConfig::Provider
       shared = shared.to_h
       settings.each do |key, value|
         if value.is_a? ComplexConfig::Settings
-          value.attributes_update_if_nil(shared)
+          value.attributes_update_if_undefined(shared)
         elsif value.nil?
           settings[key] = ComplexConfig::Settings.build(nil, shared.dup)
         end

data/lib/complex_config/settings.rb

@@ -20,7 +20,6 @@ class ComplexConfig::Settings < BasicObject
   include ::Tins::AskAndSend
 
   class << self
-
     # The [] method converts a hash-like object into a Settings object
     #
     # This method serves as a convenience accessor that delegates to the
@@ -202,8 +201,6 @@ class ComplexConfig::Settings < BasicObject
   #
   # @param other [Object] the source containing attributes to merge, which can
   #   be any object that responds to to_hash or to_ary
-  #
-  # @return [void] Returns nothing
   def attributes_update(other)
     unless other.is_a? self.class
       other = self.class.from_hash(other)
@@ -211,19 +208,19 @@ class ComplexConfig::Settings < BasicObject
     @table.update(other.table)
   end
 
-  # The attributes_update_if_nil method merges configuration attributes from
-  # another source, updating only nil values
+  # The attributes_update_if_undefined method merges configuration attributes from
+  # another source, updating only those that are completely missing (undefined)
+  # in this settings object.
   #
-  # This method updates the current object's internal table with attributes
-  # from another source, but only assigns new values when the existing keys
-  # have nil values. It preserves existing non-nil attribute values while
-  # allowing nil values to be overridden.
+  # This is specifically used for shared settings patterns where environment-specific
+  # configurations must be respected. Because it only updates missing keys, any
+  # attribute explicitly set—including an explicit `nil` value intended to disable
+  # a feature or clear a default—will be preserved and not overwritten by the
+  # provided shared configuration source.
   #
   # @param other [Object] the source containing attributes to merge, which can
   #   be any object that responds to to_hash or to_ary
-  #
-  # @return [void] Returns nothing
-  def attributes_update_if_nil(other)
+  def attributes_update_if_undefined(other)
     unless other.is_a? self.class
       other = self.class.from_hash(other)
     end
@@ -232,6 +229,22 @@ class ComplexConfig::Settings < BasicObject
     end
   end
 
+  # The attributes_update_if_nil does the same attributes_update_if_undefined
+  # does.
+  #
+  # @deprecated Use #attributes_update_if_undefined instead. This method is kept
+  #   for backward compatibility but now delegates to #attributes_update_if_undefined
+  #   to ensure explicit `nil` overrides are respected.
+  #
+  # @param other [Object] the source containing attributes to merge, which can
+  #   be any object that responds to to_hash or to_ary
+  def attributes_update_if_nil(other)
+    warn '[DEPRECATION] `%{method}` is deprecated. Please use `%{new_method}` instead.' % {
+      method: __method__, new_method: :attributes_update_if_undefined
+    }
+    attributes_update_if_undefined(other)
+  end
+
   # The replace_attributes method replaces all attributes with those from the
   # provided hash
   #
@@ -447,7 +460,6 @@ class ComplexConfig::Settings < BasicObject
   # string representation for display purposes
   #
   # @param q [PrettyPrint] the pretty printer object to use for formatting
-  # @return [void] Returns nothing
   def pretty_print(q)
     q.text inspect
   end
@@ -599,9 +611,6 @@ class ComplexConfig::Settings < BasicObject
   end
 
   # The skip method raises a skip exception to bypass plugin execution
-  #
-  # @return [void] This method always raises a :skip exception and never
-  #   returns normally
   def skip
     throw :skip
   end

data/lib/complex_config/version.rb

@@ -1,6 +1,6 @@
 module ComplexConfig
   # ComplexConfig version
-  VERSION         = '0.25.0'
+  VERSION         = '0.26.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/spec/complex_config/provider_spec.rb

@@ -165,6 +165,18 @@ describe ComplexConfig::Provider do
       ENV['RAILS_MASTER_KEY'] = nil
     end
 
+    it 'can decrypt from pathname returning content' do
+      described_class.key = key
+      expect(described_class.key).to eq key.chomp
+      decrypted = described_class.decrypt_config(asset('without-key-file.yml'))
+      expect(decrypted).to eq <<~EOT
+        ---
+        :development:
+          :foo:
+            :bar: baz
+      EOT
+    end
+
     it 'can read when key is stored in file' do
       expect(described_class['with-key-file'].development.foo.bar).to eq 'baz'
     end

data/spec/complex_config/settings_spec.rb

@@ -209,4 +209,53 @@ EOT
     expect(settings.foo.replaced).to eq true
     expect(settings.foo).to eq result
   end
+
+  it 'can update attributes from a hash' do
+    settings.foo.attributes_update(updated: 'yes', baz: 'new')
+    expect(settings.foo.updated).to eq 'yes'
+    expect(settings.foo.baz).to eq 'new'
+  end
+
+  it 'can update attributes from another Settings object' do
+    other = described_class[val: 'new']
+    settings.foo.attributes_update(other)
+    expect(settings.foo.val).to eq 'new'
+  end
+
+  it 'can update attributes only if they are missing (attributes_update_if_undefined)' do
+    # Current settings.foo has { bar: { baz: true }, nix: nil, qux: 'quux' }
+    updates = {
+      nix:     'filled',
+      qux:     'should_stay_quux',
+      new_key: 'added'
+    }
+
+    settings.foo.attributes_update_if_undefined(updates)
+
+    expect(settings.foo.nix).to be_nil
+    expect(settings.foo.qux).to eq 'quux'               # Key exists and is not nil, should NOT be updated
+    expect(settings.foo.new_key).to eq 'added'          # Key missing, should be added
+  end
+
+  it 'does not overwrite existing values with attributes_update_if_undefined' do
+    s = described_class.new(existing: 'keep')
+    updates = { existing: 'change', other: 'add' }
+
+    s.attributes_update_if_undefined(updates)
+
+    expect(s.existing).to eq 'keep'
+    expect(s.other).to eq 'add'
+  end
+
+  it 'calls attributes_update_if_undefined and warns when using deprecated attributes_update_if_nil' do
+    s = described_class.new(existing: 'keep')
+    updates = { existing: 'change', other: 'add' }
+
+    expect {
+      s.attributes_update_if_nil(updates)
+    }.to output(/DEPRECATION.*attributes_update_if_undefined/).to_stderr
+
+    expect(s.existing).to eq 'keep'
+    expect(s.other).to eq 'add'
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: complex_config
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Florian Frank
@@ -13,16 +13,16 @@ dependencies:
   name: gem_hadar
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.10'
+        version: 2.17.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '2.10'
+        version: 2.17.1
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -203,6 +203,7 @@ extra_rdoc_files:
 - lib/complex_config/tree.rb
 - lib/complex_config/version.rb
 files:
+- ".github/workflows/static.yml"
 - CHANGES.md
 - Gemfile
 - LICENSE
@@ -269,7 +270,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: configuration library
 test_files: