net-imap 0.4.13 → 0.4.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a7254a9f8865dfd12d8887a0ce62f58d764f43acb3eea019fadd13ff3f6983c
-  data.tar.gz: 8a3ae5456b5a7d78f72d862e6dcf8f8df86ec6a3d32956314c1eadc36bf5def0
+  metadata.gz: 06be993e038a4432ec954b11701ce86f946c456f9125d2b539e6c21d05e728ab
+  data.tar.gz: 7807fb77537a843e9d9a2ad0ad892dc3e75af3a734f2c4c68a1e2cbae4d34ef1
 SHA512:
-  metadata.gz: 41ee8dd354e77a06f4875ad559efb6dbae6f60c39ad714d0de46efe8a49e125194b48e02cce4d1425c73122c57ec300dcd4e7707409bcf964318146b3b9e6168
-  data.tar.gz: 215057347ecca04a9816df24b5250f124b2b655615507ef84e6b2a12567b23810da9f394f74801cd046c18e7d01072a567b95eb241bb7db7896982e9d24e414f
+  metadata.gz: 182edade4a45d1c6f4772332f2f9cd4704827895770764202aa843bfbb754defff11a8037c1955e352642201c57cea850ea51aa8e4fe6c1761b36c78562b1c5b
+  data.tar.gz: 2fff884a15a87ae7cb4a5ac422f743b5accd1ea98b34bf994cbb18238577cc259a1a672a04e5dac14864ad61bdafd90c43c160ede8ba369246fd3bb265e5cff2

data/lib/net/imap/config/attr_accessors.rb

@@ -59,6 +59,11 @@ module Net
 
         private
 
+        def initialize_clone(other)
+          super
+          @data = other.data.clone
+        end
+
         def initialize_dup(other)
           super
           @data = other.data.dup

data/lib/net/imap/config.rb

@@ -54,25 +54,117 @@ module Net
     #   plain_client.config.inherited?(:debug)  # => true
     #   plain_client.config.debug?  # => false
     #
+    # == Versioned defaults
+    #
+    # The effective default configuration for a specific +x.y+ version of
+    # +net-imap+ can be loaded with the +config+ keyword argument to
+    # Net::IMAP.new.  Requesting default configurations for previous versions
+    # enables extra backward compatibility with those versions:
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.3)
+    #   client.config.sasl_ir                  # => false
+    #   client.config.responses_without_block  # => :silence_deprecation_warning
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.4)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :silence_deprecation_warning
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.5)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :warn
+    #
+    #   client = Net::IMAP.new(hostname, config: :future)
+    #   client.config.sasl_ir                  # => true
+    #   client.config.responses_without_block  # => :raise
+    #
+    # The versioned default configs inherit certain specific config options from
+    # Config.global, for example #debug:
+    #
+    #   client = Net::IMAP.new(hostname, config: 0.4)
+    #   Net::IMAP.debug = false
+    #   client.config.debug?  # => false
+    #
+    #   Net::IMAP.debug = true
+    #   client.config.debug?  # => true
+    #
+    # Use #load_defaults to globally behave like a specific version:
+    #   client = Net::IMAP.new(hostname)
+    #   client.config.sasl_ir              # => true
+    #   Net::IMAP.config.load_defaults 0.3
+    #   client.config.sasl_ir              # => false
+    #
+    # === Named defaults
+    # In addition to +x.y+ version numbers, the following aliases are supported:
+    #
+    # [+:default+]
+    #   An alias for +:current+.
+    #
+    #   >>>
+    #   *NOTE*: This is _not_ the same as Config.default.  It inherits some
+    #   attributes from Config.global, for example: #debug.
+    # [+:current+]
+    #   An alias for the current +x.y+ version's defaults.
+    # [+:next+]
+    #   The _planned_ config for the next +x.y+ version.
+    # [+:future+]
+    #   The _planned_ eventual config for some future +x.y+ version.
+    #
+    # For example, to raise exceptions for all current deprecations:
+    #   client = Net::IMAP.new(hostname, config: :future)
+    #   client.responses  # raises an ArgumentError
     #
     # == Thread Safety
     #
     # *NOTE:* Updates to config objects are not synchronized for thread-safety.
     #
     class Config
+      # Array of attribute names that are _not_ loaded by #load_defaults.
+      DEFAULT_TO_INHERIT = %i[debug].freeze
+      private_constant :DEFAULT_TO_INHERIT
+
       # The default config, which is hardcoded and frozen.
       def self.default; @default end
 
       # The global config object.  Also available from Net::IMAP.config.
-      def self.global; @global end
+      def self.global; @global if defined?(@global) end
+
+      # A hash of hard-coded configurations, indexed by version number.
+      def self.version_defaults; @version_defaults end
+      @version_defaults = {}
 
