net-imap 0.4.12 → 0.5.5

data/lib/net/imap/search_result.rb

@@ -100,10 +100,10 @@ module Net
       #    data.to_s("SORT")   # => "* SORT 2 8 32 128 256 512"
       #    data.to_s(nil)      # => "2 8 32 128 256 512"
       #
-      #    data = Net::IMAP::SearchResult[1, 3, 16, 1024, modseq: 2048].to_s
+      #    data = Net::IMAP::SearchResult[1, 3, 16, 1024, modseq: 2048]
       #    data.to_s           # => "* SEARCH 1 3 16 1024 (MODSEQ 2048)"
       #    data.to_s("SORT")   # => "* SORT 1 3 16 1024 (MODSEQ 2048)"
-      #    data.to_s           # => "1 3 16 1024 (MODSEQ 2048)"
+      #    data.to_s(nil)      # => "1 3 16 1024 (MODSEQ 2048)"
       #
       def to_s(type = "SEARCH")
         str = +""

data/lib/net/imap/sequence_set.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set" unless defined?(::Set)
+
 module Net
   class IMAP
 
@@ -14,13 +16,6 @@ module Net
     # receive a SequenceSet as an argument, for example IMAP#search, IMAP#fetch,
     # and IMAP#store.
     #
-    # == EXPERIMENTAL API
-    #
-    # SequenceSet is currently experimental.  Only two methods, ::[] and
-    # #valid_string, are considered stable.  Although the API isn't expected to
-    # change much, any other methods may be removed or changed without
-    # deprecation.
-    #
     # == Creating sequence sets
     #
     # SequenceSet.new with no arguments creates an empty sequence set.  Note
@@ -37,7 +32,8 @@ module Net
     #
     # SequenceSet.new may receive a single optional argument: a non-zero 32 bit
     # unsigned integer, a range, a <tt>sequence-set</tt> formatted string,
-    # another sequence set, or an enumerable containing any of these.
+    # another sequence set, a Set (containing only numbers or <tt>*</tt>), or an
+    # Array containing any of these (array inputs may be nested).
     #
     #     set = Net::IMAP::SequenceSet.new(1)
     #     set.valid_string  #=> "1"
@@ -286,11 +282,7 @@ module Net
 
       # valid inputs for "*"
       STARS     = [:*, ?*, -1].freeze
-      private_constant :STAR_INT, :STARS
-
-      COERCIBLE = ->{ _1.respond_to? :to_sequence_set }
-      ENUMABLE  = ->{ _1.respond_to?(:each) && _1.respond_to?(:empty?) }
-      private_constant :COERCIBLE, :ENUMABLE
+      private_constant :STARS
 
       class << self
 
@@ -304,7 +296,7 @@ module Net
         # Use ::new to create a mutable or empty SequenceSet.
         def [](first, *rest)
           if rest.empty?
-            if first.is_a?(SequenceSet) && set.frozen? && set.valid?
+            if first.is_a?(SequenceSet) && first.frozen? && first.valid?
               first
             else
               new(first).validate.freeze
@@ -325,7 +317,7 @@ module Net
         # raised.
         def try_convert(obj)
           return obj if obj.is_a?(SequenceSet)
-          return nil unless respond_to?(:to_sequence_set)
+          return nil unless obj.respond_to?(:to_sequence_set)
           obj = obj.to_sequence_set
           return obj if obj.is_a?(SequenceSet)
           raise DataFormatError, "invalid object returned from to_sequence_set"
@@ -389,6 +381,10 @@ module Net
       # Related: #valid_string, #normalized_string, #to_s
       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.
@@ -682,6 +678,7 @@ module Net
       # Unlike #add, #merge, or #union, the new value is appended to #string.
       # This may result in a #string which has duplicates or is out-of-order.
       def append(object)
+        modifying!
         tuple = input_to_tuple object
         entry = tuple_to_str tuple
         tuple_add tuple
@@ -1271,7 +1268,8 @@ module Net
         when *STARS, Integer, Range then [input_to_tuple(obj)]
         when String      then str_to_tuples obj
         when SequenceSet then obj.tuples
-        when ENUMABLE    then obj.flat_map { input_to_tuples _1 }
+        when Set         then obj.map      { [to_tuple_int(_1)] * 2 }
+        when Array       then obj.flat_map { input_to_tuples _1 }
         when nil         then []
         else
           raise DataFormatError,
@@ -1284,8 +1282,7 @@ module Net
       # String, Set, Array, or... any type of object.
       def input_try_convert(input)
         SequenceSet.try_convert(input) ||
-          # Integer.try_convert(input) || # ruby 3.1+
-          input.respond_to?(:to_int) && Integer(input.to_int) ||
+          Integer.try_convert(input) ||
           String.try_convert(input) ||
           input
       end
@@ -1317,6 +1314,12 @@ module Net
           range.include?(min) || range.include?(max) || (min..max).cover?(range)
       end
 
+      def modifying!
+        if frozen?
+          raise FrozenError, "can't modify frozen #{self.class}: %p" % [self]
+        end
+      end
+
       def tuples_add(tuples)      tuples.each do tuple_add _1      end; self end
       def tuples_subtract(tuples) tuples.each do tuple_subtract _1 end; self end
 
