net-imap 0.4.24 → 0.5.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9419630b908b12c7f89846682dae953e50376d89ebb3b7391b3426bb34480991
-  data.tar.gz: 4558a77d38a4def28af960c201ca9359fcc828d5a316f76f95cf3c0e575702b6
+  metadata.gz: 33bccbb75eba778cb42fc5340afc2f10a899ca671123e8b538a39acbdf16bd1b
+  data.tar.gz: c4252164f38a0f36b827fb32247500e95293880e2f8026f4b7ed04926614df41
 SHA512:
-  metadata.gz: 5f4baf570c8ed5732493ba801121ae092177fca3ab5f9162ef66f0db2a23e91c09fe740d8ddba52977e65737906a6735a8405bb94e923111970621e79b813141
-  data.tar.gz: 624e1b8a76630bffa007391b303eab5729b20665d9a5242f58749e0127340ddd1a842eb94ca46da085ccfa91cc093367348586cde705b51fe3eff25882f8f096
+  metadata.gz: e682041f5c1f0e071578c0910f3eace9438064741cce16b148870c73137fd38926154269907f4948dec365e83b9115facff5ec21ac23072270ef39bab64cea10
+  data.tar.gz: 8a04cac2ad54cd0bc4b2e2f5855bac16f571c3ab6aa0183caa1427ad7c420f8c3920e74b85871c22454dbd827c7772b24cfe96bcaf262222664c05f7483f5dbd

data/Gemfile

@@ -8,9 +8,18 @@ gemspec
 gem "strscan"
 gem "base64"
 
+gem "irb"
 gem "rake"
 gem "rdoc"
 gem "test-unit"
 gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
 
-gem "benchmark-driver"
+gem "benchmark", require: false
+gem "benchmark-driver", require: false
+gem "vernier", require: false, platform: :mri
+
+group :test do
+  gem "simplecov",        require: false, platforms: %i[mri windows]
+  gem "simplecov-html",   require: false, platforms: %i[mri windows]
+  gem "simplecov-json",   require: false, platforms: %i[mri windows]
+end

data/README.md

@@ -1,7 +1,9 @@
 # Net::IMAP
 
 Net::IMAP implements Internet Message Access Protocol (IMAP) client
