net-imap 0.5.9 → 0.5.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a31378c34762136e5fc341801a0b4073157dc6c35df6aae3254d3f7b90a07b7
-  data.tar.gz: cbf787e39ecfde5a7af0061baba54eae3d7b12077679854ea62b335fc9b48798
+  metadata.gz: b7f77489a5f69bb5cf159039328259e7a0e52d18453b8777ab312b7051ec0542
+  data.tar.gz: d2417b81c84dd93424983354ed42995bfc5af9ac30c8c115c75595a7746e5fc5
 SHA512:
-  metadata.gz: fd0c8a34fa212bb42a55e943bf8184c614256b52da4ac13bdddb48f74c8517f5c7b72addb2153af42d76f2a8bcf42627ceb34e874b7842d8a6dfd542ba577578
-  data.tar.gz: 91dd4d1d35582abb9e4fd0df64c63ee5c9320f3404d548bff0a4023e32dc9a6ddd6b90cd1cc221e637a4719f3cc5699d57cc337ea17a6454b3aa7d7be9ffb423
+  metadata.gz: d20e857ab3284f3c2748da9b7324909d99f87cf8bfe52f44f2e77ba49154a34d39f3008106388e8c2cc644b83a72a1c71ef042617b780173a8dbb49e2c11bc6f
+  data.tar.gz: a60ec27b5db745e3b77d7e9aa2fb75091941a84b4a6b39bf27bfd640361ca082b1861f3828efdfc31fa54090b3f851b68ba8cf5f11def050a4c49b319ce0b42d

data/Gemfile

@@ -16,6 +16,7 @@ gem "test-unit-ruby-core", git: "https://github.com/ruby/test-unit-ruby-core"
 
 gem "benchmark", require: false
 gem "benchmark-driver", require: false
+gem "vernier", require: false, platform: :mri
 
 group :test do
   gem "simplecov",        require: false

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

@@ -28,10 +28,22 @@ module Net
         end
         private_class_method :included
 
-        if defined?(Ractor.make_shareable)
-          def self.safe(...) Ractor.make_shareable 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(...) nil.instance_eval(...).freeze end
+          def self.safe(&b) nil.instance_eval(&b).freeze end
         end
         private_class_method :safe
 
