🔧 Add config inheritance

Inheritance forms a singly-linked-list, so lookup will be O(n) on the
number of ancestors.  So arbitrarily deep ancestor lists may have poor
performance, but normal cases should be fine.  Without customization,
ancestor trees will be three or four deep:
    client -> [versioned ->] global -> default

Author: nevans

lib/net/imap/config.rb

@@ -2,12 +2,27 @@
 # :markup: markdown
 
 require_relative "config/attr_accessors"
+require_relative "config/attr_inheritance"
 
 module Net
   class IMAP
 
     # Net::IMAP::Config stores configuration options for Net::IMAP clients.
     #
+    # ## Inheritance
+    #
+    # Configs have a parent[rdoc-ref:Config::AttrInheritance#parent] config, and
+    # any attributes which have not been set locally will inherit the parent's
+    # value.
+    #
+    # See the following methods, defined by Config::AttrInheritance:
+    # - {#new}[rdoc-ref:Config::AttrInheritance#reset] -- create a new config
+    #   which inherits from the receiver.
+    # - {#inherited?}[rdoc-ref:Config::AttrInheritance#inherited?] -- return
+    #   whether a particular attribute is inherited.
+    # - {#reset}[rdoc-ref:Config::AttrInheritance#reset] -- reset attributes to
+    #   be inherited.
+    #
     # ## Thread Safety
     #
     # *NOTE:* Updates to config objects are not synchronized for thread-safety.
@@ -17,6 +32,7 @@ class Config
       def self.default; @default end
 
       include AttrAccessors
+      include AttrInheritance
 
       # The debug mode (boolean)
       #
@@ -46,9 +62,11 @@ def self.default; @default end
 
       # Creates a new config object and initialize its attribute with +attrs+.
       #
+      # If +parent+ is not given, the global config is used by default.
+      #
       # If a block is given, the new config object is yielded to it.
-      def initialize(**attrs)
-        super()
+      def initialize(parent = nil, **attrs)
+        super(parent)
         attrs.each do send(:"#{_1}=", _2) end
         yield self if block_given?
       end

lib/net/imap/config/attr_inheritance.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    class Config
+      # Inheritance forms a singly-linked-list, so lookup will be O(n) on the
+      # number of ancestors.  Without customization, ancestor trees will only be
+      # three or four deep:
+      #     client -> [versioned ->] global -> default
+      module AttrInheritance
+        INHERITED = Module.new.freeze
+        private_constant :INHERITED
+
+        module Macros # :nodoc: internal API
+          def attr_accessor(name) super; AttrInheritance.attr_accessor(name) end
+        end
+        private_constant :Macros
+
+        def self.included(mod)
+          mod.extend Macros
+        end
+        private_class_method :included
+
+        def self.attr_accessor(name) # :nodoc: internal API
+          module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{name}; (val = super) == INHERITED ? parent&.#{name} : val end
+          RUBY
+        end
+
+        # The parent Config object
+        attr_reader :parent
+
+        def initialize(parent = nil) # :notnew:
+          super()
+          @parent = parent
+          reset
+        end
+
+        # Creates a new config, which inherits from +self+.
+        def new(**attrs) self.class.new(self, **attrs) end
+
+        # Returns +true+ if +attr+ is inherited from #parent and not overridden
+        # by this config.
+        def inherited?(attr) data[attr] == INHERITED end
+
+        # :call-seq:
+        #   reset -> self
+        #   reset(attr) -> attribute value
+        #
+        # Resets an +attr+ to inherit from the #parent config.
+        #
+        # When +attr+ is nil or not given, all attributes are reset.
+        def reset(attr = nil)
+          if attr.nil?
+            data.members.each do |attr| data[attr] = INHERITED end
+            self
+          elsif inherited?(attr)
+            nil
+          else
+            old, data[attr] = data[attr], INHERITED
+            old
+          end
+        end
+
+        private
+
+        def initialize_copy(other)
+          super
+          @parent ||= other # only default has nil parent
+        end
+
+      end
+    end
+  end
+end

test/net/imap/test_config.rb

@@ -32,4 +32,75 @@ class ConfigTest < Test::Unit::TestCase
     refute default.debug?
   end
 
+  test ".new(parent, ...) and inheritance" do
+    base = Config.new debug: false
+    child = Config.new(base)
+    assert_equal base, child.parent
+    assert_equal false, child.debug
+    assert_equal false, child.debug?
+    base.debug = true
+    assert_equal true, child.debug?
+    child.debug = false
+    assert_equal false, child.debug?
+    child.reset(:debug)
+    assert_equal true, child.debug?
+    base.debug = false
+    child.debug = true
+    assert_equal true, child.debug?
+    child = Config.new(base, debug: true)
+    assert_equal true, child.debug?
+    base.debug = true
+    child = Config.new(base, debug: false)
+    assert_equal false, child.debug?
+  end
+
+  test "#new and inheritance" do
+    base = Config.new debug: false
+    child = base.new
+    assert_equal base, child.parent
+    assert_equal false, child.debug
+    assert_equal false, child.debug?
+    base.debug = true
+    assert_equal true, child.debug?
+    child.debug = false
+    assert_equal false, child.debug?
+    child.reset(:debug)
+    assert_equal true, child.debug?
+    base.debug = false
+    child.debug = true
+    assert_equal true, child.debug?
+    child = base.new(debug: true)
+    assert_equal true, child.debug?
+    base.debug = true
+    child = base.new(debug: false)
+    assert_equal false, child.debug?
+  end
+
+  test "#inherited? and #reset(attr)" do
+    base = Config.new debug: false, open_timeout: 99, idle_response_timeout: 15
+    child = base.new debug: true, open_timeout: 15, idle_response_timeout: 10
+    refute child.inherited?(:idle_response_timeout)
+    assert_equal 10, child.reset(:idle_response_timeout)
+    assert child.inherited?(:idle_response_timeout)
+    assert_equal 15, child.idle_response_timeout
+    refute child.inherited?(:open_timeout)
+    refute child.inherited?(:debug)
+    child.debug = false
+    refute child.inherited?(:debug)
+    assert_equal false, child.reset(:debug)
+    assert child.inherited?(:debug)
+    assert_equal false, child.debug
+    assert_equal nil, child.reset(:debug)
+  end
+
+  test "#reset all attributes" do
+    base = Config.new debug: false, open_timeout: 99, idle_response_timeout: 15
+    child = base.new debug: true, open_timeout: 15, idle_response_timeout: 10
+    result = child.reset
+    assert_same child, result
+    assert child.inherited?(:debug)
+    assert child.inherited?(:open_timeout)
+    assert child.inherited?(:idle_response_timeout)
+  end
+
 end