-      def self.[](config) # :nodoc: unfinished API
-        if config.is_a?(Config) || config.nil? && global.nil?
-          config
+      # :call-seq:
+      #  Net::IMAP::Config[number] -> versioned config
+      #  Net::IMAP::Config[symbol] -> named config
+      #  Net::IMAP::Config[hash]   -> new frozen config
+      #  Net::IMAP::Config[config] -> same config
+      #
+      # Given a version number, returns the default configuration for the target
+      # version.  See Config@Versioned+defaults.
+      #
+      # Given a version name, returns the default configuration for the target
+      # version.  See Config@Named+defaults.
+      #
+      # Given a Hash, creates a new _frozen_ config which inherits from
+      # Config.global.  Use Config.new for an unfrozen config.
+      #
+      # Given a config, returns that same config.
+      def self.[](config)
+        if    config.is_a?(Config)         then config
+        elsif config.nil? && global.nil?   then nil
+        elsif config.respond_to?(:to_hash) then new(global, **config).freeze
         else
-          raise TypeError, "no implicit conversion of %s to %s" % [
-            config.class, Config
-          ]
+          version_defaults.fetch(config) do
+            case config
+            when Numeric
+              raise RangeError, "unknown config version: %p" % [config]
+            when Symbol
+              raise KeyError, "unknown config name: %p" % [config]
+            else
+              raise TypeError, "no implicit conversion of %s to %s" % [
+                config.class, Config
+              ]
+            end
+          end
         end
       end
 
@@ -143,10 +235,72 @@ module Net
       # If a block is given, the new config object is yielded to it.
       def initialize(parent = Config.global, **attrs)
         super(parent)
-        attrs.each do send(:"#{_1}=", _2) end
+        update(**attrs)
         yield self if block_given?
       end
 
+      # :call-seq: update(**attrs) -> self
+      #
+      # Assigns all of the provided +attrs+ to this config, and returns +self+.
+      #
+      # An ArgumentError is raised unless every key in +attrs+ matches an
+      # assignment method on Config.
+      #
+      # >>>
+      #   *NOTE:*  #update is not atomic.  If an exception is raised due to an
+      #   invalid attribute value, +attrs+ may be partially applied.
+      def update(**attrs)
+        unless (bad = attrs.keys.reject { respond_to?(:"#{_1}=") }).empty?
+          raise ArgumentError, "invalid config options: #{bad.join(", ")}"
+        end
+        attrs.each do send(:"#{_1}=", _2) end
+        self
+      end
+
+      # :call-seq:
+      #   with(**attrs) -> config
+      #   with(**attrs) {|config| } -> result
+      #
+      # Without a block, returns a new config which inherits from self.  With a
+      # block, yields the new config and returns the block's result.
+      #
+      # If no keyword arguments are given, an ArgumentError will be raised.
+      #
+      # If +self+ is frozen, the copy will also be frozen.
+      def with(**attrs)
+        attrs.empty? and
+          raise ArgumentError, "expected keyword arguments, none given"
+        copy = new(**attrs)
+        copy.freeze if frozen?
+        block_given? ? yield(copy) : copy
+      end
+
+      # :call-seq: load_defaults(version) -> self
+      #
+      # Resets the current config to behave like the versioned default
+      # configuration for +version+.  #parent will not be changed.
+      #
+      # Some config attributes default to inheriting from their #parent (which
+      # is usually Config.global) and are left unchanged, for example: #debug.
+      #
+      # See Config@Versioned+defaults and Config@Named+defaults.
+      def load_defaults(version)
+        [Numeric, Symbol, String].any? { _1 === version } or
+          raise ArgumentError, "expected number or symbol, got %p" % [version]
+        update(**Config[version].defaults_hash)
+      end
+
+      # :call-seq: to_h -> hash
+      #
+      # Returns all config attributes in a hash.
+      def to_h; data.members.to_h { [_1, send(_1)] } end
+
+      protected
+
+      def defaults_hash
+        to_h.reject {|k,v| DEFAULT_TO_INHERIT.include?(k) }
+      end
+
       @default = new(
         debug: false,
         open_timeout: 30,
@@ -157,6 +311,29 @@ module Net
 
       @global = default.new
 
+      version_defaults[0.4] = Config[default.send(:defaults_hash)]
+
+      version_defaults[0] = Config[0.4].dup.update(
+        sasl_ir: false,
+      ).freeze
+      version_defaults[0.0] = Config[0]
+      version_defaults[0.1] = Config[0]
+      version_defaults[0.2] = Config[0]
+      version_defaults[0.3] = Config[0]
+
+      version_defaults[0.5] = Config[0.4].dup.update(
+        responses_without_block: :warn,
+      ).freeze
+
+      version_defaults[:default] = Config[0.4]
+      version_defaults[:current] = Config[0.4]
+      version_defaults[:next]    = Config[0.5]
+
+      version_defaults[:future]  = Config[0.5].dup.update(
+        responses_without_block: :raise,
+      ).freeze
+
+      version_defaults.freeze
     end
   end
 end

data/lib/net/imap.rb

@@ -717,7 +717,7 @@ module Net
   # * {IMAP URLAUTH Authorization Mechanism Registry}[https://www.iana.org/assignments/urlauth-authorization-mechanism-registry/urlauth-authorization-mechanism-registry.xhtml]
   #
   class IMAP < Protocol
-    VERSION = "0.4.13"
+    VERSION = "0.4.14"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.4.13
+  version: 0.4.14
 platform: ruby
 authors:
 - Shugo Maeda
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-16 00:00:00.000000000 Z
+date: 2024-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol