From: Kevin McCarthy Date: Sat, 28 Apr 2018 20:21:42 +0000 (-0700) Subject: Update pattern documentation. X-Git-Tag: mutt-1-10-rel~18 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=e4557546aeee21189a5fc8ecb66024f2485aab6d;p=mutt Update pattern documentation. Note that ~b, ~B, ~h, ~M, and ~X read the message in, and that this can be much slower. Change =b, =B, =h table rows to document just the IMAP behavior. The "=" simple string behavior is already covered below, and makes it less obvious whether "***)" should be added to those entries in the table. Break up the simple string and imap server-side matching explanation into two paragraphs. Add ~M to the list of patterns you can't use message scoring with. Add equivalent, if briefer, explanations to the muttrc.man page. --- diff --git a/doc/manual.xml.head b/doc/manual.xml.head index 1bff0d17..aa991dff 100644 --- a/doc/manual.xml.head +++ b/doc/manual.xml.head @@ -3904,18 +3904,19 @@ equivalent to push <function>. -The score commands adds value to -a message's score if pattern matches it. -pattern is a string in the format described in the -patterns section (note: For efficiency -reasons, patterns which scan information not available in the index, -such as ~b, ~B, ~h, -or ~X may not be used). value is -a positive or negative integer. A message's final score is the sum -total of all matching score entries. However, you -may optionally prefix value with an equal sign -(=) to cause evaluation to stop at a particular entry if -there is a match. Negative final scores are rounded up to 0. +The score commands adds value +to a message's score if pattern matches it. +pattern is a string in the format described in +the patterns section (note: For +efficiency reasons, patterns which scan information not available in +the index, such as ~b, ~B, +~h, ~M, or ~X +may not be used). value is a positive or +negative integer. A message's final score is the sum total of all +matching score entries. However, you may +optionally prefix value with an equal sign +(=) to cause evaluation to stop at a particular entry +if there is a match. Negative final scores are rounded up to 0. @@ -5176,10 +5177,10 @@ shows several ways to select messages. ~Aall messages -~b EXPRmessages which contain EXPR in the message body -=b STRINGmessages which contain STRING in the message body. If IMAP is enabled, searches for STRING on the server, rather than downloading each message and searching it locally. -~B EXPRmessages which contain EXPR in the whole message -=B STRINGmessages which contain STRING in the whole message. If IMAP is enabled, searches for STRING on the server, rather than downloading each message and searching it locally. +~b EXPRmessages which contain EXPR in the message body ***) +=b STRINGIf IMAP is enabled, like ~b but searches for STRING on the server, rather than downloading each message and searching it locally. +~B EXPRmessages which contain EXPR in the whole message ***) +=B STRINGIf IMAP is enabled, like ~B but searches for STRING on the server, rather than downloading each message and searching it locally. ~c EXPRmessages carbon-copied to EXPR %c GROUPmessages carbon-copied to any member of GROUP ~C EXPRmessages either to: or cc: EXPR @@ -5194,8 +5195,8 @@ shows several ways to select messages. %f GROUPmessages originating from any member of GROUP ~gcryptographically signed messages ~Gcryptographically encrypted messages -~h EXPRmessages which contain EXPR in the message header -=h STRINGmessages which contain STRING in the message header. If IMAP is enabled, searches for STRING on the server, rather than downloading each message and searching it locally; STRING must be of the form header: substring (see below). +~h EXPRmessages which contain EXPR in the message header ***) +=h STRINGIf IMAP is enabled, like ~h but searches for STRING on the server, rather than downloading each message and searching it locally; STRING must be of the form header: substring (see below). ~H EXPRmessages with a spam attribute matching EXPR ~i EXPRmessages which match EXPR in the Message-ID field ~kmessages which contain PGP key material @@ -5203,7 +5204,7 @@ shows several ways to select messages. %L GROUPmessage either originated or received by any member of GROUP ~lmessages addressed to a known mailing list ~m [MIN]-[MAX]messages in the range MIN to MAX *) -~M EXPRmessages which contain a mime Content-Type matching EXPR +~M EXPRmessages which contain a mime Content-Type matching EXPR ***) ~n [MIN]-[MAX]messages with a score in the range MIN to MAX *) ~Nnew messages ~Oold messages @@ -5221,7 +5222,7 @@ shows several ways to select messages. ~vmessages part of a collapsed thread. ~Vcryptographically verified messages ~x EXPRmessages which contain EXPR in the References or In-Reply-To field -~X [MIN]-[MAX]messages with MIN to MAX attachments *) +~X [MIN]-[MAX]messages with MIN to MAX attachments *) ***) ~y EXPRmessages which contain EXPR in the X-Label field ~z [MIN]-[MAX]messages with a size in the range MIN to MAX *) **) ~=duplicated messages (see $duplicate_threads) @@ -5256,24 +5257,40 @@ Where EXPR is a regular expression + +***) These patterns read each message in, and can therefore be much +slower. Over IMAP this will entail downloading each message. They +can not be used for message +scoring, and it is recommended to avoid using them for index +coloring. + + Special attention has to be payed when using regular expressions inside of patterns. Specifically, Mutt's parser for these patterns will strip one level of backslash (\), which is normally used for quoting. If it is your intention to use a backslash in the regular expression, you will need to use two backslashes instead -(\\). You can force Mutt to treat +(\\). + + + +You can force Mutt to treat EXPR as a simple string instead of a regular expression by using = instead of ~ in the pattern name. For example, =b *.* will find all messages that contain the literal string *.*. Simple string matches are less -powerful than regular expressions but can be considerably faster. This -is especially true for IMAP folders, because string matches can be -performed on the server instead of by fetching every message. IMAP -treats =h specially: it must be of the form -header: substring and will not partially match header -names. The substring part may be omitted if you simply wish to find -messages containing a particular header without regard to its value. +powerful than regular expressions but can be considerably faster. + + + +For IMAP folders, string matches =b, +=B, and =h will be performed on +the server instead of by fetching every message. IMAP treats +=h specially: it must be of the form header: +substring and will not partially match header names. The +substring part may be omitted if you simply wish to find messages +containing a particular header without regard to its value. diff --git a/doc/muttrc.man.head b/doc/muttrc.man.head index f73e5cf2..92b40935 100644 --- a/doc/muttrc.man.head +++ b/doc/muttrc.man.head @@ -504,11 +504,14 @@ all messages messages which contain \fIEXPR\fP in the message body. .TP =b \fISTRING\fP -messages which contain \fISTRING\fP in the message body. If IMAP is enabled, searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally. +If IMAP is enabled, like ~b but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally. .TP ~B \fIEXPR\fP messages which contain \fIEXPR\fP in the whole message. .TP +=B \fISTRING\fP +If IMAP is enabled, like ~B but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally. +.TP ~c \fIEXPR\fP messages carbon-copied to \fIEXPR\fP .TP @@ -554,6 +557,9 @@ PGP encrypted messages ~h \fIEXPR\fP messages which contain \fIEXPR\fP in the message header .TP +=h \fISTRING\fP +If IMAP is enabled, like ~h but searches for \fISTRING\fP on the server, rather than downloading each message and searching it locally. \fISTRING\fP must be of the form \(lqheader: substring\(rq +.TP ~H \fIEXPR\fP messages with spam tags matching \fIEXPR\fP .TP @@ -663,6 +669,12 @@ specify ranges in the forms \fB<\fP\fIMAX\fP, \fB>\fP\fIMIN\fP, .PP With the \fB~z\fP operator, the suffixes \(lqK\(rq and \(lqM\(rq are allowed to specify kilobyte and megabyte respectively. +.PP +The \fB~b\fP, \fB~B\fP, \fB~h\fP, \fB~M\fP, and \fB~X\fP operators +require reading each message in, which can be much slower. +.PP +You can force Mutt to treat \fIEXPR\fP as a simple string instead of a +regular expression by using = instead of ~ in the pattern name. .SS Matching dates .PP The \fB~d\fP and \fB~r\fP operators are used to match date ranges,