imap.rb 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9f5b0c607f3b3e66d7284613916d45c077de9a0e97f50f960fa8e63fd7b5586
-  data.tar.gz: 4529940cbd85a56bfbd4ef9d472536234852cd4cabf6349f90763644905ab953
+  metadata.gz: a11cb6eb95eff27b2d107a0e1ad8fc727b1eabb6d2c24523ada41b3906b9d42e
+  data.tar.gz: 5a37e2eff7d0177f768aeb77182f04dd47d7686cdbd42f99814c35a140e4d270
 SHA512:
-  metadata.gz: 7279ae1bb4fd2456fa2acf57cad565a0af28d2be5795e1e6bf9924b2b9f6583acf2e4a71735944c8bf3f3dc56d403d3abba5943eb87ea15054f12c718665bab9
-  data.tar.gz: 060c6a1b974e983979130cf62d03e0630ef548b64b9e80a522c6064c031126385de84f762cb1a158fd50b03711902f1430038b8aa0b3f63864c7dc4e85366548
+  metadata.gz: 8a22fc1e24e9c7765d06733837547a29f581083586b0e9fdef601756ee1d61561b44689cb7dcf5ed62f3db8fc2096ac295ac8859fc765de30fd1135123a9aac6
+  data.tar.gz: 22a69f98811483319992902f342267743bbb69acac1723b1dc8067a54f9805e8965d91925a289cfd376eac22fff3d8ec333125f4f8733cf05debd9025ad38843

data/CHANGELOG

@@ -2,6 +2,22 @@
 
 ## 20260917
 
+0.9.0: + all_of and ALL
+
+1. + Imap::Search#all_of: all_of: [{text: 'invoice'}, {text: 'overdue'}] for TEXT invoice TEXT overdue. IMAP has no AND keyword, keys simply sitting side by side, but a hash cannot hold the same key twice, so two terms upon the one key could not be asked for at all: {text: 'a', text: 'b'} keeps b and drops a without a word. Each element is a criteria hash of its own, so or and not nest inside it.
+2. ~ Imap::Search#to_imap_search_keys: + ALL_OF and + ALL, read before the operator tests beside OR and NOT, being none of the three. ALL sat in ALL_SEARCH_KEYS and in neither operator list, so {all: true} raised UnknownSearchKey. It is the key meaning every message, which is precisely what a search with no criteria has to send, so the hash could not express the simplest search there is.
+3. ALL is a case and not a member of BOOLEAN_SEARCH_KEYS, where it appears to belong: each of those defines a method of its own name, and #all is already the alias for #message_ids which the header's own example ends upon. Adding it there redefined the alias silently, which warning = true reported and 0.4.4 turned on for this.
+4. + 5 tests: that all_of ands a list, that it is how the one key carries several terms where a hash cannot, that or and not nest within it, that it sits beside the plain keys, and that {all: true} answers ['ALL'].
+5. ~ Imap::VERSION: /0.8.0/0.9.0/
+
+
+0.8.0: + Imap::Message.for, the fetch without the search, and a class a program can subclass.
+
+1. + Imap::Message.for(imap_client, message_ids): the batched fetch on its own, .search now being the search and then this. A program which builds its own search keys had no way in: .search couples the two, so search-mail had 159 lines of its own Hit reimplementing the fetch beside it.
+2. ~ Imap::Message.for: builds with new rather than Imap::Message.new, so that a subclass is handed back its own kind. A program which wants a message of its own, with a mailbox or a decoded body upon it, subclasses rather than starts again.
+3. + 4 tests: that .for builds for ids searched elsewhere, that it fetches once, that it is empty where nothing was found, and that a subclass gets itself back.
+4. ~ Imap::VERSION: /0.7.0/0.8.0/
+
 0.7.0: ~ Imap::Message: + #uid, #flags, #seen?, #size, #received_at, #sent_at, #cc, #from_address, #from_domain, #attachment?, #attachment_filenames, #source, .decode; + Imap#mailboxes
 
 1. + Imap::Message#uid, #flags, #seen?, #size, #received_at, #sent_at, #cc, #from_address, #from_domain, #attachment?, #attachment_filenames, #source. Everything a search had to go around the gem to Net::IMAP for.

