Function: gnus-search-parse-query

gnus-search-parse-query is a byte-compiled function defined in gnus-search.el.gz.

Signature

(gnus-search-parse-query STRING)

Documentation

Turn STRING into an s-expression based query.

The resulting query structure is passed to the various search backends, each of which adapts it as needed.

The search "language" is essentially a series of key:value expressions. Key is most often a mail header, but there are other keys. Value is a string, quoted if it contains spaces. Key and value are separated by a colon, no space. Expressions are implicitly ANDed; the "or" keyword can be used to OR. "not" will negate the following expression, or keys can be prefixed with a "-". The "near" operator will work for engines that understand it; other engines will convert it to
"or". Parenthetical groups work as expected.

A key that matches the name of a mail header will search that header.

Search keys can be expanded with TAB during entry, or left abbreviated so long as they remain unambiguous, ie "f" will search the "from" header. "s" will raise an error.

Other keys:

"address" will search all sender and recipient headers.

"recipient" will search "To", "Cc", and "Bcc".

"before" will search messages sent before the specified
date (date specifications to come later). Date is exclusive.

"after" (or its synonym "since") will search messages sent
after the specified date. Date is inclusive.

"mark" will search messages that have some sort of mark.
Likely values include "flag", "seen", "read", "replied". It's also possible to use Gnus' internal marks, ie "mark:R" will be interpreted as mark:read.

"tag" will search tags -- right now that's translated to
"keyword" in IMAP, and left as "tag" for notmuch. At some
point this should also be used to search marks in the Gnus registry.

Other keys can be specified, provided that the search backends know how to interpret them.

External contact-management packages can push completion tables onto the list variable gnus-search-contact-tables, to provide auto-completion of contact names and addresses for keys like
"from" and "to".

Date values (any key in gnus-search-date-keys) can be provided in any format that parse-time-string can parse (note that this can produce weird results). Dates with missing bits will be interpreted as the most recent occurrence thereof (i.e. "march
03" is the most recent March 3rd). Lastly, relative
specifications such as 1d (one day ago) are understood. This also accepts w, m, and y. m is assumed to be 30 days.

This function will accept pretty much anything as input. Its only job is to parse the query into a sexp, and pass that on -- it is the job of the search backends to make sense of the structured query. Malformed, unusable or invalid queries will typically be silently ignored.

Source Code

;; Defined in /usr/src/emacs/lisp/gnus/gnus-search.el.gz
;;; Search language

;; This "language" was generalized from the original IMAP search query
;; parsing routine.

(defun gnus-search-parse-query (string)
  "Turn STRING into an s-expression based query.
The resulting query structure is passed to the various search
backends, each of which adapts it as needed.

The search \"language\" is essentially a series of key:value
expressions.  Key is most often a mail header, but there are
other keys.  Value is a string, quoted if it contains spaces.
Key and value are separated by a colon, no space.  Expressions
are implicitly ANDed; the \"or\" keyword can be used to
OR.  \"not\" will negate the following expression, or keys can be
prefixed with a \"-\".  The \"near\" operator will work for
engines that understand it; other engines will convert it to
\"or\".  Parenthetical groups work as expected.

A key that matches the name of a mail header will search that
header.

Search keys can be expanded with TAB during entry, or left
abbreviated so long as they remain unambiguous, ie \"f\" will
search the \"from\" header.  \"s\" will raise an error.

Other keys:

\"address\" will search all sender and recipient headers.

\"recipient\" will search \"To\", \"Cc\", and \"Bcc\".

\"before\" will search messages sent before the specified
date (date specifications to come later).  Date is exclusive.

\"after\" (or its synonym \"since\") will search messages sent
after the specified date.  Date is inclusive.

\"mark\" will search messages that have some sort of mark.
Likely values include \"flag\", \"seen\", \"read\", \"replied\".
It's also possible to use Gnus' internal marks, ie \"mark:R\"
will be interpreted as mark:read.

\"tag\" will search tags -- right now that's translated to
\"keyword\" in IMAP, and left as \"tag\" for notmuch.  At some
point this should also be used to search marks in the Gnus
registry.

Other keys can be specified, provided that the search backends
know how to interpret them.

External contact-management packages can push completion tables
onto the list variable `gnus-search-contact-tables', to provide
auto-completion of contact names and addresses for keys like
\"from\" and \"to\".

Date values (any key in `gnus-search-date-keys') can be provided
in any format that `parse-time-string' can parse (note that this
can produce weird results).  Dates with missing bits will be
interpreted as the most recent occurrence thereof (i.e. \"march
03\" is the most recent March 3rd).  Lastly, relative
specifications such as 1d (one day ago) are understood.  This
also accepts w, m, and y.  m is assumed to be 30 days.

This function will accept pretty much anything as input.  Its
only job is to parse the query into a sexp, and pass that on --
it is the job of the search backends to make sense of the
structured query.  Malformed, unusable or invalid queries will
typically be silently ignored."
  (with-temp-buffer
    ;; Set up the parsing environment.
    (insert string)
    (goto-char (point-min))
    ;; Now, collect the output terms and return them.
    (let (out)
      (while (not (gnus-search-query-end-of-input))
	(push (gnus-search-query-next-expr) out))
      (reverse out))))