net-imap 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c89d97e842bce303df112c3fbc0f048f20a2ff1dbf3b85bb2314ea0d2e207c5
-  data.tar.gz: 11d6ec196e1e768f61a17b0ce7f385a11eb03e3e92af8ab327ba9a90699ee940
+  metadata.gz: cf511b8683c6931cf9ec2d3aa4a55ef634a2cc0e670590a4142d9895594b9191
+  data.tar.gz: db4ca0b7230553258e0d81a8a5b5cbed4273e30245200db661145ba430af20d0
 SHA512:
-  metadata.gz: ca70e20c3c70f4ca57822f70936546adb3129dd7c0771ef2d054b0356ed4f6a994b7453803cc06bd25ebb37dc0ed10f60b5541bc56749dee38a6126264344599
-  data.tar.gz: 2921a79dbdab7bd0476d883c18db50150388d587c711270faac99ad4505574a23e6532fe61a4fb48f51c8bddea6641d96f81d9dcbe245b4d4f4542fcc7418566
+  metadata.gz: b61a04c6992df7d6ffcf0e5396723966c3f3a5a1c6a596caf413c63d355100c8d2c28096a2261045d52ada4d8e995bba1c4f12864bf65fe1355c331df236eb85
+  data.tar.gz: 0bc68ec15c5d53f0f437eab5318bf8cdd428dcdc650a98f66e961658ed361b125e866db2d41954e50ce66de5ec143d108e9135f554bd240ff0d7057724d16416

data/lib/net/imap/sequence_set.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set" unless defined?(::Set)
+
 module Net
   class IMAP
 
@@ -280,10 +282,7 @@ module Net
 
       # valid inputs for "*"
       STARS     = [:*, ?*, -1].freeze
-      private_constant :STAR_INT, :STARS
-
-      COERCIBLE = ->{ _1.respond_to? :to_sequence_set }
-      private_constant :COERCIBLE
+      private_constant :STARS
 
       class << self
 
@@ -318,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"
@@ -382,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.

data/lib/net/imap.rb

