✨ Add basic ESearch support

[nevans]

Parse ESEARCH into ESearchResult, with support for generic RFC4466 syntax and RFC4731 ESEARCH return data. For compatibility, ESearchResult#to_a returns an array of integers (sequence numbers or UIDs) whenever any ALL result is available.

Gather ESEARCH response to #search/#uid_search. If the server returns both ESEARCH and SEARCH, both are cleared from the responses hash, but only the ESEARCH is returned.

When the server doesn't send any search responses and return options are passed, return an empty ESearchResult. This empty result will have the appropriate tag and uid values, but no data. Otherwise return an empty SearchResult.

Add keyword param for search return options, and process it differently from criteria. Also extract a return argument out of the criteria array, and process it like the return kwarg. (FYI: I discovered https://bugs.ruby-lang.org/issues/20956 while working on this).

TODO list

• ESearchResponse < Data.define(:tag, :uid, :data)
  • #data is a generic Array of [name, value] pairs. Not using Hash because some names can be repeated, and the order is significant even between different names. data.assoc(name) can be used for quick lookup.
    • TODO: test cases for unknown extensions
    • TODO: document that ExtensionData will be used for unknown return data
  • Methods for compatibility with SearchResult:
    • #to_a returns numbers from #all, #partial, or an empty array
    • #modseq
  • Methods for ESEARCH return data: #min, #max, #all, #count
  • Methods for ESEARCH + CONDSEQ: #modseq
• Parse ESEARCH into ESearchResponse
  • Return data for unknown extensions: use ExtensionData.new(tagged_ext_value)
  • Return data for ESEARCH and CONDSTORE (MIN, MAX, ALL, COUNT, MODSEQ): parse as Integer or SequenceSet
• Support in #search and #uid_search
  • Support for return options
    • return kwarg: must be an Array, and process differently than criteria.
    • extract return from array criteria and process differently than criteria
    • When server doesn't return any response but return options are used, return an empty ESearchResponse rather than an empty SearchResponse.
    • Document supported return options
  • Gather ESEARCH responses in addition to SEARCH responses. If server sends both, prefer to return the ESEARCH responses.
• For consistency, add charset kwarg to #search, #uid_search

TODO: Remove the following from this PR (make new PRs for them):

• ESearchResponse methods and data classes
  • remove #to_a returning numbers from #partial
  • remove #partial
    • remove ESearchResponse::PartialResult
  • remove #updates
  • remove #relevancy
• Parse PARTIAL, ADDTO, REMOVEFROM, RELEVANCY as generic ExtensionData

Related future PRs:

• Support for PARTIAL (RFC9394, RFC5267)
• Support for CONTEXT=* (RFC5267)
  • Automatically update a specified SequenceSet?
  • Register a special updates response handler?
• Support for ESORT (RFC5267)
• Support for SEARCH=FUZZY (RFC6203)
  • Method to zip #relevancy scores with numbers from #all or #partial
  • Unsorted ESearchResult #to_a, #all, #partial
• SequenceSet methods:
  • unsorted #numbers
  • More methods for accessing or mutating SequenceSet without affecting the order
  • #prepend - like #append but adds to the beginning
  • #insert(index, value)
  • #remove(index_or_range)
  • unsorted version of #[], #at, #slice
  • unsorted #zip with array of numbers (for RELEVANCY)
  • unsorted #zip with another SequenceSet (for COPYUID)

[nevans]

FWIW: I discovered in testing that Yahoo does not return ESEARCH results when RETURN (PARTIAL 1:500) is used, contrary to the PARTIAL RFC that was written by Yahoo engineers!