-functionality.  The protocol is described in [IMAP](https://tools.ietf.org/html/rfc3501).
+functionality.  The protocol is described in
+[RFC3501](https://www.rfc-editor.org/rfc/rfc3501),
+[RFC9051](https://www.rfc-editor.org/rfc/rfc9051) and various extensions.
 
 ## Installation
 
@@ -50,12 +52,16 @@ end
 
 ```ruby
 imap.select('Mail/sent-mail')
-if not imap.list('Mail/', 'sent-apr03')
+if imap.list('Mail/', 'sent-apr03').empty?
   imap.create('Mail/sent-apr03')
 end
 imap.search(["BEFORE", "30-Apr-2003", "SINCE", "1-Apr-2003"]).each do |message_id|
-  imap.copy(message_id, "Mail/sent-apr03")
-  imap.store(message_id, "+FLAGS", [:Deleted])
+  if imap.capable?(:move) || imap.capable?(:IMAP4rev2)
+    imap.move(message_id, "Mail/sent-apr03")
+  else
+    imap.copy(message_id, "Mail/sent-apr03")
+    imap.store(message_id, "+FLAGS", [:Deleted])
+  end
 end
 imap.expunge
 ```

data/docs/styles.css

@@ -1,24 +1,85 @@
 /* this is a work in progress. :) */
 
-main .method-header {
-  background: rgba(27,31,35,0.05);
-  border: 1px solid #6C8C22;
+/***********************************************
+ * Method descriptions
+ ***********************************************/
+
+main .method-detail {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  justify-content: space-between;
+}
+
+main .method-header,
+main .method-controls,
+.attribute-method-heading {
   padding: 0.5em;
-  border-radius: 4px;
-  /* padding: 0 0.5em; */
-  /* border-width: 0 1px; */
-  /* border-color: #6C8C22; */
-  /* border-style: solid; */
+  /* border: 1px solid var(--highlight-color); */
+  background: var(--table-header-background-color);
+  line-height: 1.6;
+}
+
+.attribute-method-heading .attribute-access-type {
+  float: right;
+}
+
+main .method-header {
+  border-right: none;
+  border-radius: 4px 0 0 4px;
+}
+
+main .method-heading :any-link {
+  text-decoration: none;
+}
+
+main .method-controls {
+  border-left: none;
+  border-radius: 0 4px 4px 0;
 }
 
 main .method-description, main .aliases {
+  grid-column: 1 / span 2;
   padding-left: 1em;
 }
 
-body {
-  /*
-   * The default (300) can be too low contrast.  Also, many fonts don't
-   * distinguish between 300->400, so <em>...</em> had no effect.
-   */
-  font-weight: 400;
+@media (max-width: 700px) {
+  main .method-header, main .method-controls, main .method-description {
+    grid-column: 1 / span 2;
+    margin: 0;
+  }
+  main .method-controls {
+    background: none;
+  }
+}
+
+/***********************************************
+ * Description lists
+ ***********************************************/
+
+main dt {
+  margin-bottom: 0; /* override rdoc 6.8 */
+  float: unset;     /* override rdoc 6.8 */
+  line-height: 1.5; /* matches `main p` */
+}
+
+main dl.note-list dt {
+  margin-right: 1em;
+  float: left;
+}
+
+main dl.note-list dt:has(+ dt) {
+  margin-right: 0.25em;
+}
+
+main dl.note-list dt:has(+ dt)::after {
+  content: ', ';
+  font-weight: normal;
+}
+
+main dd {
+  margin: 0 0 1em 1em;
+}
+
+main dd p:first-child {
+  margin-top: 0;
 }

data/lib/net/imap/authenticators.rb

@@ -9,7 +9,7 @@ module Net::IMAP::Authenticators
       "%s.%s is deprecated.  Use %s.%s instead." % [
         Net::IMAP, __method__, Net::IMAP::SASL, __method__
       ],
-      uplevel: 1
+      uplevel: 1, category: :deprecated
     )
     Net::IMAP::SASL.add_authenticator(...)
   end
@@ -20,7 +20,7 @@ module Net::IMAP::Authenticators
       "%s.%s is deprecated.  Use %s.%s instead." % [
         Net::IMAP, __method__, Net::IMAP::SASL, __method__
       ],
-      uplevel: 1
+      uplevel: 1, category: :deprecated
     )
     Net::IMAP::SASL.authenticator(...)
   end

data/lib/net/imap/command_data.rb

@@ -3,6 +3,9 @@
 require "date"
 
 require_relative "errors"
+require_relative "data_lite"
+
+# :enddoc:
 
 module Net
   class IMAP < Protocol
@@ -78,7 +81,7 @@ module Net
       put_string('"' + str.gsub(/["\\]/, "\\\\\\&") + '"')
     end
 
-    def send_binary_literal(*a, **kw) send_literal(*a, **kw, binary: true) end
+    def send_binary_literal(*a, **kw); send_literal(*a, **kw, binary: true) end
 
     # `non_sync` is an optional tri-state flag:
     # * `true`  -> Force non-synchronizing `LITERAL+`/`LITERAL-` behavior.
@@ -130,27 +133,7 @@ module Net
     def send_date_data(date) put_string Net::IMAP.encode_date(date) end
     def send_time_data(time) put_string Net::IMAP.encode_time(time) end
 
-    # simplistic emulation of CommandData = Data.define(:data)
-    class CommandData # :nodoc:
-      class << self
-        def new(arg = nil, data: arg) super(data: data) end
-        alias :[] :new
-      end
-
-      def initialize(data:)
-        @data = data
-        freeze
-      end
-
-      attr_reader :data
-
-      def to_h(&block) block ? to_h.to_h(&block) : { data: data } end
-      def ==(other)   self.class === other && to_h  ==  other.to_h  end
-      def eql?(other) self.class === other && to_h.eql?(other.to_h) end
-
-      # following class definition goes beyond the basic Data.define(:data)
-      ##
-
+    CommandData = Data.define(:data) do # :nodoc:
       def self.validate(...)
         data = new(...)
         data.validate
@@ -179,7 +162,7 @@ module Net
     class RawText < CommandData # :nodoc:
       def initialize(data:)
         data = String(data.to_str)
-        data = if [Encoding::ASCII, Encoding::UTF_8].include?(data.encoding)
+        data = if data.encoding in Encoding::ASCII | Encoding::UTF_8
           -data
         elsif data.ascii_only?
           -(data.dup.force_encoding("ASCII"))
@@ -200,9 +183,9 @@ module Net
         end
       end
 
-      def ascii_only?; data.ascii_only? end
+      def ascii_only? = data.ascii_only?
 
-      def send_data(imap, tag) imap.__send__(:put_string, data) end
+      def send_data(imap, tag) = imap.__send__(:put_string, data)
     end
 
     class RawData < CommandData # :nodoc:
@@ -212,11 +195,10 @@ module Net
         validate
       end
 
-      def send_data(imap, tag) data.each do _1.send_data(imap, tag) end end
+      def send_data(imap, tag) = data.each do _1.send_data(imap, tag) end
 
       def validate
-        return unless RawText === data.last
-        text = data.last.data
+        return unless data.last in RawText(data: text)
         if text.rindex(/~?\{[1-9]\d*\+?\}\z/n)
           raise DataFormatError, "RawData cannot end with literal continuation"
         end
@@ -231,10 +213,7 @@ module Net
           text, binary, bytesize, non_sync, data = $`, !!$1, $2, !!$3, $'
           bytesize = Integer bytesize, 10
           parts << RawText[text] unless text.empty?
-          parts << extract_literal(data,
-                                   binary: binary,
-                                   bytesize: bytesize,
-                                   non_sync: non_sync)
+          parts << extract_literal(data, binary:, bytesize:, non_sync:)
           data[0, bytesize] = ""
         end
         parts << RawText[data] unless data.empty?
@@ -247,7 +226,7 @@ module Net
             "expected: %s, remaining: %s" % [bytesize, data.bytesize]
         end
         literal = data.byteslice(0, bytesize)
-        (binary ? Literal8 : Literal).new(data: literal, non_sync: non_sync)
+        (binary ? Literal8 : Literal).new(data: literal, non_sync:)
       end
     end
 
@@ -275,47 +254,24 @@ module Net
       end
     end
 
-    class QuotedString # :nodoc:
+    class QuotedString < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:send_quoted_string, @data)
-      end
-
-      def validate
-      end
-
-      private
-
-      def initialize(data)
-        @data = data
+        imap.__send__(:send_quoted_string, data)
       end
     end
 
-    class Literal # :nodoc:
-      class << self
-        def new(_data = nil, _non_sync = nil, data: _data, non_sync: _non_sync)
-          super(data: data, non_sync: non_sync)
-        end
-        alias :[] :new
+    class Literal < Data.define(:data, :non_sync) # :nodoc:
+      def self.validate(...)
+        data = new(...)
+        data.validate
+        data
       end
 
-      attr_reader :data, :non_sync
-
-      def to_h(&block) block ? to_h.to_h(&block) : { data: data, non_sync: non_sync } end
-      def ==(other)   self.class === other && to_h  ==  other.to_h  end
-      def eql?(other) self.class === other && to_h.eql?(other.to_h) end
-
       def initialize(data:, non_sync: nil)
         data = -String(data.to_str).b or
           raise DataFormatError, "#{self.class} expects string input"
-        @data, @non_sync = data, non_sync
+        super
         validate
-        freeze
-      end
-
-      def self.validate(...)
-        data = new(...)
-        data.validate
-        data
       end
 
       def bytesize; data.bytesize end
@@ -328,7 +284,7 @@ module Net
       end
 
       def send_data(imap, tag)
-        imap.__send__(:send_literal, data, tag, non_sync: non_sync)
+        imap.__send__(:send_literal, data, tag, non_sync:)
       end
     end
 
@@ -336,23 +292,66 @@ module Net
       def validate; nil end # all bytes are okay
 
       def send_data(imap, tag)
-        imap.__send__(:send_binary_literal, data, tag, non_sync: non_sync)
+        imap.__send__(:send_binary_literal, data, tag, non_sync:)
+      end
+    end
+
+    class PartialRange < CommandData # :nodoc:
+      uint32_max = 2**32 - 1
+      POS_RANGE = 1..uint32_max
+      NEG_RANGE = -uint32_max..-1
+      Positive = ->{ (_1 in Range) and POS_RANGE.cover?(_1) }
+      Negative = ->{ (_1 in Range) and NEG_RANGE.cover?(_1) }
+
+      def initialize(data:)
+        min, max = case data
+        in Range
+          data.minmax.map { Integer _1 }
+        in ResponseParser::Patterns::PARTIAL_RANGE
+          data.split(":").map { Integer _1 }.minmax
+        else
+          raise ArgumentError, "invalid partial range input: %p" % [data]
+        end
+        data = min..max
+        unless data in Positive | Negative
+          raise ArgumentError, "invalid partial-range: %p" % [data]
+        end
+        super
+      rescue TypeError, RangeError
+        raise ArgumentError, "expected range min/max to be Integers"
+      end
+
+      def formatted = "%d:%d" % data.minmax
+
+      def send_data(imap, tag)
+        imap.__send__(:put_string, formatted)
       end
     end
 
-    class MessageSet # :nodoc:
+    # *DEPRECATED*.  Replaced by SequenceSet.
+    class MessageSet < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, format_internal(@data))
+        imap.__send__(:put_string, format_internal(data))
       end
 
       def validate
-        validate_internal(@data)
+        validate_internal(data)
       end
 
       private
 
-      def initialize(data)
-        @data = data
+      def initialize(data:)
+        super
+        warn("DEPRECATED: #{MessageSet} should be replaced with #{SequenceSet}.",
+             uplevel: 1, category: :deprecated)
+        begin
+          # to ensure the input works with SequenceSet, too
+          SequenceSet.new(data)
+        rescue
+          warn "MessageSet input is incompatible with SequenceSet: [%s] %s" % [
+            $!.class, $!.message
+          ]
+        end
       end
 
       def format_internal(data)
@@ -396,22 +395,18 @@ module Net
       end
     end
 
-    class ClientID # :nodoc:
+    class ClientID < CommandData # :nodoc:
 
       def send_data(imap, tag)
-        imap.__send__(:send_data, format_internal(@data), tag)
+        imap.__send__(:send_data, format_internal(data), tag)
       end
 
       def validate
-        validate_internal(@data)
+        validate_internal(data)
       end
 
       private
 
-      def initialize(data)
-        @data = data
-      end
-
       def validate_internal(client_id)
         client_id.to_h.each do |k,v|
           unless StringFormatter.valid_string?(k)

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

@@ -19,7 +19,7 @@ module Net
             AttrTypeCoercion.attr_accessor(attr, type: type)
           end
 
-          module_function def Integer?; NilOrInteger end
+          module_function def Integer? = NilOrInteger
         end
         private_constant :Macros
 
@@ -28,14 +28,26 @@ module Net
         end
         private_class_method :included
 
-        # Used in v0.5.8+ for Ractor sharability.
-        def self.safe(...) nil.instance_eval(...).freeze end
+        if defined?(Ractor.shareable_proc)
+          def self.safe(&b)
+            case obj = b.call
+            when Proc
+              Ractor.shareable_proc(&obj)
+            else
+              Ractor.make_shareable obj
+            end
+          end
+        elsif defined?(Ractor.make_shareable)
+          def self.safe(&b)
+            obj = nil.instance_eval(&b).freeze
+            Ractor.make_shareable obj
+          end
+        else
+          def self.safe(&b) nil.instance_eval(&b).freeze end
+        end
         private_class_method :safe
 
-        Types = Hash.new do |h, type|
-          type.nil? || Proc === type or raise TypeError, "type not nil or Proc"
-          safe{type}
-        end
+        Types = Hash.new do |h, type| type => Proc | nil; safe{type} end
         Types[:boolean] = Boolean = safe{-> {!!_1}}
         Types[Integer]  = safe{->{Integer(_1)}}
 
@@ -48,10 +60,10 @@ module Net
         NilOrInteger = safe{->val { Integer val unless val.nil? }}
 
         Enum = ->(*enum) {
-          enum     = safe{enum}
-          expected = -"one of #{enum.map(&:inspect).join(", ")}"
+          safe_enum = safe{enum}
+          expected = -"one of #{safe_enum.map(&:inspect).join(", ")}"
           safe{->val {
-            return val if enum.include?(val)
+            return val if safe_enum.include?(val)
             raise ArgumentError, "expected %s, got %p" % [expected, val]
           }}
         }

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Net
+  class IMAP
+    class Config
+      # >>>
+      #   *NOTE:* This module is an internal implementation detail, with no
+      #   guarantee of backward compatibility.
+      #
+      # Adds a +defaults+ parameter to +attr_accessor+, which is used to compile
+      # Config.version_defaults.
+      module AttrVersionDefaults
+        # The <tt>x.y</tt> part of Net::IMAP::VERSION, as a Rational number.
+        CURRENT_VERSION = VERSION.to_r
+
+        # The config version used for <tt>Config[:next]</tt>.
+        NEXT_VERSION    = CURRENT_VERSION + 0.1r
+
+        # The config version used for <tt>Config[:future]</tt>.
+        FUTURE_VERSION  = 1.0r
+
+        VERSIONS = ((0.0r..FUTURE_VERSION) % 0.1r).to_a.freeze
+
+        # See Config.version_defaults.
+        singleton_class.attr_reader :version_defaults
+
+        @version_defaults = Hash.new {|h, k|
+          # NOTE: String responds to both so the order is significant.
+          # And ignore non-numeric conversion to zero, because: "wat!?".to_r == 0
+          (h.fetch(k.to_r, nil) || h.fetch(k.to_f, nil) if k.is_a?(Numeric)) ||
+            (h.fetch(k.to_sym, nil) if k.respond_to?(:to_sym)) ||
+            (h.fetch(k.to_r,   nil) if k.respond_to?(:to_r) && k.to_r != 0r) ||
+            (h.fetch(k.to_f,   nil) if k.respond_to?(:to_f) && k.to_f != 0.0)
+        }
+
+        # :stopdoc: internal APIs only
+
+        def attr_accessor(name, defaults: nil, default: (unset = true), **kw)
+          unless unset
+            version  = DEFAULT_TO_INHERIT.include?(name) ? nil : 0.0r
+            defaults = { version => default }
+          end
+          defaults&.each_pair do |version, default|
+            AttrVersionDefaults.version_defaults[version] ||= {}
+            AttrVersionDefaults.version_defaults[version][name] = default
+          end
+          super(name, **kw)
+        end
+
+        def self.compile_default!
+          raise "Config.default already compiled" if Config.default
+          default = VERSIONS.select { _1 <= CURRENT_VERSION }
+            .filter_map { version_defaults[_1] }
+            .prepend(version_defaults.delete(nil))
+            .inject(&:merge)
+          Config.new(**default).freeze
+        end
+
+        def self.compile_version_defaults!
+          # Temporarily assign Config.default, enabling #load_defaults(:default)
+          version_defaults[:default] = Config.default
+          # Use #load_defaults so some attributes are inherited from global.
+          version_defaults[:default] = Config.new.load_defaults(:default).freeze
+          version_defaults[0.0r]     = Config[version_defaults.fetch(0.0r)]
+
+          VERSIONS.each_cons(2) do |prior, version|
+            updates = version_defaults[version]
+            version_defaults[version] = version_defaults[prior]
+              .then { updates ? _1.dup.update(**updates).freeze : _1 }
+          end
+
+          # Safe conversions one way only:
+          #   0.6r.to_f == 0.6  # => true
+          #   0.6 .to_r == 0.6r # => false
+          version_defaults.to_a.each do |k, v|
+            next unless k in Rational
+            version_defaults[k.to_f] = v
+          end
+
+          version_defaults[:original] = Config[0.0r]
+          version_defaults[:current]  = Config[CURRENT_VERSION]
+          version_defaults[:next]     = Config[NEXT_VERSION]
+          version_defaults[:future]   = Config[FUTURE_VERSION]
+
+          version_defaults.freeze
+        end
+
+      end
+    end
+  end
+end