@@ -719,7 +719,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.0"
+    VERSION = "0.5.1"
 
     # Aliases for supported capabilities, to be used with the #enable command.
     ENABLE_ALIASES = {
@@ -1929,77 +1929,269 @@ module Net
       end
     end
 
-    # Sends a {SEARCH command [IMAP4rev1 §6.4.4]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.4]
-    # to search the mailbox for messages that match the given searching
-    # criteria, and returns message sequence numbers.  +keys+ can either be a
-    # string holding the entire search string, or a single-dimension array of
-    # search keywords and arguments.
+    # :call-seq:
+    #   search(criteria, charset = nil) -> result
     #
-    # Returns a SearchResult object.  SearchResult inherits from Array (for
+    # Sends a {SEARCH command [IMAP4rev1 §6.4.4]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.4]
+    # to search the mailbox for messages that match the given search +criteria+,
+    # and returns a SearchResult.  SearchResult inherits from Array (for
     # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
     # capability has been enabled.
     #
+    # +criteria+ is one or more search keys and their arguments, which may be
+    # provided as an array or a string.
+    # See {"Search criteria"}[rdoc-ref:#search@Search+criteria], below.
+    #
+    # * When +criteria+ is an array, each member is a +SEARCH+ command argument:
+    #   * Any SequenceSet sends SequenceSet#valid_string.
+    #     These types are converted to SequenceSet for validation and encoding:
+    #     * +Set+
+    #     * +Range+
+    #     * <tt>-1</tt> and +:*+ -- both translate to <tt>*</tt>
+    #     * responds to +#to_sequence_set+
+    #     * +Array+, when each element is one of the above types, a positive
+    #       +Integer+, a sequence-set formatted +String+, or a deeply nested
+    #       +Array+ of these same types.
+    #   * Any +String+ is sent verbatim when it is a valid \IMAP atom,
+    #     and encoded as an \IMAP quoted or literal string otherwise.
+    #   * Any other nested +Array+ is encoded as a parenthesized list, to group
+    #     multiple search keys (e.g., for use with +OR+ and +NOT+).
+    #   * Any other +Integer+ (besides <tt>-1</tt>) will be sent as +#to_s+.
+    #   * +Date+ objects will be encoded as an \IMAP date (see ::encode_date).
+    #
+    # * When +criteria+ is a string, it will be sent directly to the server
+    #   <em>without any validation or encoding</em>.  *WARNING:* This is
+    #   vulnerable to injection attacks when external inputs are used.
+    #
+    # +charset+ is the name of the {registered character
+    # set}[https://www.iana.org/assignments/character-sets/character-sets.xhtml]
+    # used by strings in the search +criteria+.  When +charset+ isn't specified,
+    # either <tt>"US-ASCII"</tt> or <tt>"UTF-8"</tt> is assumed, depending on
+    # the server's capabilities.  +charset+ may be sent inside +criteria+
+    # instead of as a separate argument.
+    #
     # Related: #uid_search
     #
-    # ===== Search criteria
+    # ===== For example:
+    #
+    #   p imap.search(["SUBJECT", "hello", "NOT", "SEEN"])
+    #   #=> [1, 6, 7, 8]
+    #
+    # The following searches send the exact same command to the server:
+    #
+    #    # criteria array, charset arg
+    #    imap.search(["OR", "UNSEEN", %w(FLAGGED SUBJECT foo)], "UTF-8")
+    #    # criteria string, charset arg
+    #    imap.search("OR UNSEEN (FLAGGED SUBJECT foo)", "UTF-8")
+    #    # criteria array contains charset arg
+    #    imap.search([*%w[CHARSET UTF-8], "OR", "UNSEEN", %w(FLAGGED SUBJECT foo)])
+    #    # criteria string contains charset arg
+    #    imap.search("CHARSET UTF-8 OR UNSEEN (FLAGGED SUBJECT foo)")
     #
-    # For a full list of search criteria,
+    # ===== Search keys
+    #
+    # For full definitions of the standard search +criteria+,
     # see [{IMAP4rev1 §6.4.4}[https://www.rfc-editor.org/rfc/rfc3501.html#section-6.4.4]],
     # or  [{IMAP4rev2 §6.4.4}[https://www.rfc-editor.org/rfc/rfc9051.html#section-6.4.4]],
     # in addition to documentation for
-    # any [CAPABILITIES[https://www.iana.org/assignments/imap-capabilities/imap-capabilities.xhtml]]
-    # reported by #capabilities which may define additional search filters, e.g:
+    # any #capabilities which may define additional search filters, such as
     # +CONDSTORE+, +WITHIN+, +FILTERS+, <tt>SEARCH=FUZZY</tt>, +OBJECTID+, or
-    # +SAVEDATE+.  The following are some common search criteria:
+    # +SAVEDATE+.
+    #
+    # With the exception of <em>sequence-set</em> and <em>parenthesized
+    # list</em>, all search keys are composed of prefix label with zero or more
+    # arguments.  The number and type of arguments is specific to each search
+    # key.
+    #
+    # +ALL+::
+    #   Matches every message in the mailbox.
+    #
+    # (_search-key_ _search-key_...)::
+    #   Combines one or more _search-key_ arguments to match
+    #   messages which match all contained search keys.  Useful for +OR+, +NOT+,
+    #   and other search keys with _search-key_ arguments.
+    #
+    #   _Note:_ this search key has no label.
+    #
+    # +OR+ _search-key_ _search-key_::
+    #   Matches messages which match either _search-key_ argument.
+    #
+    # +NOT+ _search-key_::
+    #   Matches messages which do not match _search-key_.
+    #
+    # _sequence-set_::
+    #   Matches messages with message sequence numbers in _sequence-set_.
+    #
+    #   _Note:_ this search key has no label.
+    #
+    #   <em>+UIDONLY+ must *not* be enabled.</em>
+    #   {[RFC9586]}[https://www.rfc-editor.org/rfc/rfc9586.html]
+    #
+    # +UID+ _sequence-set_::
+    #   Matches messages with a UID in _sequence-set_.
+    #
+    # +ANSWERED+::
+    # +UNANSWERED+::
+    #   Matches messages with or without the <tt>\\Answered</tt> flag.
+    # +DELETED+::
+    # +UNDELETED+::
+    #   Matches messages with or without the <tt>\\Deleted</tt> flag.
+    # +DRAFT+::
+    # +UNDRAFT+::
+    #   Matches messages with or without the <tt>\\Draft</tt> flag.
+    # +FLAGGED+::
+    # +UNFLAGGED+::
+    #   Matches messages with or without the <tt>\\Flagged</tt> flag.
+    # +SEEN+::
+    # +UNSEEN+::
+    #   Matches messages with or without the <tt>\\Seen</tt> flag.
+    #
+    # +KEYWORD+ _keyword_::
+    # +UNKEYWORD+ _keyword_::
+    #   Matches messages with or without the specified _keyword_.
+    #
+    # +BCC+ _substring_::
+    #   Matches when _substring_ is in the envelope's BCC field.
+    # +CC+ _substring_::
+    #   Matches when _substring_ is in the envelope's CC field.
+    # +FROM+ _substring_::
+    #   Matches when _substring_ is in the envelope's FROM field.
+    # +SUBJECT+ _substring_::
+    #   Matches when _substring_ is in the envelope's SUBJECT field.
+    # +TO+ _substring_::
+    #   Matches when _substring_ is in the envelope's TO field.
+    #
+    # +HEADER+ _field_ _substring_::
+    #   Matches when _substring_ is in the specified header _field_.
+    #
+    # +BODY+ _string_::
+    #   Matches when _string_ is in the body of the message.
+    #   Does not match on header fields.
+    #
+    #   The server _may_ use flexible matching, rather than simple substring
+    #   matches.  For example, this may use stemming or match only full words.
+    #
+    # +TEXT+ _string_::
+    #   Matches when _string_ is in the header or body of the message.
+    #
+    #   The server _may_ use flexible matching, rather than simple substring
+    #   matches.  For example, this may use stemming or match only full words.
+    #
+    # +BEFORE+ _date_::
+    # +ON+ _date_::
+    # +SINCE+ _date_::
+    #   Matches when the +INTERNALDATE+ is earlier than, on, or later than
+    #   _date_.
+    #
+    # +SENTBEFORE+ _date_::
+    # +SENTON+ _date_::
+    # +SENTSINCE+ _date_::
+    #   Matches when the +Date+ header is earlier than, on, or later than _date_.
+    #
+    # +SMALLER+ _bytes_::
+    # +LARGER+ _bytes_::
+    #   Matches when +RFC822.SIZE+ is smaller/larger than _bytes_.
+    #
+    # ====== Removed from +IMAP4rev2+
+    #
+    # The <tt>\\Recent</tt> flag has been removed from +IMAP4rev2+.  So these
+    # search keys require the +IMAP4rev1+ capability.
     #
-    # <message set>:: a set of message sequence numbers.  "<tt>,</tt>" indicates
-    #                 an interval, "+:+" indicates a range.  For instance,
-    #                 "<tt>2,10:12,15</tt>" means "<tt>2,10,11,12,15</tt>".
+    # +RECENT+::
+    # +UNRECENT+::
+    #   Matches messages with or without the <tt>\\Recent</tt> flag.
     #
-    # BEFORE <date>:: messages with an internal date strictly before
-    #                 <b><date></b>.  The date argument has a format similar
-    #                 to <tt>8-Aug-2002</tt>, and can be formatted using
-    #                 Net::IMAP.format_date.
+    # +NEW+::
+    #   Equivalent to <tt>(RECENT UNSEEN)</tt>.
     #
-    # BODY <string>:: messages that contain <string> within their body.
+    # ====== Extension search keys
     #
-    # CC <string>:: messages containing <string> in their CC field.
+    # The search keys described below are defined by standard \IMAP extensions.
     #
-    # FROM <string>:: messages that contain <string> in their FROM field.
+    # +OLDER+ _interval_::
+    # +YOUNGER+ _interval_::
+    #   Matches when +INTERNALDATE+ is more/less than _interval_ seconds ago.
     #
-    # NEW:: messages with the \Recent, but not the \Seen, flag set.
+    #   <em>Requires the +WITHIN+ capability</em>.
+    #   {[RFC5032]}[https://www.rfc-editor.org/rfc/rfc5032.html]
     #
-    # NOT <search-key>:: negate the following search key.
+    # +ANNOTATION+ _entry_ _attr_ _value_::
+    #   Matches messages that have annotations with entries matching _entry_,
+    #   attributes matching _attr_, and _value_ in the attribute's values.
     #
-    # OR <search-key> <search-key>:: "or" two search keys together.
+    #   <em>Requires the +ANNOTATE-EXPERIMENT-1+ capability</em>.
+    #   {[RFC5257]}[https://www.rfc-editor.org/rfc/rfc5257.html].
     #
-    # ON <date>:: messages with an internal date exactly equal to <date>,
-    #             which has a format similar to 8-Aug-2002.
+    # +FILTER+ _filter_::
+    #   References a _filter_ that is stored on the server and matches all
+    #   messages which would be matched by that filter's search criteria.
     #
-    # SINCE <date>:: messages with an internal date on or after <date>.
+    #   <em>Requires the +FILTERS+ capability</em>.
+    #   {[RFC5466]}[https://www.rfc-editor.org/rfc/rfc5466.html#section-3.1]
     #
-    # SUBJECT <string>:: messages with <string> in their subject.
+    # +FUZZY+ _search-key_::
+    #   Uses fuzzy matching for the specified search key.
     #
-    # TO <string>:: messages with <string> in their TO field.
+    #   <em>Requires the <tt>SEARCH=FUZZY</tt> capability.</em>
+    #   {[RFC6203]}[https://www.rfc-editor.org/rfc/rfc6203.html#section-6].
     #
-    # ===== For example:
+    # +MODSEQ+ _modseq_::
+    #   Matches when +MODSEQ+ is greater than or equal to _modseq_.
     #
-    #   p imap.search(["SUBJECT", "hello", "NOT", "NEW"])
-    #   #=> [1, 6, 7, 8]
+    #   <em>Requires the +CONDSTORE+ capability</em>.
+    #   {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1.5].
+    #
+    # +MODSEQ+ _entry_ _entry-type_ _modseq_::
+    #   Matches when a specific metadata _entry_ has been updated since
+    #   _modseq_.
+    #
+    #   For flags, the corresponding _entry_ name is
+    #   <tt>"/flags/#{flag_name}"</tt>, where _flag_name_ includes the
+    #   <tt>\\</tt> prefix.  _entry-type_ can be one of <tt>"shared"</tt>,
+    #   <tt>"priv"</tt> (private), or <tt>"all"</tt>.
+    #
+    #   <em>Requires the +CONDSTORE+ capability</em>.
+    #   {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1.5].
+    #
+    # +EMAILID+ _objectid_::
+    # +THREADID+ _objectid_::
+    #   Matches when +EMAILID+/+THREADID+ is equal to _objectid_
+    #   (substring matches are not supported).
+    #
+    #   <em>Requires the +OBJECTID+ capability</em>.
+    #   {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-6]
+    #
+    # +SAVEDATESUPPORTED+::
+    #   Matches every message in the mailbox when the mailbox supports the save
+    #   date attribute.  Otherwise, it matches no messages.
+    #
+    #   <em>Requires the +SAVEDATE+ capability</em>.
+    #   {[RFC8514]}[https://www.rfc-editor.org/rfc/rfc8514.html#section-4.3]
+    #
+    # +SAVEDBEFORE+ _date_::
+    # +SAVEDON+ _date_::
+    # +SAVEDSINCE+ _date_::
+    #   Matches when the save date is earlier than, on, or later than _date_.
+    #
+    #   <em>Requires the +SAVEDATE+ capability.</em>
+    #   {[RFC8514]}[https://www.rfc-editor.org/rfc/rfc8514.html#section-4.3]
     #
     # ===== Capabilities
     #
-    # If [CONDSTORE[https://www.rfc-editor.org/rfc/rfc7162.html]] is supported
+    # If CONDSTORE[https://www.rfc-editor.org/rfc/rfc7162.html] is supported
     # and enabled for the selected mailbox, a non-empty SearchResult will
     # include a +MODSEQ+ value.
     #   imap.select("mbox", condstore: true)
-    #   result = imap.search(["SUBJECT", "hi there", "not", "new")
+    #   result = imap.search(["SUBJECT", "hi there", "not", "new"])
     #   #=> Net::IMAP::SearchResult[1, 6, 7, 8, modseq: 5594]
     #   result.modseq # => 5594
-    def search(keys, charset = nil)
-      return search_internal("SEARCH", keys, charset)
+    def search(...)
+      search_internal("SEARCH", ...)
     end
 
+    # :call-seq:
+    #   uid_search(criteria, charset = nil) -> result
+    #
     # Sends a {UID SEARCH command [IMAP4rev1 §6.4.8]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.8]
     # to search the mailbox for messages that match the given searching
     # criteria, and returns unique identifiers (<tt>UID</tt>s).
@@ -2008,9 +2200,9 @@ module Net
     # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+
     # capability has been enabled.
     #
-    # See #search for documentation of search criteria.
-    def uid_search(keys, charset = nil)
-      return search_internal("UID SEARCH", keys, charset)
+    # See #search for documentation of parameters.
+    def uid_search(...)
+      search_internal("UID SEARCH", ...)
     end
 
     # :call-seq:
@@ -2939,18 +3131,11 @@ module Net
       end
     end
 
-    def search_internal(cmd, keys, charset)
-      if keys.instance_of?(String)
-        keys = [RawData.new(keys)]
-      else
-        normalize_searching_criteria(keys)
-      end
+    def search_internal(cmd, keys, charset = nil)
+      keys = normalize_searching_criteria(keys)
+      args = charset ? ["CHARSET", charset, *keys] : keys
       synchronize do
-        if charset
-          send_command(cmd, "CHARSET", charset, *keys)
-        else
-          send_command(cmd, *keys)
-        end
+        send_command(cmd, *args)
         clear_responses("SEARCH").last || []
       end
     end
@@ -2997,11 +3182,7 @@ module Net
     end
 
     def sort_internal(cmd, sort_keys, search_keys, charset)
-      if search_keys.instance_of?(String)
-        search_keys = [RawData.new(search_keys)]
-      else
-        normalize_searching_criteria(search_keys)
-      end
+      search_keys = normalize_searching_criteria(search_keys)
       synchronize do
         send_command(cmd, sort_keys, charset, *search_keys)
         clear_responses("SORT").last || []
@@ -3009,25 +3190,39 @@ module Net
     end
 
     def thread_internal(cmd, algorithm, search_keys, charset)
-      if search_keys.instance_of?(String)
-        search_keys = [RawData.new(search_keys)]
-      else
-        normalize_searching_criteria(search_keys)
-      end
+      search_keys = normalize_searching_criteria(search_keys)
       synchronize do
         send_command(cmd, algorithm, charset, *search_keys)
         clear_responses("THREAD").last || []
       end
     end
 
-    def normalize_searching_criteria(keys)
-      keys.collect! do |i|
-        case i
-        when -1, Range, Array
-          SequenceSet.new(i)
+    def normalize_searching_criteria(criteria)
+      return RawData.new(criteria) if criteria.is_a?(String)
+      criteria.map {|i|
+        if coerce_search_arg_to_seqset?(i)
+          SequenceSet[i]
         else
           i
         end
+      }
+    end
+
+    def coerce_search_arg_to_seqset?(obj)
+      case obj
+      when Set, -1, :* then true
+      when Range       then true
+      when Array       then obj.all? { coerce_search_array_arg_to_seqset? _1 }
+      else                  obj.respond_to?(:to_sequence_set)
+      end
+    end
+
+    def coerce_search_array_arg_to_seqset?(obj)
+      case obj
+      when Integer then obj.positive? || obj == -1
+      when String  then ResponseParser::Patterns::SEQUENCE_SET_STR.match?(obj.b)
+      else
+        coerce_search_arg_to_seqset?(obj)
       end
     end
 

data/rakelib/string_prep_tables_generator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set" unless defined?(::Set)
+
 # Generator for stringprep regexps.
 #
 # Combines Unicode character classes with generated tables.  Generated regexps

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-imap
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Shugo Maeda
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-10-16 00:00:00.000000000 Z
+date: 2024-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-protocol
@@ -125,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key: 
 specification_version: 4
 summary: Ruby client api for Internet Message Access Protocol