net-imap 0.4.12 → 0.5.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5147af8d1017e772136634ea2144c33a1666a00a25d03de20a6d89f9b026ecc
-  data.tar.gz: 66a41c1fcfc932da451f65074ae6659d872b85aeeef831208cf47178f944cd08
+  metadata.gz: cdbdda0ed73da899ec338f66022a16104562d3701c568b0a6d4897270a608ac5
+  data.tar.gz: b6a7ec70776b32f8eb57d01a0869503eb5d76f719ac091eb92e0206608e936e9
 SHA512:
-  metadata.gz: 67a5545d46acd17051097ad3e10304817980fad7621ca0225c614f8bd49d62365d9b9d3305fa1ac3fbebd63bd1ba2155cb5a94d448ca6a6763655dd31cdb22a2
-  data.tar.gz: dbc107f94925486cbc3eb28a26c45560fce568f3836d65127628599fd7a117046d5cc0225f1999b387802316b781bce367da5b660da79200c7e576515669ca70
+  metadata.gz: 381bf2428719ed8decb5d241fda0e19f28031dd4a77980b3717bb29c37bed1c927f00e5b57862e209ecf24b2e9b38c01088d6e1a90fc4b4cc026cdd9e6611100
+  data.tar.gz: 513c6a77d46b6d2cf67aea4511023acc76c69940e3b1a0d0eae7223b53ff63bc8e6e009f51fef826b09f76f6ad1d92e84243e8457f59d3912db7e74bf69d3d1b

data/Gemfile

@@ -8,9 +8,16 @@ gem "digest"
 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-driver", require: false
+
+group :test do
+  gem "simplecov",        require: false
+  gem "simplecov-html",   require: false
+  gem "simplecov-json",   require: false
+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,7 @@
 require "date"
 
 require_relative "errors"
+require_relative "data_lite"
 
 module Net
   class IMAP < Protocol
@@ -40,10 +41,10 @@ module Net
         send_number_data(data)
       when Array
         send_list_data(data, tag)
-      when Date
-        send_date_data(data)
       when Time, DateTime
         send_time_data(data)
+      when Date
+        send_date_data(data)
       when Symbol
         send_symbol_data(data)
       else
@@ -119,79 +120,95 @@ 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)
+        imap.__send__(:put_string, data)
       end
+    end
 
-      def validate
-      end
-
-      private
-
-      def initialize(data)
-        @data = data
+    class QuotedString < CommandData # :nodoc:
+      def send_data(imap, tag)
+        imap.__send__(:send_quoted_string, data)
       end
     end
 
-    class Literal # :nodoc:
+    class Literal < CommandData # :nodoc:
       def send_data(imap, tag)
-        imap.__send__(:send_literal, @data, tag)
+        imap.__send__(:send_literal, data, tag)
       end
+    end
 
-      def validate
+    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
 
-      private
+      def formatted = "%d:%d" % data.minmax
 
-      def initialize(data)
-        @data = data
+      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)
@@ -235,22 +252,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_accessors.rb