@@ -1331,6 +1334,7 @@ module Net
       #   ---------??===lower==|--|==|----|===upper===|-- join until upper
       #   ---------??===lower==|--|==|--|=====upper===|-- join to upper
       def tuple_add(tuple)
+        modifying!
         min, max = tuple
         lower, lower_idx = tuple_gte_with_index(min - 1)
         if    lower.nil?              then tuples << tuple
@@ -1367,6 +1371,7 @@ module Net
       # -------??=====lower====|--|====|---|====upper====|-- 7. delete until
       # -------??=====lower====|--|====|--|=====upper====|-- 8. delete and trim
       def tuple_subtract(tuple)
+        modifying!
         min, max = tuple
         lower, idx = tuple_gte_with_index(min)
         if    lower.nil?        then nil # case 1.
@@ -1407,12 +1412,11 @@ module Net
       end
 
       def nz_number(num)
-        case num
-        when Integer, /\A[1-9]\d*\z/ then num = Integer(num)
-        else raise DataFormatError, "%p is not a valid nz-number" % [num]
-        end
-        NumValidator.ensure_nz_number(num)
-        num
+        String === num && !/\A[1-9]\d*\z/.match?(num) and
+          raise DataFormatError, "%p is not a valid nz-number" % [num]
+        NumValidator.ensure_nz_number Integer num
+      rescue TypeError # To catch errors from Integer()
+        raise DataFormatError, $!.message
       end
 
       # intentionally defined after the class implementation

data/lib/net/imap/stringprep/nameprep.rb

@@ -4,7 +4,7 @@ module Net
   class IMAP
     module StringPrep
 
-      # Defined in RFC3491[https://tools.ietf.org/html/rfc3491], the +nameprep+
+      # Defined in RFC3491[https://www.rfc-editor.org/rfc/rfc3491], the +nameprep+
       # profile of "Stringprep" is:
       # >>>
       #   used by the IDNA protocol for preparing domain names; it is not

data/lib/net/imap/stringprep/trace.rb

@@ -4,11 +4,11 @@ module Net
   class IMAP
     module StringPrep
 
-      # Defined in RFC-4505[https://tools.ietf.org/html/rfc4505] §3, The +trace+
+      # Defined in RFC-4505[https://www.rfc-editor.org/rfc/rfc4505] §3, The +trace+
       # profile of \StringPrep is used by the +ANONYMOUS+ \SASL mechanism.
       module Trace
 
-        # Defined in RFC-4505[https://tools.ietf.org/html/rfc4505] §3.
+        # Defined in RFC-4505[https://www.rfc-editor.org/rfc/rfc4505] §3.
         STRINGPREP_PROFILE = "trace"
 
         # >>>
@@ -23,7 +23,7 @@ module Net
         #   No Unicode normalization is required by this profile.
         NORMALIZATION = nil
 
-        # From RFC-4505[https://tools.ietf.org/html/rfc4505] §3, The "trace"
+        # From RFC-4505[https://www.rfc-editor.org/rfc/rfc4505] §3, The "trace"
         # Profile of "Stringprep":
         # >>>
         #   Characters from the following tables of [StringPrep] are prohibited:
@@ -47,7 +47,7 @@ module Net
 
         module_function
 
-        # From RFC-4505[https://tools.ietf.org/html/rfc4505] §3, The "trace"
+        # From RFC-4505[https://www.rfc-editor.org/rfc/rfc4505] §3, The "trace"
         # Profile of "Stringprep":
         # >>>
         #   The character repertoire of this profile is Unicode 3.2 [Unicode].

data/lib/net/imap/vanished_data.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP < Protocol
+
+    # Net::IMAP::VanishedData represents the contents of a +VANISHED+ response,
+    # which is described by the
+    # {QRESYNC}[https://www.rfc-editor.org/rfc/rfc7162.html] extension.
+    # [{RFC7162 §3.2.10}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.2.10]].
+    #
+    # +VANISHED+ responses replace +EXPUNGE+ responses when either the
+    # {QRESYNC}[https://www.rfc-editor.org/rfc/rfc7162.html] or the
+    # {UIDONLY}[https://www.rfc-editor.org/rfc/rfc9586.html] extension has been
+    # enabled.
+    class VanishedData < Data.define(:uids, :earlier)
+
+      # Returns a new VanishedData object.
+      #
+      # * +uids+ will be converted by SequenceSet.[].
+      # * +earlier+ will be converted to +true+ or +false+
+      def initialize(uids:, earlier:)
+        uids    = SequenceSet[uids]
+        earlier = !!earlier
+        super
+      end
+
+      ##
+      # :attr_reader: uids
+      #
+      # SequenceSet of UIDs that have been permanently removed from the mailbox.
+
+      ##
+      # :attr_reader: earlier
+      #
+      # +true+ when the response was caused by Net::IMAP#uid_fetch with
+      # <tt>vanished: true</tt> or Net::IMAP#select/Net::IMAP#examine with
+      # <tt>qresync: true</tt>.
+      #
+      # +false+ when the response is used to announce message removals within an
+      # already selected mailbox.
+
+      # rdoc doesn't handle attr aliases nicely. :(
+      alias earlier? earlier # :nodoc:
+      ##
+      # :attr_reader: earlier?
+      #
+      # Alias for #earlier.
+
+      # Returns an Array of all of the UIDs in #uids.
+      #
+      # See SequenceSet#numbers.
+      def to_a; uids.numbers end
+
+    end
+  end
+end