net-imap 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf511b8683c6931cf9ec2d3aa4a55ef634a2cc0e670590a4142d9895594b9191
-  data.tar.gz: db4ca0b7230553258e0d81a8a5b5cbed4273e30245200db661145ba430af20d0
+  metadata.gz: d271261a2609a31b8c84ae74913bf57d5046e95318db7660b3230940bdbff447
+  data.tar.gz: 771baa4b8a6c3f83f6ef4f320dda8dc5ea9f2fa2ace15fd9b0c1c1b3a594363a
 SHA512:
-  metadata.gz: b61a04c6992df7d6ffcf0e5396723966c3f3a5a1c6a596caf413c63d355100c8d2c28096a2261045d52ada4d8e995bba1c4f12864bf65fe1355c331df236eb85
-  data.tar.gz: 0bc68ec15c5d53f0f437eab5318bf8cdd428dcdc650a98f66e961658ed361b125e866db2d41954e50ce66de5ec143d108e9135f554bd240ff0d7057724d16416
+  metadata.gz: 230d40d8d183b1c69f63050990df140b49aa5731d0868713e44d2da68c2713ede4fd8d4b1aff60103c25ac6586076e220973b774a43cd5a7b3eaad4e49e7bf3b
+  data.tar.gz: 156e6c86f6fe39a76de89275bfcd3c57b5adcd375de6add45cd00a30bf92bbf04a2b475702db33cae0509fc0b7b3e015518d4991cd5c467f833cacb0f75d3ca6

data/README.md

