Subject: 27.0.50; Merge feature/gnus-select2
From: Eric Abrahamsen <[email-masked]>
To: [email-masked]
Cc: Andrew Cohen <[email-masked]>, Lars Ingebrigtsen <[email-masked]>
Date: Tue, 22 Oct 2019 09:14:43 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi all, Andy Cohen's nnselect Gnus backend looks ready to merge -- he
wrote to emacs.devel but it occurs to me it might be better to start
here. His original message is here, and I've pasted the full text below
the link:

https://lists.gnu.org/archive/html/emacs-devel/2019-10/msg00689.html

------

After many months I have updated the gnus-select2 feature branch. This
incorporates a number of bug fixes as well as updating to the latest
master. I have been using this version (or something close to it) for
nearly a year with no problems. For those who use gnus please check it
out and if no obvious bugs appear I will figure out how to push this
into master.

This branch introduces a new "virtual" backend, nnselect, that allows an
arbitrary list of messages to be treated as a normal gnus group. The
messages may come from multiple servers and multiple backends. The
resulting group behaves in (almost) all respects like any real group:
messages may be threaded, marked, moved, deleted, copied, etc. nnselect
groups may be ephemeral or persistent.

An obvious use case for nnselect is to create a functional group out of
the messages produced by some kind of search. In this feature branch
searching (performed by nnir) simply returns a list of articles that is
passed to nnselect, which handles the group creation and message
manipulation. (This should be transparent to the user---that is,
searching should appear to function as before, except that the group
created from the search has more functionality).

Below is a first pass at some documentation that hasn't yet been pushed
into the gnus manual on the branch.

=nnselect= is a select method for virtual groups composed of messages
from other groups that may span multiple servers and backends. For the
most part these groups behave like any other group: messages may be
threaded, marked, moved, deleted, copied, etc.; groups may be ephemeral
or persistent; groups may be created via gnus-group-make-group or
browsed as foreign via gnus-group-browse-foreign-server.

The key to using an nnselect group is specifying the messages to
include. Each nnselect group has a group parameter =nnselect-specs=
which is an alist with two elements: a function =nnselect-function=; and
arguments =nnselect-args= to be passed to the function, if any.

The function =nnselect-function= must return a vector. Each element of
this vector is in turn a 3-element vector corresponding to one
message. The 3 elements are: the fully-qualified group name; the message
number; and a "score" that can be used for additional sorting. The
values for the score are arbitrary, and are not used directly by the
nnselect method---they may, for example, all be set to 100.

As an example we might have a group whose nnselect-specs are

 (nnselect-specs
  (nnselect-function . identity)
  (nnselect-args .
                 [["nnimap+work:mail" 595 100]
                  ["nnimap+home:sent" 223 100]
                ["nntp+news.gmane.org:gmane.emacs.gnus.general" 23666 100])))

Here the function is the identity and the argument is just a list of
messages.

Or the function might be a search query (using nnir):

 (nnselect-specs
  (nnselect-function . nnir-run-query)
  (nnselect-args
   (nnir-query-spec
    (query . "FLAGGED")
    (criteria . ""))
   (nnir-group-spec
    ("nnimap:home")
    ("nnimap:work"))))

This creates a group composed of all flagged messages on two imap
servers, "home" and "work".

And one last example. Here is a function that runs a search query to
find all message that have been received over the past =days=

(defun my-recent-email (days)
      (let ((query-spec
             (list
              (cons 'query
                    (format-time-string "SENTSINCE %d-%b-%Y"
                                        (time-subtract (current-time)
                                                       (days-to-time days))))
              (cons 'criteria "")))
            (group-spec  (list (list "nnimap:home") (list "nnimap:work"))))
        (nnir-run-query   (cons 'nnir-specs
                                (list (cons 'nnir-query-spec query-spec)
                                      (cons 'nnir-group-spec group-spec))))))

Then an nnselect-specs 

 (nnselect-specs
  (nnselect-function . my-recent-email)
  (nnselect-args . 7))

will provide a group composed of all messages on the home and work
servers received in the last 7 days.

** scanning

Refreshing the selection of an nnselect group by running the
nnselect-function may take a long time to complete. Consequently
nnselect groups are not refreshed by default when
=gnus-group-get-new-news= is invoked. In those cases where running the
function is not too time-consuming, a group parameter of nnselect-rescan
can be set to allow automatic refreshing. A refresh can always be
invoked manually through =gnus-group-get-new-news-this-group=.