imap 0.4.6 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26d3a42b29eb3be8775fc3ec60f3559b0834e8ef106e2e3458cd2b93bdee7364
-  data.tar.gz: 85aebe82c105a2d7db62c581ca61bd2c0630fcd7054dc777a02a86e84fd620ba
+  metadata.gz: 4b8f4ea427e7f3c30d6ce897ad13cdf4d22693b18170941d13c96f0e267bde83
+  data.tar.gz: 59a416b6e3687d94b3be00a9c2ce3c43090bd3ae09570b8cb0f9158f07d9a8a0
 SHA512:
-  metadata.gz: bb36b35b0cd5f9ddc6895aa0bfe9c0d644cd5386f13f4b26a66324d767560c3af41a8741be6a4fecf4f69fbbf6028dc823e1207e9aba50ab63a382b0a9750c50
-  data.tar.gz: 79add07e74eb8acc3105b3791be56d020cc50c89e80d47d3e47f8b46cf997b6e9c7fdd44e536292435f5560f380bd1bdac2d966c4bfc53bd548a010e77b93432
+  metadata.gz: 16d311031d31ef2f8b50ebf349134429a3bd4a82174062ffbcf867369c23f039c444a099115ced05911f89093f5f30c3a0a4fe1014d45e1499beb6ecbf522fc4
+  data.tar.gz: '08dc54d7f1f9e867461b521f9383f9e6a56d3e747ee5ec697a53e7015c0f6df079fd2ec96cd8a677c3607bd824ec4e7cb4daefccde1acac09ad3265365457149'

data/CHANGELOG

@@ -1,5 +1,14 @@
 # CHANGELOG
 
+## [0.4.7] - 2026-09-17, ~ Imap::Search: the chaining interface, which the header has documented and which has never run
+- ~ Imap::Search: the generated methods named in lower case, so that from() answers where FROM() did. All 32 were upper case, being defined straight off the key constants, and none was reachable as the header wrote it.
+- ~ Imap::Search: the generated methods return self, having returned the criteria hash, so that they chain.
+- + Imap::Search#not: applies to what follows immediately and to nothing after it. + Negated, which carries a general key's value through the hash; a boolean needs none, false already reading as NOT.
+- ~ Imap::Search#general_to_imap_search_key: ['NOT', key, value] where the value is Negated.
+- ~ Imap::Search: the Usage header takes an imap_client, without which all() has nothing to search.
+- + tests: the lower case names, that they chain, both negations, and that not applies once only.
+- ~ Imap::VERSION: /0.4.6/0.4.7/
+
 ## [0.4.6] - 2026-09-17, ~ Imap::Message#body: BODY.PEEK[TEXT]; ~ Imap::Search#to_imap_search_keys: raise upon a key which is neither
 - ~ Imap::Message#body: BODY.PEEK[TEXT] for BODY[TEXT]. Reading a body set \Seen, so anything which looked at one marked it read; PEEK is the whole of the difference and the response still answers to BODY[TEXT].
 - ~ Imap::Search#to_imap_search_keys: + UnknownSearchKey where the case matched neither operator. An unrecognised key was dropped and the search ran wider than it was asked for, saying nothing.

data/lib/Imap/Search.rb

@@ -2,8 +2,8 @@
 # Imap::Search
 
 # Usage:
-# 1. Imap::Search.new.not.subject('Payday Loans').answered.from('noreply@example.com').all
-# 2. Imap::Search.new({from: 'noreply@example.com', answered: true})
+# 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})
 
 # Notes:
 # 1. List of search keys taken from RFC-3501 (INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1), http://tools.ietf.org/html/rfc3501.
@@ -13,6 +13,11 @@ class Imap
 
     class UnknownSearchKey < ArgumentError; end
 
+    # A general key carries its value; negating one has to carry both, the hash
+    # having nowhere else to put it.  A boolean key needs none of this: false
+    # already reads as NOT.
+    Negated = Struct.new(:value)
+
     ALL_SEARCH_KEYS = %w{
       ALL
       ANSWERED
@@ -84,17 +89,25 @@ class Imap
     }
 
     BOOLEAN_SEARCH_KEYS.each do |boolean_search_key|
-      define_method boolean_search_key do |value = true|
-        criteria.merge!(boolean_search_key.to_sym => value)
+      define_method boolean_search_key.downcase do |value = true|
+        criteria.merge!(boolean_search_key.to_sym => negating? ? !value : value)
+        self
       end
     end
 
     GENERAL_SEARCH_KEYS.each do |general_search_key|
-      define_method general_search_key do |value|
-        criteria.merge!(general_search_key.to_sym => value)
+      define_method general_search_key.downcase do |value|
+        criteria.merge!(general_search_key.to_sym => negating? ? Negated.new(value) : value)
+        self
       end
     end
 
+    # Applies to what follows immediately, and to nothing after that.
+    def not
+      @negate = true
+      self
+    end
+
     attr_accessor :criteria
     attr_accessor :imap_client
 
@@ -121,7 +134,7 @@ class Imap
     end
 
     def general_to_imap_search_key(key, value)
-      [key, value]
+      value.is_a?(Negated) ? ['NOT', key, value.value] : [key, value]
     end
 
     def boolean_to_imap_search_key(key, value)
@@ -132,6 +145,12 @@ class Imap
       end
     end
 
+    def negating?
+      negate = @negate
+      @negate = false
+      negate
+    end
+
     def message_ids
       imap_client.imap.search(to_imap_search_keys)
     end

data/lib/Imap/VERSION.rb

@@ -1,3 +1,3 @@
 class Imap
-  VERSION = '0.4.6'
+  VERSION = '0.4.7'
 end

data/test/Imap/Search_test.rb

@@ -44,6 +44,30 @@ describe Imap::Search do
     end
   end
 
+  describe 'the chaining interface' do
+    it 'names the keys in lower case' do
+      _(Imap::Search.new(client).from('x@y.com').criteria).must_equal({FROM: 'x@y.com'})
+    end
+
+    it 'returns itself, so that it chains' do
+      search = Imap::Search.new(client)
+      _(search.from('x@y.com')).must_be_same_as search
+    end
+
+    it 'negates a general key' do
+      _(Imap::Search.new(client).not.subject('Payday Loans').to_imap_search_keys).must_equal ['NOT', 'SUBJECT', 'Payday Loans']
+    end
+
+    it 'negates a boolean key' do
+      _(Imap::Search.new(client).not.seen.to_imap_search_keys).must_equal ['NOT', 'SEEN']
+    end
+
+    it 'negates what follows immediately and nothing after it' do
+      keys = Imap::Search.new(client).not.subject('Payday Loans').answered.from('noreply@example.com').to_imap_search_keys
+      _(keys).must_equal ['NOT', 'SUBJECT', 'Payday Loans', 'ANSWERED', 'FROM', 'noreply@example.com']
+    end
+  end
+
   describe '#message_ids' do
     it 'returns an array of message IDs' do
       ids = search.message_ids

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imap
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.7
 platform: ruby
 authors:
 - thoran