data/lib/Imap/Message.rb

@@ -3,16 +3,17 @@
 
 # Usage:
 # 1. Imap::Message.search(imap_client, {from: 'noreply@example.com'})
-# 2. Imap::Message.new(message_id, imap_client)
-# 3. Imap::Message.new(message_id, imap_client).body
-# 4. Imap::Message.new(message_id, imap_client).urls
-# 5. Imap::Message.new(message_id, imap_client).mark_as_read
-# 6. Imap::Message.new(message_id, imap_client).subject
-# 7. Imap::Message.new(message_id, imap_client).from
-# 8. Imap::Message.new(message_id, imap_client).to
-# 9. Imap::Message.new(message_id, imap_client).received_at
-# 10. Imap::Message.new(message_id, imap_client).attachment_filenames
-# 11. Imap::Message.new(message_id, imap_client).source
+# 2. Imap::Message.for(imap_client, imap_client.imap.search(['ALL']))
+# 3. Imap::Message.new(message_id, imap_client)
+# 4. Imap::Message.new(message_id, imap_client).body
+# 5. Imap::Message.new(message_id, imap_client).urls
+# 6. Imap::Message.new(message_id, imap_client).mark_as_read
+# 7. Imap::Message.new(message_id, imap_client).subject
+# 8. Imap::Message.new(message_id, imap_client).from
+# 9. Imap::Message.new(message_id, imap_client).to
+# 10. Imap::Message.new(message_id, imap_client).received_at
+# 11. Imap::Message.new(message_id, imap_client).attachment_filenames
+# 12. Imap::Message.new(message_id, imap_client).source
 
 require 'time'
 
@@ -28,19 +29,23 @@ class Imap
     ENCODED_WORD = /=\?([^?]+)\?([BbQq])\?([^?]*)\?=/
 
     class << self
+      def search(imap_client, **search_criteria)
+        self.for(imap_client, Imap::Search.new(imap_client, search_criteria).message_ids)
+      end
+      alias_method :find, :search
 
       # One fetch for a slice of messages rather than one per attribute per
       # message.  A hundred messages cost a round trip apiece for the subject and
       # another apiece for the from; they cost one for the hundred now.
-      def search(imap_client, **search_criteria)
-        message_ids = Imap::Search.new(imap_client, search_criteria).message_ids
+      #
+      # new and not Imap::Message.new, so that a subclass gets its own kind back.
+      def for(imap_client, message_ids)
         message_ids.each_slice(SLICE).flat_map do |slice|
           imap_client.imap.fetch(slice, FETCH_ATTRIBUTES).collect do |data|
-            Imap::Message.new(data.seqno, imap_client, data)
+            new(data.seqno, imap_client, data)
           end
         end
       end
-      alias_method :find, :search
 
       # RFC 2047: =?charset?B?base64?= and =?charset?Q?quoted-printable?=, which
       # headers carry wherever the subject or a name is not ASCII.
@@ -62,7 +67,6 @@ class Imap
       rescue StandardError
         text
       end
-
     end # class << self
 
     attr_accessor :imap_client

data/lib/Imap/Search.rb

@@ -4,6 +4,7 @@
 # Usage:
 # 1. Imap::Search.new(imap_client).not.subject('Payday Loans').answered.from('noreply@example.com').all
 # 2. Imap::Search.new(imap_client, {from: 'noreply@example.com', answered: true})
+# 3. Imap::Search.new(imap_client, {all_of: [{text: 'invoice'}, {text: 'overdue'}]})
 
 # Notes:
 # 1. List of search keys taken from RFC-3501 (INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1), http://tools.ietf.org/html/rfc3501.
@@ -123,6 +124,10 @@ class Imap
       criteria.inject([]) do |m, kv|
         key, value = kv.first.to_s.upcase, kv.last
         case