@@ -0,0 +1,75 @@
+# 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.
+      #
+      # +attr_accessor+ values are stored in a struct rather than ivars, making
+      # it simpler to ensure that all config objects share a single object
+      # shape.  This also simplifies iteration over all defined attributes.
+      module AttrAccessors
+        module Macros # :nodoc: internal API
+          def attr_accessor(name) AttrAccessors.attr_accessor(name) end
+        end
+        private_constant :Macros
+
+        def self.included(mod)
+          mod.extend Macros
+        end
+        private_class_method :included
+
+        extend Forwardable
+
+        def self.attr_accessor(name) # :nodoc: internal API
+          name = name.to_sym
+          def_delegators :data, name, :"#{name}="
+        end
+
+        def self.attributes
+          instance_methods.grep(/=\z/).map { _1.to_s.delete_suffix("=").to_sym }
+        end
+        private_class_method :attributes
+
+        def self.struct # :nodoc: internal API
+          unless defined?(self::Struct)
+            const_set :Struct, Struct.new(*attributes)
+          end
+          self::Struct
+        end
+
+        def initialize # :notnew:
+          super()
+          @data = AttrAccessors.struct.new
+        end
+
+        # Freezes the internal attributes struct, in addition to +self+.
+        def freeze
+          data.freeze
+          super
+        end
+
+        protected
+
+        attr_reader :data # :nodoc: internal API
+
+        private
+
+        def initialize_clone(other)
+          super
+          @data = other.data.clone
+        end
+
+        def initialize_dup(other)
+          super
+          @data = other.data.dup
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    class Config
+      # >>>
+      #   *NOTE:* The public methods on this module are part of the stable
+      #   public API of Net::IMAP::Config.  But the module itself is an internal
+      #   implementation detail, with no guarantee of backward compatibility.
+      #
+      # +attr_accessor+ methods will delegate to their #parent when the local
+      # value does not contain an override.  Inheritance forms a singly linked
+      # list, so lookup will be <tt>O(n)</tt> on the number of ancestors.  In
+      # practice, the ancestor chain is not expected to be long.  Without
+      # customization, it is only three deep:
+      # >>>
+      #     IMAP#config → Config.global → Config.default
+      #
+      # When creating a client with the +config+ keyword, for example to use
+      # the appropriate defaults for an application or a library while still
+      # relying on global for configuration of +debug+ or +logger+, most likely
+      # the ancestor chain is still only four deep:
+      # >>>
+      #     IMAP#config → alternate defaults → Config.global → Config.default
+      module AttrInheritance
+        INHERITED = Module.new.freeze
+        private_constant :INHERITED
+
+        module Macros # :nodoc: internal API
+          def attr_accessor(name) super; AttrInheritance.attr_accessor(name) end
+        end
+        private_constant :Macros
+
+        def self.included(mod)
+          mod.extend Macros
+        end
+        private_class_method :included
+
+        def self.attr_accessor(name) # :nodoc: internal API
+          module_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{name}; (val = super) == INHERITED ? parent&.#{name} : val end
+          RUBY
+        end
+
+        # The parent Config object
+        attr_reader :parent
+
+        def initialize(parent = nil) # :notnew:
+          super()
+          @parent = Config[parent]
+          reset
+        end
+
+        # Creates a new config, which inherits from +self+.
+        def new(**attrs) self.class.new(self, **attrs) end
+
+        # Returns +true+ if +attr+ is inherited from #parent and not overridden
+        # by this config.
+        def inherited?(attr) data[attr] == INHERITED end
+
+        # :call-seq:
+        #   reset -> self
+        #   reset(attr) -> attribute value
+        #
+        # Resets an +attr+ to inherit from the #parent config.
+        #
+        # When +attr+ is nil or not given, all attributes are reset.
+        def reset(attr = nil)
+          if attr.nil?
+            data.members.each do |attr| data[attr] = INHERITED end
+            self
+          elsif inherited?(attr)
+            nil
+          else
+            old, data[attr] = data[attr], INHERITED
+            old
+          end
+        end
+
+        private
+
+        def initialize_copy(other)
+          super
+          @parent ||= other # only default has nil parent
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    class Config
+      # >>>
+      #   *NOTE:* This module is an internal implementation detail, with no
+      #   guarantee of backward compatibility.
+      #
+      # Adds a +type+ keyword parameter to +attr_accessor+, to enforce that
+      # config attributes have valid types, for example: boolean, numeric,
+      # enumeration, non-nullable, etc.
+      module AttrTypeCoercion
+        # :stopdoc: internal APIs only
+
+        module Macros # :nodoc: internal API
+          def attr_accessor(attr, type: nil)
+            super(attr)
+            AttrTypeCoercion.attr_accessor(attr, type: type)
+          end
+        end
+        private_constant :Macros
+
+        def self.included(mod)
+          mod.extend Macros
+        end
+        private_class_method :included
+
+        def self.attr_accessor(attr, type: nil)
+          return unless type
+          if    :boolean == type then boolean attr
+          elsif Integer  == type then integer attr
+          elsif Array   === type then enum    attr, type
+          else raise ArgumentError, "unknown type coercion %p" % [type]
+          end
+        end
+
+        def self.boolean(attr)
+          define_method :"#{attr}=" do |val| super !!val end
+          define_method :"#{attr}?" do send attr end
+        end
+
+        def self.integer(attr)
+          define_method :"#{attr}=" do |val| super Integer val end
+        end
+
+        def self.enum(attr, enum)
+          enum = enum.dup.freeze
+          expected = -"one of #{enum.map(&:inspect).join(", ")}"
+          define_method :"#{attr}=" do |val|
+            unless enum.include?(val)
+              raise ArgumentError, "expected %s, got %p" % [expected, val]
+            end
+            super val
+          end
+        end
+
+      end
+    end
+  end
+end