From a366a0d1deeaafacd434436489b2a08abb233fe4 Mon Sep 17 00:00:00 2001 From: nick evans Date: Thu, 7 Nov 2024 10:37:20 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Document=20all=20known=20standar?= =?UTF-8?q?d=20search=20keys?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rather than only list a subset of search keys, this documents them all. --- lib/net/imap.rb | 193 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 170 insertions(+), 23 deletions(-) diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 494b258d..c52b2498 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -1977,46 +1977,193 @@ def uid_expunge(uid_set) # # criteria string contains charset arg # imap.search("CHARSET UTF-8 OR UNSEEN FLAGGED SUBJECT foo") # - # ===== Search criteria + # ===== Search keys # - # For a full list of search criteria, + # 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+, SEARCH=FUZZY, +OBJECTID+, or - # +SAVEDATE+. The following are some common search criteria: + # +SAVEDATE+. + # + # With the exception of sequence-set and parenthesized + # list, 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. + # + # +UIDONLY+ must *not* be enabled. + # {[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 \\Answered flag. + # +DELETED+:: + # +UNDELETED+:: + # Matches messages with or without the \\Deleted flag. + # +DRAFT+:: + # +UNDRAFT+:: + # Matches messages with or without the \\Draft flag. + # +FLAGGED+:: + # +UNFLAGGED+:: + # Matches messages with or without the \\Flagged flag. + # +SEEN+:: + # +UNSEEN+:: + # Matches messages with or without the \\Seen 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 \\Recent flag has been removed from +IMAP4rev2+. So these + # search keys require the +IMAP4rev1+ capability. # - # :: a set of message sequence numbers. "," indicates - # an interval, "+:+" indicates a range. For instance, - # "2,10:12,15" means "2,10,11,12,15". + # +RECENT+:: + # +UNRECENT+:: + # Matches messages with or without the \\Recent flag. + # + # +NEW+:: + # Equivalent to (RECENT UNSEEN). + # + # ====== Extension search keys + # + # The search keys described below are defined by standard \IMAP extensions. + # + # +OLDER+ _interval_:: + # +YOUNGER+ _interval_:: + # Matches when +INTERNALDATE+ is more/less than _interval_ seconds ago. + # + # Requires the +WITHIN+ capability. + # {[RFC5032]}[https://www.rfc-editor.org/rfc/rfc5032.html] + # + # +ANNOTATION+ _entry_ _attr_ _value_:: + # Matches messages that have annotations with entries matching _entry_, + # attributes matching _attr_, and _value_ in the attribute's values. + # + # Requires the +ANNOTATE-EXPERIMENT-1+ capability. + # {[RFC5257]}[https://www.rfc-editor.org/rfc/rfc5257.html]. + # + # +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. + # + # Requires the +FILTERS+ capability. + # {[RFC5466]}[https://www.rfc-editor.org/rfc/rfc5466.html#section-3.1] + # + # +FUZZY+ _search-key_:: + # Uses fuzzy matching for the specified search key. + # + # Requires the SEARCH=FUZZY capability. + # {[RFC6203]}[https://www.rfc-editor.org/rfc/rfc6203.html#section-6]. # - # BEFORE :: messages with an internal date strictly before - # . The date argument has a format similar - # to 8-Aug-2002, and can be formatted using - # Net::IMAP.format_date. + # +MODSEQ+ _modseq_:: + # Matches when +MODSEQ+ is greater than or equal to _modseq_. # - # BODY :: messages that contain within their body. + # Requires the +CONDSTORE+ capability. + # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1.5]. # - # CC :: messages containing in their CC field. + # +MODSEQ+ _entry_ _entry-type_ _modseq_:: + # Matches when a specific metadata _entry_ has been updated since + # _modseq_. # - # FROM :: messages that contain in their FROM field. + # For flags, the corresponding _entry_ name is + # "/flags/#{flag_name}", where _flag_name_ includes the + # \\ prefix. _entry-type_ can be one of "shared", + # "priv" (private), or "all". # - # NEW:: messages with the \Recent, but not the \Seen, flag set. + # Requires the +CONDSTORE+ capability. + # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html#section-3.1.5]. # - # NOT :: negate the following search key. + # +EMAILID+ _objectid_:: + # +THREADID+ _objectid_:: + # Matches when +EMAILID+/+THREADID+ is equal to _objectid_ + # (substring matches are not supported). # - # OR :: "or" two search keys together. + # Requires the +OBJECTID+ capability. + # {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html#section-6] # - # ON :: messages with an internal date exactly equal to , - # which has a format similar to 8-Aug-2002. + # +SAVEDATESUPPORTED+:: + # Matches every message in the mailbox when the mailbox supports the save + # date attribute. Otherwise, it matches no messages. # - # SINCE :: messages with an internal date on or after . + # Requires the +SAVEDATE+ capability. + # {[RFC8514]}[https://www.rfc-editor.org/rfc/rfc8514.html#section-4.3] # - # SUBJECT :: messages with in their subject. + # +SAVEDBEFORE+ _date_:: + # +SAVEDON+ _date_:: + # +SAVEDSINCE+ _date_:: + # Matches when the save date is earlier than, on, or later than _date_. # - # TO :: messages with in their TO field. + # Requires the +SAVEDATE+ capability. + # {[RFC8514]}[https://www.rfc-editor.org/rfc/rfc8514.html#section-4.3] # # ===== Capabilities #