@@ -50,12 +50,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,80 @@
 /* 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-areas:   "header         controls"
+                         "description description";
+  grid-template-columns: 1fr           min-content;
+  justify-content: space-between;
+}
+
+main .method-header, main .method-controls {
   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;
+}
+
+main .method-header {
+  grid-area: "header";
+  border-right: none;
+  border-radius: 4px 0 0 4px;
+}
+
+main .method-controls {
+  grid-area: "controls";
+  border-left: none;
+  border-radius: 0 4px 4px 0;
 }
 
 main .method-description, main .aliases {
+  grid-area: "description";
+  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/command_data.rb

@@ -3,6 +3,7 @@
 require "date"
 
 require_relative "errors"
+require_relative "data_lite"
 
 module Net
   class IMAP < Protocol
@@ -119,80 +120,53 @@ module Net
       put_string("\\" + symbol.to_s)
     end
 
-    class RawData # :nodoc:
+    CommandData = Data.define(:data) do # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, @data)
+        raise NoMethodError, "#{self.class} must implement #{__method__}"
       end
 
       def validate
       end
-
-      private
-
-      def initialize(data)
-        @data = data
-      end
     end
 
-    class Atom # :nodoc:
+    class RawData < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:put_string, @data)
-      end
-
-      def validate
-      end
-
-      private
-
-      def initialize(data)
-        @data = data
+        imap.__send__(:put_string, data)
       end
     end
 
-    class QuotedString # :nodoc:
+    class Atom < 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__(:put_string, data)
       end
     end
 
-    class Literal # :nodoc:
+    class QuotedString < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:send_literal, @data, tag)
-      end
-
-      def validate
+        imap.__send__(:send_quoted_string, data)
       end
+    end
 
-      private
-
-      def initialize(data)
-        @data = data
+    class Literal < CommandData # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:send_literal, data, tag)
       end
     end
 
     # *DEPRECATED*.  Replaced by SequenceSet.
-    class MessageSet # :nodoc:
+    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
@@ -246,22 +220,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/data_lite.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+# Some of the code in this file was copied from the polyfill-data gem.
+#
+# MIT License
+#
+# Copyright (c) 2023 Jim Gay, Joel Drapper, Nicholas Evans
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+
+module Net
+  class IMAP
+    data_or_object = RUBY_VERSION >= "3.2.0" ? ::Data : Object
+    class DataLite < data_or_object
+      def encode_with(coder) coder.map = attributes.transform_keys(&:to_s) end
+      def init_with(coder) initialize(**coder.map.transform_keys(&:to_sym)) end
+    end
+
+    Data = DataLite
+  end
+end
+
+# :nocov:
+# Need to skip test coverage for the rest, because it isn't loaded by ruby 3.2+.
+return if RUBY_VERSION >= "3.2.0"
+
+module Net
+  class IMAP
+    # DataLite is a temporary substitute for ruby 3.2's +Data+ class.  DataLite
+    # is aliased as Net::IMAP::Data, so that code using it won't need to be
+    # updated when it is removed.
+    #
+    # See {ruby 3.2's documentation for Data}[https://docs.ruby-lang.org/en/3.2/Data.html].
+    #
+    # [When running ruby 3.1]
+    #    This class reimplements the API for ruby 3.2's +Data+, and should be
+    #    compatible for nearly all use-cases.  This reimplementation <em>will be
+    #    removed</em> in +net-imap+ 0.6, when support for ruby 3.1 is dropped.
+    #
+    #    _NOTE:_ +net-imap+ no longer supports ruby versions prior to 3.1.
+    # [When running ruby >= 3.2]
+    #    This class inherits from +Data+ and _only_ defines the methods needed
+    #    for YAML serialization.  This will be dropped when +psych+ adds support
+    #    for +Data+.
+    #
+    # Some of the code in this class was copied or adapted from the
+    # {polyfill-data gem}[https://rubygems.org/gems/polyfill-data], by Jim Gay
+    # and Joel Drapper, under the MIT license terms.
+    class DataLite
+      singleton_class.undef_method :new
+
+      TYPE_ERROR    = "%p is not a symbol nor a string"
+      ATTRSET_ERROR = "invalid data member: %p"
+      DUP_ERROR     = "duplicate member: %p"
+      ARITY_ERROR   = "wrong number of arguments (given %d, expected %s)"
+      private_constant :TYPE_ERROR, :ATTRSET_ERROR, :DUP_ERROR, :ARITY_ERROR
+
+      # Defines a new Data class.
+      #
+      # _NOTE:_ Unlike ruby 3.2's +Data.define+, DataLite.define only supports
+      # member names which are valid local variable names.  Member names can't
+      # be keywords (e.g: +next+ or +class+) or start with capital letters, "@",
+      # etc.
+      def self.define(*args, &block)
+        members = args.each_with_object({}) do |arg, members|
+          arg = arg.to_str unless arg in Symbol | String if arg.respond_to?(:to_str)
+          arg = arg.to_sym if     arg in String
+          arg in Symbol     or  raise TypeError,     TYPE_ERROR    % [arg]
+          arg in %r{=}      and raise ArgumentError, ATTRSET_ERROR % [arg]
+          members.key?(arg) and raise ArgumentError, DUP_ERROR     % [arg]
+          members[arg] = true
+        end
+        members = members.keys.freeze
+
+        klass = ::Class.new(self)
+
+        klass.singleton_class.undef_method :define
+        klass.define_singleton_method(:members) { members }
+
+        def klass.new(*args, **kwargs, &block)
+          if kwargs.size.positive?
+            if args.size.positive?
+              raise ArgumentError, ARITY_ERROR % [args.size, 0]
+            end
+          elsif members.size < args.size
+            expected = members.size.zero? ? 0 : 0..members.size
+            raise ArgumentError, ARITY_ERROR % [args.size, expected]
+          else
+            kwargs = Hash[members.take(args.size).zip(args)]
+          end
+          allocate.tap do |instance|
+            instance.__send__(:initialize, **kwargs, &block)
+          end.freeze
+        end
+
+        klass.singleton_class.alias_method :[], :new
+        klass.attr_reader(*members)
+
+        # Dynamically defined initializer methods are in an included module,
+        # rather than directly on DataLite (like in ruby 3.2+):
+        # * simpler to handle required kwarg ArgumentErrors
+        # * easier to ensure consistent ivar assignment order (object shape)
+        # * faster than instance_variable_set
+        klass.include(Module.new do
+          if members.any?
+            kwargs = members.map{"#{_1.name}:"}.join(", ")
+            params = members.map(&:name).join(", ")
+            ivars  = members.map{"@#{_1.name}"}.join(", ")
+            attrs  = members.map{"attrs[:#{_1.name}]"}.join(", ")
+            module_eval <<~RUBY, __FILE__, __LINE__ + 1
+              protected
+              def initialize(#{kwargs}) #{ivars} = #{params}; freeze end
+              def marshal_load(attrs)   #{ivars} = #{attrs};  freeze end
+            RUBY
+          end
+        end)
+
+        klass.module_eval do _1.module_eval(&block) end if block_given?
+
+        klass
+      end
+
+      ##
+      # singleton-method: new
+      # call-seq:
+      #   new(*args) -> instance
+      #   new(**kwargs) -> instance
+      #
+      # Constuctor for classes defined with ::define.
+      #
+      # Aliased as ::[].
+
+      ##
+      # singleton-method: []
+      # call-seq:
+      #   ::[](*args) -> instance
+      #   ::[](**kwargs) -> instance
+      #
+      # Constuctor for classes defined with ::define.
+      #
+      # Alias for ::new
+
+      ##
+      def members;     self.class.members                              end
+      def attributes;  Hash[members.map {|m| [m, send(m)] }]           end
+      def to_h(&block) attributes.to_h(&block)                         end
+      def hash;        [self.class, attributes].hash                   end
+      def ==(other)    self.class == other.class && to_h == other.to_h end
+      def eql?(other)  self.class == other.class && hash == other.hash end
+      def deconstruct; attributes.values                               end
+
+      def deconstruct_keys(keys)
+        raise TypeError unless keys.is_a?(Array) || keys.nil?
+        return attributes if keys&.first.nil?
+        attributes.slice(*keys)
+      end
+
+      def with(**kwargs)
+        return self if kwargs.empty?
+        self.class.new(**attributes.merge(kwargs))
+      end
+
+      def inspect
+        __inspect_guard__(self) do |seen|
+          return "#<data #{self.class}:...>" if seen
+          attrs = attributes.map {|kv| "%s=%p" % kv }.join(", ")
+          display = ["data", self.class.name, attrs].compact.join(" ")
+          "#<#{display}>"
+        end
+      end
+      alias_method :to_s, :inspect
+
+      private
+
+      def initialize_copy(source) super.freeze end
+      def marshal_dump; attributes end
+
+      # Yields +true+ if +obj+ has been seen already, +false+ if it hasn't.
+      # Marks +obj+ as seen inside the block, so circuler references don't
+      # recursively trigger a SystemStackError (stack level too deep).
+      #
+      # Making circular references inside a Data object _should_ be very
+      # uncommon, but we'll support them for the sake of completeness.
+      def __inspect_guard__(obj)
+        preexisting = Thread.current[:__net_imap_data__inspect__]
+        Thread.current[:__net_imap_data__inspect__] ||= {}.compare_by_identity
+        inspect_guard = Thread.current[:__net_imap_data__inspect__]
+        if inspect_guard.include?(obj)
+          yield true
+        else
+          begin
+            inspect_guard[obj] = true
+            yield false
+          ensure
+            inspect_guard.delete(obj)
+          end
+        end
+      ensure
+        unless preexisting.equal?(inspect_guard)
+          Thread.current[:__net_imap_data__inspect__] = preexisting
+        end
+      end
+
+    end
+
+  end
+end
+# :nocov:

data/lib/net/imap/esearch_result.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    # An "extended search" response (+ESEARCH+).  ESearchResult should be
+    # returned (instead of SearchResult) by IMAP#search, IMAP#uid_search,
+    # IMAP#sort, and IMAP#uid_sort under any of the following conditions:
+    #
+    # * Return options were specified for IMAP#search or IMAP#uid_search.
+    #   The server must support a search extension which allows
+    #   RFC4466[https://www.rfc-editor.org/rfc/rfc4466.html] +return+ options,
+    #   such as +ESEARCH+, +PARTIAL+, or +IMAP4rev2+.
+    # * Return options were specified for IMAP#sort or IMAP#uid_sort.
+    #   The server must support the +ESORT+ extension
+    #   {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html#section-3].
+    #
+    #   *NOTE:* IMAP#search and IMAP#uid_search do not support +ESORT+ yet.
+    # * The server supports +IMAP4rev2+ but _not_ +IMAP4rev1+, or +IMAP4rev2+
+    #   has been enabled.  +IMAP4rev2+ requires +ESEARCH+ results.
+    #
+    # Note that some servers may claim to support a search extension which
+    # requires an +ESEARCH+ result, such as +PARTIAL+, but still only return a
+    # +SEARCH+ result when +return+ options are specified.
+    #
+    # Some search extensions may result in the server sending ESearchResult
+    # responses after the initiating command has completed.  Use
+    # IMAP#add_response_handler to handle these responses.
+    class ESearchResult < Data.define(:tag, :uid, :data)
+      def initialize(tag: nil, uid: nil, data: nil)
+        tag  => String       | nil; tag = -tag if tag
+        uid  => true | false | nil; uid = !!uid
+        data => Array        | nil; data ||= []; data.freeze
+        super
+      end
+
+      # :call-seq: to_a -> Array of integers
+      #
+      # When #all contains a SequenceSet of message sequence
+      # numbers or UIDs, +to_a+ returns that set as an array of integers.
+      #
+      # When #all is +nil+, either because the server
+      # returned no results or because +ALL+ was not 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 || [] end
+
+      ##
+      # attr_reader: tag
+      #
+      # The tag string for the command that caused this response to be returned.
+      #
+      # When +nil+, this response was not caused by a particular command.
+
+      ##
+      # attr_reader: uid
+      #
+      # Indicates whether #data in this response refers to UIDs (when +true+) or
+      # to message sequence numbers (when +false+).
+
+      ##
+      alias uid? uid
+
+      ##
+      # attr_reader: data
+      #
+      # Search return data, as an array of <tt>[name, value]</tt> pairs.  Most
+      # return data corresponds to a search +return+ option with the same name.
+      #
+      # Note that some return data names may be used more than once per result.
+      #
+      # This data can be more simply retrieved by #min, #max, #all, #count,
+      # #modseq, and other methods.
+
+      # :call-seq: min -> integer or nil
+      #
+      # The lowest message number/UID that satisfies the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MIN+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def min;        data.assoc("MIN")&.last        end
+
+      # :call-seq: max -> integer or nil
+      #
+      # The highest message number/UID that satisfies the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MAX+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def max;        data.assoc("MAX")&.last        end
+
+      # :call-seq: all -> sequence set or nil
+      #
+      # A SequenceSet containing all message sequence numbers or UIDs that
+      # satisfy the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +ALL+ return option was not specified but other return options were.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      #
+      # See also: #to_a
+      def all;        data.assoc("ALL")&.last        end
+
+      # :call-seq: count -> integer or nil
+      #
+      # Returns the number of messages that satisfy the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +COUNT+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def count;      data.assoc("COUNT")&.last      end
+
+      # :call-seq: modseq -> integer or nil
+      #
+      # The highest +mod-sequence+ of all messages being returned.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MODSEQ+ search criterion wasn't specified.
+      #
+      # Note that there is no search +return+ option for +MODSEQ+.  It will be
+      # returned whenever the +CONDSTORE+ extension has been enabled.  Using the
+      # +MODSEQ+ search criteria will implicitly enable +CONDSTORE+.
+      #
+      # Requires +CONDSTORE+ {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html]
+      # and +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.2].
+      def modseq;     data.assoc("MODSEQ")&.last     end
+
+    end
+  end
+end

data/lib/net/imap/response_data.rb

@@ -2,6 +2,7 @@
 
 module Net
   class IMAP < Protocol
+    autoload :ESearchResult,    "#{__dir__}/esearch_result"
     autoload :FetchData,        "#{__dir__}/fetch_data"
     autoload :SearchResult,     "#{__dir__}/search_result"
     autoload :SequenceSet,      "#{__dir__}/sequence_set"

data/lib/net/imap/response_parser/parser_utils.rb

@@ -185,6 +185,11 @@ module Net
           @str[@pos, str.length] == str
         end
 
+        def peek_re?(re)
+          assert_no_lookahead if Net::IMAP.debug
+          re.match?(@str, @pos)
+        end
+
         def peek_re(re)
           assert_no_lookahead if config.debug?
           re.match(@str, @pos)