@@ -48,10 +60,11 @@ module Net
         NilOrInteger = safe{->val { Integer val unless val.nil? }}
 
         Enum = ->(*enum) {
-          enum     = safe{enum}
-          expected = -"one of #{enum.map(&:inspect).join(", ")}"
+          sh_enum = Ractor.make_shareable(enum)
+          safe_enum = safe{sh_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/esearch_result.rb

@@ -39,12 +39,49 @@ module Net
       # numbers or UIDs, +to_a+ returns that set as an array of integers.
       #
       # When both #all and #partial are +nil+, either because the server
-      # returned no results or because +ALL+ and +PARTIAL+ were not included in
-      # the IMAP#search +RETURN+ options, #to_a returns an empty array.
+      # returned no results or because neither +ALL+ or +PARTIAL+ were included
+      # in the IMAP#search +RETURN+ options, #to_a returns an empty array.
       #
       # Note that SearchResult also implements +to_a+, so it can be used without
       # checking if the server returned +SEARCH+ or +ESEARCH+ data.
-      def to_a; all&.numbers || partial&.to_a || [] end
+      #
+      # Related: #each, #to_sequence_set, #all, #partial
+      def to_a; to_sequence_set.numbers end
+
+      # :call-seq: to_sequence_set -> SequenceSet or nil
+      #
+      # When either #all or #partial contains a SequenceSet of message sequence
+      # numbers or UIDs, +to_sequence_set+ returns that sequence set.
+      #
+      # When both #all and #partial are +nil+, either because the server
+      # returned no results or because neither +ALL+ or +PARTIAL+ were included
+      # in the IMAP#search +RETURN+ options, #to_sequence_set returns
+      # SequenceSet.empty.
+      #
+      # Note that SearchResult also implements +to_sequence_set+, so it can be
+      # used without checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      #
+      # Related: #each, #to_a, #all, #partial
+      def to_sequence_set
+        all || partial&.to_sequence_set || SequenceSet.empty
+      end
+
+      # When either #all or #partial contains a SequenceSet of message sequence
+      # numbers or UIDs, +each+ yields each integer in the set.
+      #
+      # When both #all and #partial are +nil+, either because the server
+      # returned no results or because +ALL+ and +PARTIAL+ were not included in
+      # the IMAP#search +RETURN+ options, #each does not yield.
+      #
+      # Note that SearchResult also implements +#each+, so it can be used
+      # without checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      #
+      # Related: #to_sequence_set, #to_a, #all, #partial
+      def each(&)
+        return to_enum(__callee__) unless block_given?
+        to_sequence_set.each_number(&)
+        self
+      end
 
       ##
       # attr_reader: tag
@@ -161,6 +198,8 @@ module Net
         #
         # See also: ESearchResult#to_a.
         def to_a; results&.numbers || [] end
+
+        alias to_sequence_set results
       end
 
       # :call-seq: partial -> PartialResult or nil

data/lib/net/imap/flags.rb

@@ -173,7 +173,7 @@ module Net
     SUBSCRIBED = :Subscribed
 
     # The mailbox is a remote mailbox.
-    REMOTE = :Remove
+    REMOTE = :Remote
 
     # Alias for NO_INFERIORS, to match the \IMAP spelling.
     NOINFERIORS   = NO_INFERIORS

data/lib/net/imap/search_result.rb

@@ -60,9 +60,8 @@ module Net
       #     [3, 5, 7] == Net::IMAP::SearchResult[3, 5, 7, modseq: 99] # => true
       #
       def ==(other)
-        (modseq ?
-         other.is_a?(self.class) && modseq == other.modseq :
-         other.is_a?(Array)) &&
+        other.is_a?(Array) &&
+          modseq == (other.modseq if other.respond_to?(:modseq)) &&
           size == other.size &&
           sort == other.sort
       end

data/lib/net/imap/sequence_set.rb

@@ -84,7 +84,7 @@ module Net
     #
     #     # Other inputs are normalized
     #     set = Net::IMAP::SequenceSet([1, 2, [3..7, 5], 6..10, 2048, 1024])
-    #     set.valid_string  #=> "1:10,55,1024:2048"
+    #     set.valid_string  #=> "1:10,1024,2048"
     #     set.frozen?       #=> false
     #
     #     unfrozen = set
@@ -107,7 +107,7 @@ module Net
     #
     #     # Other inputs are normalized
     #     set = Net::IMAP::SequenceSet[1, 2, [3..7, 5], 6..10, 2048, 1024]
-    #     set.valid_string  #=> "1:10,55,1024:2048"
+    #     set.valid_string  #=> "1:10,1024,2048"
     #     set.frozen?       #=> true
     #
     #     frozen   = set
@@ -396,6 +396,23 @@ module Net
       STARS     = [:*, ?*, -1].freeze
       private_constant :STARS
 
+      INSPECT_MAX_LEN      = 512
+      INSPECT_TRUNCATE_LEN =  16
+      private_constant :INSPECT_MAX_LEN, :INSPECT_TRUNCATE_LEN
+
+      # /(,\d+){100}\z/ is shockingly slow on huge strings.
+      # /(,\d{0,10}){100}\z/ is ok, but ironically, Regexp.linear_time? is false.
+      #
+      # This unrolls all nested quantifiers.  It's much harder to read, but it's
+      # also the fastest out of all the versions I tested.
+      nz_uint32   = /[1-9](?:\d(?:\d(?:\d(?:\d(?:\d(?:\d(?:\d(?:\d(?:\d)?)?)?)?)?)?)?)?)?/
+      num_or_star = /#{nz_uint32}|\*/
+      entry       = /#{num_or_star}(?::#{num_or_star})?/
+      entries     = ([entry] * INSPECT_TRUNCATE_LEN).join(",")
+      INSPECT_ABRIDGED_HEAD_RE = /\A#{entries},/
+      INSPECT_ABRIDGED_TAIL_RE = /,#{entries}\z/
+      private_constant :INSPECT_ABRIDGED_HEAD_RE, :INSPECT_ABRIDGED_TAIL_RE
+
       class << self
 
         # :call-seq:
@@ -427,14 +444,14 @@ module Net
         # +to_sequence_set+, calls +obj.to_sequence_set+ and returns the result.
         # Otherwise returns +nil+.
         #
-        # If +obj.to_sequence_set+ doesn't return a SequenceSet, an exception is
-        # raised.
+        # If +obj.to_sequence_set+ doesn't return a SequenceSet or +nil+, an
+        # exception is raised.
         #
         # Related: Net::IMAP::SequenceSet(), ::new, ::[]
         def try_convert(obj)
           return obj if obj.is_a?(SequenceSet)
           return nil unless obj.respond_to?(:to_sequence_set)
-          obj = obj.to_sequence_set
+          return nil unless obj = obj.to_sequence_set
           return obj if obj.is_a?(SequenceSet)
           raise DataFormatError, "invalid object returned from to_sequence_set"
         end
@@ -465,7 +482,7 @@ module Net
       #     set = Net::IMAP::SequenceSet.new("1,2,3:7,5,6:10,2048,1024")
       #     set.valid_string  #=> "1,2,3:7,5,6:10,2048,1024"
       #     set = Net::IMAP::SequenceSet.new(1, 2, 3..7, 5, 6..10, 2048, 1024)
-      #     set.valid_string  #=> "1:10,55,1024:2048"
+      #     set.valid_string  #=> "1:10,1024,2048"
       #
       # With no arguments (or +nil+) creates an empty sequence set.  Note that
       # an empty sequence set is invalid in the \IMAP grammar.
@@ -530,7 +547,10 @@ module Net
       # accepted by ::new.
       def replace(other)
         case other
-        when SequenceSet then initialize_dup(other)
+        when SequenceSet then
+          modifying! # short circuit before doing any work
+          @tuples = other.deep_copy_tuples
+          @string = other.instance_variable_get(:@string)
         when String      then self.string = other
         else                  clear; merge other
         end
@@ -559,29 +579,31 @@ module Net
       # If the set was created from a single string, it is not normalized.  If
       # the set is updated the string will be normalized.
       #
-      # Related: #valid_string, #normalized_string, #to_s
+      # Related: #valid_string, #normalized_string, #to_s, #inspect
       def string; @string ||= normalized_string if valid? end
 
       # Returns an array with #normalized_string when valid and an empty array
       # otherwise.
       def deconstruct; valid? ? [normalized_string] : [] end
 
-      # Assigns a new string to #string and resets #elements to match.  It
-      # cannot be set to an empty string—assign +nil+ or use #clear instead.
-      # The string is validated but not normalized.
+      # Assigns a new string to #string and resets #elements to match.
+      # Assigning +nil+ or an empty string are equivalent to calling #clear.
+      #
+      # Non-empty strings are validated but not normalized.
       #
-      # Use #add or #merge to add a string to an existing set.
+      # Use #add, #merge, or #append to add a string to an existing set.
       #
       # Related: #replace, #clear
-      def string=(str)
-        if str.nil?
+      def string=(input)
+        if input.nil?
           clear
-        else
-          modifying! # redundant check, to normalize the error message for JRuby
-          str = String.try_convert(str) or raise ArgumentError, "not a string"
+        elsif (str = String.try_convert(input))
+          modifying! # short-circuit before parsing the string
           tuples = str_to_tuples str
           @tuples, @string = [], -str
           tuples_add tuples
+        else
+          raise ArgumentError, "expected a string or nil, got #{input.class}"
         end
         str
       end
@@ -590,7 +612,7 @@ module Net
       # string when the set is empty.  Note that an empty set is invalid in the
       # \IMAP syntax.
       #
-      # Related: #valid_string, #normalized_string, #to_s
+      # Related: #string, #valid_string, #normalized_string, #inspect
       def to_s; string || "" end
 
       # Freezes and returns the set.  A frozen SequenceSet is Ractor-safe.
@@ -1623,21 +1645,60 @@ module Net
       #
       # Returns +nil+ when the set is empty.
       #
-      # Related: #normalize!, #normalize
+      # Related: #normalize!, #normalize, #string, #to_s
       def normalized_string
         @tuples.empty? ? nil : -@tuples.map { tuple_to_str _1 }.join(",")
       end
 
+      # Returns an inspection string for the SequenceSet.
+      #
+      #   Net::IMAP::SequenceSet.new.inspect
+      #   #=> "Net::IMAP::SequenceSet()"
+      #
+      #   Net::IMAP::SequenceSet(1..5, 1024, 15, 2000).inspect
+      #   #=> 'Net::IMAP::SequenceSet("1:5,15,1024,2000")'
+      #
+      # Frozen sets have slightly different output:
+      #
+      #   Net::IMAP::SequenceSet.empty.inspect
+      #   #=> "Net::IMAP::SequenceSet.empty"
+      #
+      #   Net::IMAP::SequenceSet[1..5, 1024, 15, 2000].inspect
+      #   #=> 'Net::IMAP::SequenceSet["1:5,15,1024,2000"]'
+      #
+      # Large sets (by number of #entries) have abridged output, with only the
+      # first and last entries:
+      #
+      #   Net::IMAP::SequenceSet(((1..5000) % 2).to_a).inspect
+      #   #=> #<Net::IMAP::SequenceSet 2500 entries "1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31,...(2468 entries omitted)...,4969,4971,4973,4975,4977,4979,4981,4983,4985,4987,4989,4991,4993,4995,4997,4999">
+      #
+      # Related: #to_s, #string
       def inspect
-        if empty?
-          (frozen? ?  "%s.empty" : "#<%s empty>") % [self.class]
-        elsif frozen?
-          "%s[%p]"   % [self.class, to_s]
+        case (count = count_entries)
+        when 0
+          (frozen? ? "%s.empty" : "%s()") % [self.class]
+        when ..INSPECT_MAX_LEN
+          (frozen? ? "%s[%p]" : "%s(%p)") % [self.class, to_s]
         else
-          "#<%s %p>" % [self.class, to_s]
+          if @string
+            head = @string[INSPECT_ABRIDGED_HEAD_RE]
+            tail = @string[INSPECT_ABRIDGED_TAIL_RE]
+          else
+            head = export_string_entries(@tuples.first(INSPECT_TRUNCATE_LEN)) + ","
+            tail = "," + export_string_entries(@tuples.last(INSPECT_TRUNCATE_LEN))
+          end
+          '#<%s %d entries "%s...(%d entries omitted)...%s"%s>' % [
+            self.class, count,
+            head, count - INSPECT_TRUNCATE_LEN * 2, tail,
+            frozen? ? " (frozen)" : "",
+          ]
         end
       end
 
+      private def count_entries
+        @string ? @string.count(",") + 1 : @tuples.count
+      end
+
       ##
       # :method: to_sequence_set
       # :call-seq: to_sequence_set -> self
@@ -1676,6 +1737,8 @@ module Net
 
       attr_reader :tuples # :nodoc:
 
+      def deep_copy_tuples; @tuples.map { _1.dup } end # :nodoc:
+
       private
 
       def remain_frozen(set) frozen? ? set.freeze : set end
@@ -1683,13 +1746,12 @@ module Net
 
       # frozen clones are shallow copied
       def initialize_clone(other)
-        other.frozen? ? super : initialize_dup(other)
+        @tuples = other.deep_copy_tuples unless other.frozen?
+        super
       end
 
       def initialize_dup(other)
-        modifying! # redundant check, to normalize the error message for JRuby
-        @tuples = other.tuples.map(&:dup)
-        @string = other.string&.-@
+        @tuples = other.deep_copy_tuples
         super
       end
 
@@ -1741,6 +1803,10 @@ module Net
       def to_tuple_int(obj) STARS.include?(obj) ? STAR_INT : nz_number(obj) end
       def from_tuple_int(num) num == STAR_INT ? :* : num end
 
+      def export_string_entries(entries)
+        -entries.map { tuple_to_str _1 }.join(",")
+      end
+
       def tuple_to_str(tuple) tuple.uniq.map{ from_tuple_int _1 }.join(":") end
       def str_to_tuples(str) str.split(",", -1).map! { str_to_tuple _1 } end
       def str_to_tuple(str)

data/lib/net/imap/vanished_data.rb

@@ -19,7 +19,7 @@ module Net
       # * +uids+ will be converted by SequenceSet.[].
       # * +earlier+ will be converted to +true+ or +false+
       def initialize(uids:, earlier:)
-        uids    = SequenceSet[uids]
+        uids    = SequenceSet[uids] unless uids.equal? SequenceSet.empty
         earlier = !!earlier
         super
       end
@@ -51,6 +51,15 @@ module Net
       # See SequenceSet#numbers.
       def to_a; uids.numbers end
 
+      # Yields each UID in #uids and returns +self+.  Returns an Enumerator when
+      # no block is given.
+      #
+      # See SequenceSet#each_number.
+      def each(&)
+        return to_enum unless block_given?
+        uids.each_number(&)
+        self
+      end
     end
   end
 end

data/lib/net/imap.rb

@@ -788,7 +788,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.5.9"
+    VERSION = "0.5.11"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -2110,8 +2110,8 @@ module Net
     end
 
     # call-seq:
-    #   uid_expunge{uid_set) -> array of message sequence numbers
-    #   uid_expunge{uid_set) -> VanishedData of UIDs
+    #   uid_expunge(uid_set) -> array of message sequence numbers
+    #   uid_expunge(uid_set) -> VanishedData of UIDs
     #
     # Sends a {UID EXPUNGE command [RFC4315 §2.1]}[https://www.rfc-editor.org/rfc/rfc4315#section-2.1]
     # {[IMAP4rev2 §6.4.9]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.4.9]
@@ -2961,6 +2961,18 @@ module Net
     #   command parameters defined by the extension will implicitly enable it.
     #   See {[RFC7162 §3.1]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1].
     #
+    # [+QRESYNC+ {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html]]
+    #   *NOTE:* Enabling QRESYNC will replace +EXPUNGE+ with +VANISHED+, but
+    #   the extension arguments to #select, #examine, and #uid_fetch are not
+    #   supported yet.
+    #
+    #   Adds quick resynchronization options to #select, #examine, and
+    #   #uid_fetch.  +QRESYNC+ _must_ be explicitly enabled before using any of
+    #   the extension's command parameters.  All +EXPUNGE+ responses will be
+    #   replaced with +VANISHED+ responses.  Enabling +QRESYNC+ implicitly
+    #   enables +CONDSTORE+ as well.
+    #   See {[RFC7162 §3.2]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.2].
+    #
     # [+:utf8+ --- an alias for <tt>"UTF8=ACCEPT"</tt>]
     #
     #   In a future release, <tt>enable(:utf8)</tt> will enable either
@@ -3672,6 +3684,9 @@ module Net
     end
 
     def fetch_internal(cmd, set, attr, mod = nil, partial: nil, changedsince: nil)
+      if partial && !cmd.start_with?("UID ")
+        raise ArgumentError, "partial can only be used with uid_fetch"
+      end
       set = SequenceSet[set]
       if partial
         mod ||= []

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.5.9
+  version: 0.5.11
 platform: ruby
 authors:
 - Shugo Maeda
@@ -129,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol
 test_files: []