+        when key == 'ALL'
+          m << 'ALL'
+        when key == 'ALL_OF'
+          m << all_of(value)
         when key == 'OR'
           m << any_of(value)
         when key == 'NOT'
@@ -137,6 +142,13 @@ class Imap
       end.flatten
     end
 
+    # AND has no keyword: keys sit side by side and the server ands them.  A hash
+    # cannot hold the same key twice, though, so several terms upon the one key
+    # say so here: all_of: [{text: 'a'}, {text: 'b'}] for TEXT a TEXT b.
+    def all_of(criteria_hashes)
+      criteria_hashes.flat_map{|criteria_hash| Search.new(nil, criteria_hash).to_imap_search_keys}
+    end
+
     # OR takes two keys and no more, so three criteria nest: OR OR a b c.  Each
     # is a criteria hash of its own, so either side may nest further.
     def any_of(criteria_hashes)

data/lib/Imap/VERSION.rb

@@ -1,3 +1,3 @@
 class Imap
-  VERSION = '0.7.0'
+  VERSION = '0.9.0'
 end

data/test/Imap/Message_test.rb

@@ -30,6 +30,29 @@ describe Imap::Message do
     end
   end
 
+  describe '.for' do
+    it 'builds messages for ids the caller searched for itself' do
+      messages = Imap::Message.for(client, [1, 2, 3])
+      _(messages.size).must_equal 3
+      _(messages.first).must_be_instance_of Imap::Message
+      _(messages.first.subject).must_match(/Mock Subject/)
+    end
+
+    it 'fetches once for the whole slice' do
+      Imap::Message.for(client, [1, 2, 3])
+      _(client.imap.fetch_count).must_equal 1
+    end
+
+    it 'is empty where nothing was found' do
+      _(Imap::Message.for(client, [])).must_equal []
+    end
+
+    it 'gives a subclass back its own kind' do
+      hit = Class.new(Imap::Message)
+      _(hit.for(client, [1]).first).must_be_instance_of hit
+    end
+  end
+
   describe 'the batched fetch' do
     it 'fetches once for the whole slice rather than once per message' do
       messages = Imap::Message.search(client, from: 'test@example.com')

data/test/Imap/Search_test.rb

@@ -47,6 +47,27 @@ describe Imap::Search do
   describe 'OR, NOT and HEADER' do
     def keys(criteria) = Imap::Search.new(client, criteria).to_imap_search_keys
 
+    it 'answers ALL, which every key list named and neither operator list held' do
+      _(keys(all: true)).must_equal ['ALL']
+    end
+
+    it 'ands a list of criteria hashes for ALL_OF' do
+      _(keys(all_of: [{text: 'invoice'}, {text: 'overdue'}])).must_equal ['TEXT', 'invoice', 'TEXT', 'overdue']
+    end
+
+    it 'is how the one key carries more than one term, a hash holding it once' do
+      _(keys({text: 'invoice'}.merge(text: 'overdue'))).must_equal ['TEXT', 'overdue']
+      _(keys(all_of: [{text: 'invoice'}, {text: 'overdue'}])).must_equal ['TEXT', 'invoice', 'TEXT', 'overdue']
+    end
+
+    it 'nests OR and NOT inside ALL_OF' do
+      _(keys(all_of: [{not: {text: 'draft'}}, {or: [{from: 'a@x'}, {to: 'b@y'}]}])).must_equal ['NOT', 'TEXT', 'draft', 'OR', 'FROM', 'a@x', 'TO', 'b@y']
+    end
+
+    it 'sits beside the plain keys' do
+      _(keys(since: '1-Sep-2026', all_of: [{text: 'a'}, {text: 'b'}])).must_equal ['SINCE', '1-Sep-2026', 'TEXT', 'a', 'TEXT', 'b']
+    end
+
     it 'takes two criteria hashes for OR' do
       _(keys(or: [{from: 'a@x'}, {to: 'b@y'}])).must_equal ['OR', 'FROM', 'a@x', 'TO', 'b@y']
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imap.rb
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - thoran