GSP/GSP-Agent-Windows
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
GSP-Agent-Windows/OGP64/usr/share/doc/mutt/advancedusage.html

1338 lines
No EOL
113 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 4. Advanced Usage</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="The Mutt E-Mail Client" /><link rel="up" href="index.html" title="The Mutt E-Mail Client" /><link rel="prev" href="configuration.html" title="Chapter 3. Configuration" /><link rel="next" href="mimesupport.html" title="Chapter 5. Mutt's MIME Support" /><style xmlns="" type="text/css">
body { margin-left:2%; margin-right:2%; font-family:serif; }
.toc, .list-of-tables, .list-of-examples { font-family:sans-serif; }
h1, h2, h3, h4, h5, h6 { font-family:sans-serif; }
p { text-align:justify; }
div.table p.title, div.example p.title { font-size:smaller; font-family:sans-serif; }
.email, .email a { font-family:monospace; }
div.table-contents table, div.informaltable table { border-collapse:collapse; border:1px solid #c0c0c0; }
div.table-contents table td, div.informaltable td, div.table-contents table th, div.informaltable table th { padding:5px; text-align:left; }
div.table-contents table th, div.informaltable table th {
font-family:sans-serif;
background:#d0d0d0;
font-weight:normal;
vertical-align:top;
}
div.cmdsynopsis { border-left:1px solid #707070; padding-left:5px; }
li div.cmdsynopsis { border-left:none; padding-left:0px; }
pre.screen, div.note { background:#f0f0f0; border:1px solid #c0c0c0; padding:5px; margin-left:2%; margin-right:2%; }
div.example p.title { margin-left:2%; }
div.note h3 { font-size:small; font-style:italic; font-variant: small-caps; }
div.note h3:after { content: ":" }
div.note { margin-bottom: 5px; }
.command { font-family: monospace; font-weight: normal; }
.command strong { font-weight: normal; }
tr { vertical-align: top; }
.comment { color:#707070; }
</style></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 4. Advanced Usage</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="configuration.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="mimesupport.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="advancedusage"></a>Chapter 4. Advanced Usage</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="advancedusage.html#charset-handling">1. Character Set Handling</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#regexp">2. Regular Expressions</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#patterns">3. Patterns: Searching, Limiting and Tagging</a></span></dt><dd><dl><dt><span class="sect2"><a href="advancedusage.html#patterns-modifier">3.1. Pattern Modifier</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#simple-searches">3.2. Simple Searches</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#complex-patterns">3.3. Nesting and Boolean Operators</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#date-patterns">3.4. Searching by Date</a></span></dt></dl></dd><dt><span class="sect1"><a href="advancedusage.html#markmsg">4. Marking Messages</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#tags">5. Using Tags</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#hooks">6. Using Hooks</a></span></dt><dd><dl><dt><span class="sect2"><a href="advancedusage.html#pattern-hook">6.1. Message Matching in Hooks</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#mailbox-hook">6.2. Mailbox Matching in Hooks</a></span></dt></dl></dd><dt><span class="sect1"><a href="advancedusage.html#setenv">7. Managing the Environment</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#query">8. External Address Queries</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#mailbox-formats">9. Mailbox Formats</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#shortcuts">10. Mailbox Shortcuts</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#using-lists">11. Handling Mailing Lists</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#display-munging">12. Display Munging</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#new-mail">13. New Mail Detection</a></span></dt><dd><dl><dt><span class="sect2"><a href="advancedusage.html#new-mail-formats">13.1. How New Mail Detection Works</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#new-mail-polling">13.2. Polling For New Mail</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#new-mail-monitoring">13.3. Monitoring New Mail</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#calc-mailbox-counts">13.4. Calculating Mailbox Message Counts</a></span></dt></dl></dd><dt><span class="sect1"><a href="advancedusage.html#editing-threads">14. Editing Threads</a></span></dt><dd><dl><dt><span class="sect2"><a href="advancedusage.html#link-threads">14.1. Linking Threads</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#break-threads">14.2. Breaking Threads</a></span></dt></dl></dd><dt><span class="sect1"><a href="advancedusage.html#dsn">15. Delivery Status Notification (DSN) Support</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#urlview">16. Start a WWW Browser on URLs</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#echo">17. Echoing Text</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#compose-flow">18. Message Composition Flow</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#batch-compose-flow">19. Batch Composition Flow</a></span></dt><dt><span class="sect1"><a href="advancedusage.html#muttlisp">20. Using MuttLisp (EXPERIMENTAL)</a></span></dt><dd><dl><dt><span class="sect2"><a href="advancedusage.html#run">20.1. Running a command generated by MuttLisp</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#muttlisp-interpolate">20.2. Interpolating MuttLisp in a Command Argument</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#muttlisp-syntax">20.3. MuttLisp Syntax</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#muttlisp-funcs">20.4. MuttLisp Functions</a></span></dt><dt><span class="sect2"><a href="advancedusage.html#muttlisp-examples">20.5. Examples</a></span></dt></dl></dd><dt><span class="sect1"><a href="advancedusage.html#misc-topics">21. Miscellany</a></span></dt></dl></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="charset-handling"></a>1. Character Set Handling</h2></div></div></div><p>
A <span class="quote">“<span class="quote">character set</span>”</span> is basically a mapping between bytes and
glyphs and implies a certain character encoding scheme. For example, for
the ISO 8859 family of character sets, an encoding of 8bit per character
is used. For the Unicode character set, different character encodings
may be used, UTF-8 being the most popular. In UTF-8, a character is
represented using a variable number of bytes ranging from 1 to 4.
</p><p>
Since Mutt is a command-line tool run from a shell, and delegates
certain tasks to external tools (such as an editor for composing/editing
messages), all of these tools need to agree on a character set and
encoding. There exists no way to reliably deduce the character set a
plain text file has. Interoperability is gained by the use of
well-defined environment variables. The full set can be printed by
issuing <code class="literal">locale</code> on the command line.
</p><p>
Upon startup, Mutt determines the character set on its own using
routines that inspect locale-specific environment variables. Therefore,
it is generally not necessary to set the <code class="literal">$charset</code>
variable in Mutt. It may even be counter-productive as Mutt uses system
and library functions that derive the character set themselves and on
which Mutt has no influence. It's safest to let Mutt work out the locale
setup itself.
</p><p>
If you happen to work with several character sets on a regular basis,
it's highly advisable to use Unicode and an UTF-8 locale. Unicode can
represent nearly all characters in a message at the same time. When not
using a Unicode locale, it may happen that you receive messages with
characters not representable in your locale. When displaying such a
message, or replying to or forwarding it, information may get lost
possibly rendering the message unusable (not only for you but also for
the recipient, this breakage is not reversible as lost information
cannot be guessed).
</p><p>
A Unicode locale makes all conversions superfluous which eliminates the
risk of conversion errors. It also eliminates potentially wrong
expectations about the character set between Mutt and external programs.
</p><p>
The terminal emulator used also must be properly configured for the
current locale. Terminal emulators usually do <span class="emphasis"><em>not</em></span>
derive the locale from environment variables, they need to be configured
separately. If the terminal is incorrectly configured, Mutt may display
random and unexpected characters (question marks, octal codes, or just
random glyphs), format strings may not work as expected, you may not be
abled to enter non-ascii characters, and possible more. Data is always
represented using bytes and so a correct setup is very important as to
the machine, all character sets <span class="quote">“<span class="quote">look</span>”</span> the same.
</p><p>
Warning: A mismatch between what system and library functions think the
locale is and what Mutt was told what the locale is may make it behave
badly with non-ascii input: it will fail at seemingly random places.
This warning is to be taken seriously since not only local mail handling
may suffer: sent messages may carry wrong character set information the
<span class="emphasis"><em>receiver</em></span> has too deal with. The need to set
<code class="literal">$charset</code> directly in most cases points at terminal
and environment variable setup problems, not Mutt problems.
</p><p>
A list of officially assigned and known character sets can be found at
<a class="ulink" href="http://www.iana.org/assignments/character-sets" target="_top">IANA</a>,
a list of locally supported locales can be obtained by running
<code class="literal">locale -a</code>.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="regexp"></a>2. Regular Expressions</h2></div></div></div><p>
All string patterns in Mutt including those in more complex <a class="link" href="advancedusage.html#patterns" title="3. Patterns: Searching, Limiting and Tagging">patterns</a> must be specified using regular
expressions (regexp) in the <span class="quote">“<span class="quote">POSIX extended</span>”</span> syntax (which
is more or less the syntax used by egrep and GNU awk). For your
convenience, we have included below a brief description of this syntax.
</p><p>
The search is case sensitive if the pattern contains at least one upper
case letter, and case insensitive otherwise.
</p><div class="note"><h3 class="title">Note</h3><p>
<span class="quote">“<span class="quote">\</span>”</span> must be quoted if used for a regular expression in an
initialization command: <span class="quote">“<span class="quote">\\</span>”</span>.
</p></div><p>
A regular expression is a pattern that describes a set of strings.
Regular expressions are constructed analogously to arithmetic
expressions, by using various operators to combine smaller expressions.
</p><div class="note"><h3 class="title">Note</h3><p>
The regular expression can be enclosed/delimited by either " or ' which
is useful if the regular expression includes a white-space character.
See <a class="xref" href="configuration.html#muttrc-syntax" title="3. Syntax of Initialization Files">Syntax of Initialization Files</a> for more information on " and '
delimiter processing. To match a literal " or ' you must preface it
with \ (backslash).
</p></div><p>
The fundamental building blocks are the regular expressions that match a
single character. Most characters, including all letters and digits,
are regular expressions that match themselves. Any metacharacter with
special meaning may be quoted by preceding it with a backslash.
</p><p>
The period <span class="quote">“<span class="quote">.</span>”</span> matches any single character. The caret
<span class="quote">“<span class="quote">^</span>”</span> and the dollar sign <span class="quote">“<span class="quote">$</span>”</span> are metacharacters
that respectively match the empty string at the beginning and end of a
line.
</p><p>
A list of characters enclosed by <span class="quote">“<span class="quote">[</span>”</span> and <span class="quote">“<span class="quote">]</span>”</span>
matches any single character in that list; if the first character of the
list is a caret <span class="quote">“<span class="quote">^</span>”</span> then it matches any character
<span class="emphasis"><em>not</em></span> in the list. For example, the regular
expression <span class="emphasis"><em>[0123456789]</em></span> matches any single digit.
A range of ASCII characters may be specified by giving the first and
last characters, separated by a hyphen <span class="quote">“<span class="quote">-</span>”</span>. Most
metacharacters lose their special meaning inside lists. To include a
literal <span class="quote">“<span class="quote">]</span>”</span> place it first in the list. Similarly, to
include a literal <span class="quote">“<span class="quote">^</span>”</span> place it anywhere but first.
Finally, to include a literal hyphen <span class="quote">“<span class="quote">-</span>”</span> place it last.
</p><p>
Certain named classes of characters are predefined. Character classes
consist of <span class="quote">“<span class="quote">[:</span>”</span>, a keyword denoting the class, and
<span class="quote">“<span class="quote">:]</span>”</span>. The following classes are defined by the POSIX
standard in
<a class="xref" href="advancedusage.html#posix-regex-char-classes" title="Table 4.1. POSIX regular expression character classes">Table 4.1, “POSIX regular expression character classes”</a>
</p><div class="table"><a id="posix-regex-char-classes"></a><p class="title"><strong>Table 4.1. POSIX regular expression character classes</strong></p><div class="table-contents"><table class="table" summary="POSIX regular expression character classes" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Character class</th><th>Description</th></tr></thead><tbody><tr><td>[:alnum:]</td><td>Alphanumeric characters</td></tr><tr><td>[:alpha:]</td><td>Alphabetic characters</td></tr><tr><td>[:blank:]</td><td>Space or tab characters</td></tr><tr><td>[:cntrl:]</td><td>Control characters</td></tr><tr><td>[:digit:]</td><td>Numeric characters</td></tr><tr><td>[:graph:]</td><td>Characters that are both printable and visible. (A space is printable, but not visible, while an <span class="quote">“<span class="quote">a</span>”</span> is both)</td></tr><tr><td>[:lower:]</td><td>Lower-case alphabetic characters</td></tr><tr><td>[:print:]</td><td>Printable characters (characters that are not control characters)</td></tr><tr><td>[:punct:]</td><td>Punctuation characters (characters that are not letter, digits, control characters, or space characters)</td></tr><tr><td>[:space:]</td><td>Space characters (such as space, tab and formfeed, to name a few)</td></tr><tr><td>[:upper:]</td><td>Upper-case alphabetic characters</td></tr><tr><td>[:xdigit:]</td><td>Characters that are hexadecimal digits</td></tr></tbody></table></div></div><br class="table-break" /><p>
A character class is only valid in a regular expression inside the
brackets of a character list.
</p><div class="note"><h3 class="title">Note</h3><p>
Note that the brackets in these class names are part of the symbolic
names, and must be included in addition to the brackets delimiting the
bracket list. For example, <span class="emphasis"><em>[[:digit:]]</em></span> is
equivalent to <span class="emphasis"><em>[0-9]</em></span>.
</p></div><p>
Two additional special sequences can appear in character lists. These
apply to non-ASCII character sets, which can have single symbols (called
collating elements) that are represented with more than one character,
as well as several characters that are equivalent for collating or
sorting purposes:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Collating Symbols</span></dt><dd><p>
A collating symbol is a multi-character collating element enclosed in
<span class="quote">“<span class="quote">[.</span>”</span> and <span class="quote">“<span class="quote">.]</span>”</span>. For example, if
<span class="quote">“<span class="quote">ch</span>”</span> is a collating element, then
<span class="emphasis"><em>[[.ch.]]</em></span> is a regexp that matches this collating
element, while <span class="emphasis"><em>[ch]</em></span> is a regexp that matches either
<span class="quote">“<span class="quote">c</span>”</span> or <span class="quote">“<span class="quote">h</span>”</span>.
</p></dd><dt><span class="term">Equivalence Classes</span></dt><dd><p>
An equivalence class is a locale-specific name for a list of characters
that are equivalent. The name is enclosed in <span class="quote">“<span class="quote">[=</span>”</span> and
<span class="quote">“<span class="quote">=]</span>”</span>. For example, the name <span class="quote">“<span class="quote">e</span>”</span> might be used
to represent all of <span class="quote">“<span class="quote">e</span>”</span> with grave
(<span class="quote">“<span class="quote">è</span>”</span>), <span class="quote">“<span class="quote">e</span>”</span> with acute
(<span class="quote">“<span class="quote">é</span>”</span>) and <span class="quote">“<span class="quote">e</span>”</span>. In this case,
<span class="emphasis"><em>[[=e=]]</em></span> is a regexp that matches any of:
<span class="quote">“<span class="quote">e</span>”</span> with grave (<span class="quote">“<span class="quote">è</span>”</span>), <span class="quote">“<span class="quote">e</span>”</span>
with acute (<span class="quote">“<span class="quote">é</span>”</span>) and <span class="quote">“<span class="quote">e</span>”</span>.
</p></dd></dl></div><p>
A regular expression matching a single character may be followed by one
of several repetition operators described in <a class="xref" href="advancedusage.html#regex-repeat" title="Table 4.2. Regular expression repetition operators">Table 4.2, “Regular expression repetition operators”</a>.
</p><div class="table"><a id="regex-repeat"></a><p class="title"><strong>Table 4.2. Regular expression repetition operators</strong></p><div class="table-contents"><table class="table" summary="Regular expression repetition operators" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Operator</th><th>Description</th></tr></thead><tbody><tr><td>?</td><td>The preceding item is optional and matched at most once</td></tr><tr><td>*</td><td>The preceding item will be matched zero or more times</td></tr><tr><td>+</td><td>The preceding item will be matched one or more times</td></tr><tr><td>{n}</td><td>The preceding item is matched exactly <span class="emphasis"><em>n</em></span> times</td></tr><tr><td>{n,}</td><td>The preceding item is matched <span class="emphasis"><em>n</em></span> or more times</td></tr><tr><td>{,m}</td><td>The preceding item is matched at most <span class="emphasis"><em>m</em></span> times</td></tr><tr><td>{n,m}</td><td>The preceding item is matched at least <span class="emphasis"><em>n</em></span> times, but no more than <span class="emphasis"><em>m</em></span> times</td></tr></tbody></table></div></div><br class="table-break" /><p>
Two regular expressions may be concatenated; the resulting regular
expression matches any string formed by concatenating two substrings
that respectively match the concatenated subexpressions.
</p><p>
Two regular expressions may be joined by the infix operator
<span class="quote">“<span class="quote">|</span>”</span>; the resulting regular expression matches any string
matching either subexpression.
</p><p>
Repetition takes precedence over concatenation, which in turn takes
precedence over alternation. A whole subexpression may be enclosed in
parentheses to override these precedence rules.
</p><div class="note"><h3 class="title">Note</h3><p>
If you compile Mutt with the included regular expression engine, the
following operators may also be used in regular expressions as described
in <a class="xref" href="advancedusage.html#regex-gnu-ext" title="Table 4.3. GNU regular expression extensions">Table 4.3, “GNU regular expression extensions”</a>.
</p></div><div class="table"><a id="regex-gnu-ext"></a><p class="title"><strong>Table 4.3. GNU regular expression extensions</strong></p><div class="table-contents"><table class="table" summary="GNU regular expression extensions" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Expression</th><th>Description</th></tr></thead><tbody><tr><td>\\y</td><td>Matches the empty string at either the beginning or the end of a word</td></tr><tr><td>\\B</td><td>Matches the empty string within a word</td></tr><tr><td>\\&lt;</td><td>Matches the empty string at the beginning of a word</td></tr><tr><td>\\&gt;</td><td>Matches the empty string at the end of a word</td></tr><tr><td>\\w</td><td>Matches any word-constituent character (letter, digit, or underscore)</td></tr><tr><td>\\W</td><td>Matches any character that is not word-constituent</td></tr><tr><td>\\`</td><td>Matches the empty string at the beginning of a buffer (string)</td></tr><tr><td>\\'</td><td>Matches the empty string at the end of a buffer</td></tr></tbody></table></div></div><br class="table-break" /><p>
Please note however that these operators are not defined by POSIX, so
they may or may not be available in stock libraries on various systems.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="patterns"></a>3. Patterns: Searching, Limiting and Tagging</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="patterns-modifier"></a>3.1. Pattern Modifier</h3></div></div></div><p>
Many of Mutt's commands allow you to specify a pattern to match
(<code class="literal">limit</code>, <code class="literal">tag-pattern</code>,
<code class="literal">delete-pattern</code>, etc.). <a class="xref" href="advancedusage.html#tab-patterns" title="Table 4.4. Pattern modifiers">Table 4.4, “Pattern modifiers”</a>
shows several ways to select messages.
</p><div class="table"><a id="tab-patterns"></a><p class="title"><strong>Table 4.4. Pattern modifiers</strong></p><div class="table-contents"><table class="table" summary="Pattern modifiers" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Pattern modifier</th><th>Description</th></tr></thead><tbody><tr><td>~A</td><td>all messages</td></tr><tr><td>~b <span class="emphasis"><em>EXPR</em></span></td><td>messages which contain <span class="emphasis"><em>EXPR</em></span> in the message body ***)</td></tr><tr><td>=b <span class="emphasis"><em>STRING</em></span></td><td>If IMAP is enabled, like ~b but searches for <span class="emphasis"><em>STRING</em></span> on the server, rather than downloading each message and searching it locally.</td></tr><tr><td>~B <span class="emphasis"><em>EXPR</em></span></td><td>messages which contain <span class="emphasis"><em>EXPR</em></span> in the whole message ***)</td></tr><tr><td>=B <span class="emphasis"><em>STRING</em></span></td><td>If IMAP is enabled, like ~B but searches for <span class="emphasis"><em>STRING</em></span> on the server, rather than downloading each message and searching it locally.</td></tr><tr><td>~c <span class="emphasis"><em>EXPR</em></span></td><td>messages carbon-copied to <span class="emphasis"><em>EXPR</em></span></td></tr><tr><td>%c <span class="emphasis"><em>GROUP</em></span></td><td>messages carbon-copied to any member of <span class="emphasis"><em>GROUP</em></span></td></tr><tr><td>~C <span class="emphasis"><em>EXPR</em></span></td><td>messages either to: or cc: <span class="emphasis"><em>EXPR</em></span></td></tr><tr><td>%C <span class="emphasis"><em>GROUP</em></span></td><td>messages either to: or cc: to any member of <span class="emphasis"><em>GROUP</em></span></td></tr><tr><td>~d [<span class="emphasis"><em>MIN</em></span>]-[<span class="emphasis"><em>MAX</em></span>]</td><td>messages with <span class="quote">“<span class="quote">date-sent</span>”</span> in a Date range</td></tr><tr><td>~D</td><td>deleted messages</td></tr><tr><td>~e <span class="emphasis"><em>EXPR</em></span></td><td>messages which contains <span class="emphasis"><em>EXPR</em></span> in the <span class="quote">“<span class="quote">Sender</span>”</span> field</td></tr><tr><td>%e <span class="emphasis"><em>GROUP</em></span></td><td>messages which contain a member of <span class="emphasis"><em>GROUP</em></span> in the <span class="quote">“<span class="quote">Sender</span>”</span> field</td></tr><tr><td>~E</td><td>expired messages</td></tr><tr><td>~F</td><td>flagged messages</td></tr><tr><td>~f <span class="emphasis"><em>EXPR</em></span></td><td>messages originating from <span class="emphasis"><em>EXPR</em></span></td></tr><tr><td>%f <span class="emphasis"><em>GROUP</em></span></td><td>messages originating from any member of <span class="emphasis"><em>GROUP</em></span></td></tr><tr><td>~g</td><td>cryptographically signed messages</td></tr><tr><td>~G</td><td>cryptographically encrypted messages</td></tr><tr><td>~h <span class="emphasis"><em>EXPR</em></span></td><td>messages which contain <span class="emphasis"><em>EXPR</em></span> in the message header ***)</td></tr><tr><td>=h <span class="emphasis"><em>STRING</em></span></td><td>If IMAP is enabled, like ~h but searches for <span class="emphasis"><em>STRING</em></span> on the server, rather than downloading each message and searching it locally; <span class="emphasis"><em>STRING</em></span> must be of the form <span class="quote">“<span class="quote">header: substring</span>”</span> (see below).</td></tr><tr><td>~H <span class="emphasis"><em>EXPR</em></span></td><td>messages with a spam attribute matching <span class="emphasis"><em>EXPR</em></span></td></tr><tr><td>~i <span class="emphasis"><em>EXPR</em></span></td><td>messages which match <span class="emphasis"><em>EXPR</em></span> in the <span class="quote">“<span class="quote">Message-ID</span>”</span> field</td></tr><tr><td>~k</td><td>messages which contain PGP key material</td></tr><tr><td>~L <span class="emphasis"><em>EXPR</em></span></td><td>messages either originated or received by <span class="emphasis"><em>EXPR</em></span></td></tr><tr><td>%L <span class="emphasis"><em>GROUP</em></span></td><td>message either originated or received by any member of <span class="emphasis"><em>GROUP</em></span></td></tr><tr><td>~l</td><td>messages addressed to a known mailing list</td></tr><tr><td>~m [<span class="emphasis"><em>MIN</em></span>]-[<span class="emphasis"><em>MAX</em></span>]</td><td>messages in the range <span class="emphasis"><em>MIN</em></span> to <span class="emphasis"><em>MAX</em></span> *)</td></tr><tr><td>~M <span class="emphasis"><em>EXPR</em></span></td><td>messages which contain a mime Content-Type matching <span class="emphasis"><em>EXPR</em></span> ***)</td></tr><tr><td>~n [<span class="emphasis"><em>MIN</em></span>]-[<span class="emphasis"><em>MAX</em></span>]</td><td>messages with a score in the range <span class="emphasis"><em>MIN</em></span> to <span class="emphasis"><em>MAX</em></span> *)</td></tr><tr><td>~N</td><td>new messages</td></tr><tr><td>~O</td><td>old messages</td></tr><tr><td>~p</td><td>messages addressed to you (consults <a class="link" href="reference.html#from" title="3.109. from">$from</a>, <span class="command"><strong>alternates</strong></span>, and local account/hostname information)</td></tr><tr><td>~P</td><td>messages from you (consults <a class="link" href="reference.html#from" title="3.109. from">$from</a>, <span class="command"><strong>alternates</strong></span>, and local account/hostname information)</td></tr><tr><td>~Q</td><td>messages which have been replied to</td></tr><tr><td>~r [<span class="emphasis"><em>MIN</em></span>]-[<span class="emphasis"><em>MAX</em></span>]</td><td>messages with <span class="quote">“<span class="quote">date-received</span>”</span> in a Date range</td></tr><tr><td>~R</td><td>read messages</td></tr><tr><td>~s <span class="emphasis"><em>EXPR</em></span></td><td>messages having <span class="emphasis"><em>EXPR</em></span> in the <span class="quote">“<span class="quote">Subject</span>”</span> field.</td></tr><tr><td>~S</td><td>superseded messages</td></tr><tr><td>~t <span class="emphasis"><em>EXPR</em></span></td><td>messages addressed to <span class="emphasis"><em>EXPR</em></span></td></tr><tr><td>~T</td><td>tagged messages</td></tr><tr><td>~u</td><td>messages addressed to a subscribed mailing list</td></tr><tr><td>~U</td><td>unread messages</td></tr><tr><td>~v</td><td>messages part of a collapsed thread.</td></tr><tr><td>~V</td><td>cryptographically verified messages</td></tr><tr><td>~x <span class="emphasis"><em>EXPR</em></span></td><td>messages which contain <span class="emphasis"><em>EXPR</em></span> in the <span class="quote">“<span class="quote">References</span>”</span> or <span class="quote">“<span class="quote">In-Reply-To</span>”</span> field</td></tr><tr><td>~X [<span class="emphasis"><em>MIN</em></span>]-[<span class="emphasis"><em>MAX</em></span>]</td><td>messages with <span class="emphasis"><em>MIN</em></span> to <span class="emphasis"><em>MAX</em></span> attachments *) ***)</td></tr><tr><td>~y <span class="emphasis"><em>EXPR</em></span></td><td>messages which contain <span class="emphasis"><em>EXPR</em></span> in the <span class="quote">“<span class="quote">X-Label</span>”</span> field</td></tr><tr><td>~z [<span class="emphasis"><em>MIN</em></span>]-[<span class="emphasis"><em>MAX</em></span>]</td><td>messages with a size in the range <span class="emphasis"><em>MIN</em></span> to <span class="emphasis"><em>MAX</em></span> *) **)</td></tr><tr><td>~=</td><td>duplicated messages (see <a class="link" href="reference.html#duplicate-threads" title="3.83. duplicate_threads">$duplicate_threads</a>)</td></tr><tr><td>~$</td><td>unreferenced messages (requires threaded view)</td></tr><tr><td>~(<span class="emphasis"><em>PATTERN</em></span>)</td><td>messages in threads
containing messages matching <span class="emphasis"><em>PATTERN</em></span>, e.g. all
threads containing messages from you: ~(~P)</td></tr><tr><td>~&lt;(<span class="emphasis"><em>PATTERN</em></span>)</td><td>messages
whose immediate parent matches <span class="emphasis"><em>PATTERN</em></span>,
e.g. replies to your messages: ~&lt;(~P)</td></tr><tr><td>~&gt;(<span class="emphasis"><em>PATTERN</em></span>)</td><td>messages
having an immediate child matching <span class="emphasis"><em>PATTERN</em></span>,
e.g. messages you replied to: ~&gt;(~P)</td></tr></tbody></table></div></div><br class="table-break" /><p>
Where <span class="emphasis"><em>EXPR</em></span> is a <a class="link" href="advancedusage.html#regexp" title="2. Regular Expressions">regular expression</a>, and <span class="emphasis"><em>GROUP</em></span> is an
<a class="link" href="configuration.html#addrgroup" title="4. Address Groups">address group</a>.
</p><p>
*) The forms <span class="quote">“<span class="quote">&lt;[<span class="emphasis"><em>MAX</em></span>]</span>”</span>,
<span class="quote">“<span class="quote">&gt;[<span class="emphasis"><em>MIN</em></span>]</span>”</span>,
<span class="quote">“<span class="quote">[<span class="emphasis"><em>MIN</em></span>]-</span>”</span> and
<span class="quote">“<span class="quote">-[<span class="emphasis"><em>MAX</em></span>]</span>”</span> are allowed, too.
</p><p>
**) The suffixes <span class="quote">“<span class="quote">K</span>”</span> and <span class="quote">“<span class="quote">M</span>”</span> are allowed to
specify kilobyte and megabyte respectively.
</p><p>
***) 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 <a class="link" href="configuration.html#score-command" title="27. Message Scoring">message
scoring</a>, and it is recommended to avoid using them for index
coloring.
</p><p>
Special attention has to be paid when using regular expressions inside
of patterns. Specifically, Mutt's parser for these patterns will strip
one level of backslash (<span class="quote">“<span class="quote">\</span>”</span>), 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
(<span class="quote">“<span class="quote">\\</span>”</span>).
</p><p>
You can force Mutt to treat
<span class="emphasis"><em>EXPR</em></span> as a simple string instead of a regular
expression by using = instead of ~ in the pattern name. For example,
<code class="literal">=b *.*</code> will find all messages that contain the
literal string <span class="quote">“<span class="quote">*.*</span>”</span>. Simple string matches are less
powerful than regular expressions but can be considerably faster.
</p><p>
For IMAP folders, string matches <code class="literal">=b</code>,
<code class="literal">=B</code>, and <code class="literal">=h</code> will be performed on
the server instead of by fetching every message. IMAP treats
<code class="literal">=h</code> specially: it must be of the form <span class="quote">“<span class="quote">header:
substring</span>”</span> 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.
</p><p>
Patterns matching lists of addresses (notably c, C, p, P and t) match if
there is at least one match in the whole list. If you want to make sure
that all elements of that list match, you need to prefix your pattern
with <span class="quote">“<span class="quote">^</span>”</span>. This example matches all mails which only has
recipients from Germany.
</p><div class="example"><a id="ex-recips"></a><p class="title"><strong>Example 4.1. Matching all addresses in address lists</strong></p><div class="example-contents"><pre class="screen">
^~C \.de$
</pre></div></div><br class="example-break" /><p>
You can restrict address pattern matching to aliases that you have
defined with the "@" modifier. This example matches messages whose
recipients are all from Germany, and who are known to your alias list.
</p><div class="example"><a id="ex-restrict-to-aliases"></a><p class="title"><strong>Example 4.2. Matching restricted to aliases</strong></p><div class="example-contents"><pre class="screen">
^@~C \.de$
</pre></div></div><br class="example-break" /><p>
To match any defined alias, use a regular expression that matches any
string. This example matches messages whose senders are known aliases.
</p><div class="example"><a id="ex-match-alias"></a><p class="title"><strong>Example 4.3. Matching any defined alias</strong></p><div class="example-contents"><pre class="screen">
@~f .
</pre></div></div><br class="example-break" /></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="simple-searches"></a>3.2. Simple Searches</h3></div></div></div><p>
Mutt supports two versions of so called <span class="quote">“<span class="quote">simple
searches</span>”</span>. These are issued if the query entered for searching,
limiting and similar operations does not seem to contain a valid pattern
modifier (i.e. it does not contain one of these characters:
<span class="quote">“<span class="quote">~</span>”</span>, <span class="quote">“<span class="quote">=</span>”</span> or <span class="quote">“<span class="quote">%</span>”</span>). If the query is
supposed to contain one of these special characters, they must be
escaped by prepending a backslash (<span class="quote">“<span class="quote">\</span>”</span>).
</p><p>
The first type is by checking whether the query string equals
a keyword case-insensitively from <a class="xref" href="advancedusage.html#tab-simplesearch-keywords" title="Table 4.5. Simple search keywords">Table 4.5, “Simple search keywords”</a>:
If that is the case, Mutt will use the shown pattern modifier instead.
If a keyword would conflict with your search keyword, you need to turn
it into a regular expression to avoid matching the keyword table. For
example, if you want to find all messages matching <span class="quote">“<span class="quote">flag</span>”</span>
(using <a class="link" href="reference.html#simple-search" title="3.324. simple_search">$simple_search</a>)
but don't want to match flagged messages, simply search for
<span class="quote">“<span class="quote"><code class="literal">[f]lag</code></span>”</span>.
</p><div class="table"><a id="tab-simplesearch-keywords"></a><p class="title"><strong>Table 4.5. Simple search keywords</strong></p><div class="table-contents"><table class="table" summary="Simple search keywords" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Keyword</th><th>Pattern modifier</th></tr></thead><tbody><tr><td>all</td><td>~A</td></tr><tr><td>.</td><td>~A</td></tr><tr><td>^</td><td>~A</td></tr><tr><td>del</td><td>~D</td></tr><tr><td>flag</td><td>~F</td></tr><tr><td>new</td><td>~N</td></tr><tr><td>old</td><td>~O</td></tr><tr><td>repl</td><td>~Q</td></tr><tr><td>read</td><td>~R</td></tr><tr><td>tag</td><td>~T</td></tr><tr><td>unread</td><td>~U</td></tr></tbody></table></div></div><br class="table-break" /><p>
The second type of simple search is to build a complex search pattern
using <a class="link" href="reference.html#simple-search" title="3.324. simple_search">$simple_search</a> as a
template. Mutt will insert your query properly quoted and search for the
composed complex query.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="complex-patterns"></a>3.3. Nesting and Boolean Operators</h3></div></div></div><p>
Logical AND is performed by specifying more than one criterion. For
example:
</p><pre class="screen">
~t mutt ~f elkins
</pre><p>
would select messages which contain the word <span class="quote">“<span class="quote">mutt</span>”</span> in the
list of recipients <span class="emphasis"><em>and</em></span> that have the word
<span class="quote">“<span class="quote">elkins</span>”</span> in the <span class="quote">“<span class="quote">From</span>”</span> header field.
</p><p>
Mutt also recognizes the following operators to create more complex
search patterns:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
! — logical NOT operator
</p></li><li class="listitem"><p>
| — logical OR operator
</p></li><li class="listitem"><p>
() — logical grouping operator
</p></li></ul></div><p>
Here is an example illustrating a complex search pattern. This pattern
will select all messages which do not contain <span class="quote">“<span class="quote">mutt</span>”</span> in the
<span class="quote">“<span class="quote">To</span>”</span> or <span class="quote">“<span class="quote">Cc</span>”</span> field and which are from
<span class="quote">“<span class="quote">elkins</span>”</span>.
</p><div class="example"><a id="ex-pattern-bool"></a><p class="title"><strong>Example 4.4. Using boolean operators in patterns</strong></p><div class="example-contents"><pre class="screen">
!(~t mutt|~c mutt) ~f elkins
</pre></div></div><br class="example-break" /><p>
Here is an example using white space in the regular expression (note the
<span class="quote">“<span class="quote">'</span>”</span> and <span class="quote">“<span class="quote">"</span>”</span> delimiters). For this to match,
the mail's subject must match the <span class="quote">“<span class="quote">^Junk +From +Me$</span>”</span> and it
must be from either <span class="quote">“<span class="quote">Jim +Somebody</span>”</span> or <span class="quote">“<span class="quote">Ed
+SomeoneElse</span>”</span>:
</p><pre class="screen">
'~s "^Junk +From +Me$" ~f ("Jim +Somebody"|"Ed +SomeoneElse")'
</pre><div class="note"><h3 class="title">Note</h3><p>
If a regular expression contains parenthesis, or a vertical bar ("|"),
you <span class="emphasis"><em>must</em></span> enclose the expression in double or single
quotes since those characters are also used to separate different parts
of Mutt's pattern language. For example: <code class="literal">~f
"me@(mutt\.org|cs\.hmc\.edu)"</code> Without the quotes, the
parenthesis wouldn't end. This would be separated to two OR'd patterns:
<span class="emphasis"><em>~f me@(mutt\.org</em></span> and
<span class="emphasis"><em>cs\.hmc\.edu)</em></span>. They are never what you want.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="date-patterns"></a>3.4. Searching by Date</h3></div></div></div><p>
Mutt supports two types of dates, <span class="emphasis"><em>absolute</em></span> and
<span class="emphasis"><em>relative</em></span>.
</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="date-absolute"></a>3.4.1. Absolute Dates</h4></div></div></div><p>
Dates <span class="emphasis"><em>must</em></span> be in DD/MM/YY format (month and year
are optional, defaulting to the current month and year) or YYYYMMDD. An
example of a valid range of dates is:
</p><pre class="screen">
Limit to messages matching: ~d 20/1/95-31/10
Limit to messages matching: ~d 19950120-19951031
</pre><p>
If you omit the minimum (first) date, and just specify
<span class="quote">“<span class="quote">-DD/MM/YY</span>”</span> or <span class="quote">“<span class="quote">-YYYYMMDD</span>”</span>, all messages
<span class="emphasis"><em>before</em></span> the given date will be selected. If you omit the
maximum (second) date, and specify <span class="quote">“<span class="quote">DD/MM/YY-</span>”</span>, all messages
<span class="emphasis"><em>after</em></span> the given date will be selected. If you
specify a single date with no dash (<span class="quote">“<span class="quote">-</span>”</span>), only messages
sent on the given date will be selected.
</p><p>
You can add error margins to absolute dates. An error margin is a sign
(+ or -), followed by a digit, followed by one of the units in <a class="xref" href="advancedusage.html#tab-date-units" title="Table 4.6. Date units">Table 4.6, “Date units”</a>. As a special case, you can replace the sign
by a <span class="quote">“<span class="quote">*</span>”</span> character, which is equivalent to giving identical
plus and minus error margins.
</p><div class="table"><a id="tab-date-units"></a><p class="title"><strong>Table 4.6. Date units</strong></p><div class="table-contents"><table class="table" summary="Date units" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Unit</th><th>Description</th></tr></thead><tbody><tr><td>y</td><td>Years</td></tr><tr><td>m</td><td>Months</td></tr><tr><td>w</td><td>Weeks</td></tr><tr><td>d</td><td>Days</td></tr></tbody></table></div></div><br class="table-break" /><p>
Example: To select any messages two weeks around January 15, 2001, you'd
use the following pattern:
</p><pre class="screen">
Limit to messages matching: ~d 15/1/2001*2w
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="dates-relative"></a>3.4.2. Relative Dates</h4></div></div></div><p>
This type of date is relative to the current date, and may be specified
as:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
&gt;<span class="emphasis"><em>offset</em></span> for messages older than
<span class="emphasis"><em>offset</em></span> units
</p></li><li class="listitem"><p>
&lt;<span class="emphasis"><em>offset</em></span> for messages newer than
<span class="emphasis"><em>offset</em></span> units
</p></li><li class="listitem"><p>
=<span class="emphasis"><em>offset</em></span> for messages exactly
<span class="emphasis"><em>offset</em></span> units old
</p></li></ul></div><p>
<span class="emphasis"><em>offset</em></span> is specified as a positive number with one
of the units from <a class="xref" href="advancedusage.html#tab-rel-date-units" title="Table 4.7. Relative date units">Table 4.7, “Relative date units”</a>.
</p><div class="table"><a id="tab-rel-date-units"></a><p class="title"><strong>Table 4.7. Relative date units</strong></p><div class="table-contents"><table class="table" summary="Relative date units" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Unit</th><th>Description</th></tr></thead><tbody><tr><td>y</td><td>Years</td></tr><tr><td>m</td><td>Months</td></tr><tr><td>w</td><td>Weeks</td></tr><tr><td>d</td><td>Days</td></tr><tr><td>H</td><td>Hours</td></tr><tr><td>M</td><td>Minutes</td></tr><tr><td>S</td><td>Seconds</td></tr></tbody></table></div></div><br class="table-break" /><p>
Example: to select messages less than 1 month old, you would use
</p><pre class="screen">
Limit to messages matching: ~d &lt;1m
</pre><div class="note"><h3 class="title">Note</h3><p>
All dates used when searching are relative to the
<span class="emphasis"><em>local</em></span> time zone, so unless you change the setting
of your <a class="link" href="reference.html#index-format" title="3.161. index_format">$index_format</a> to include a
<code class="literal">%[...]</code> format, these are <span class="emphasis"><em>not</em></span> the
dates shown in the main index.
</p></div></div></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="markmsg"></a>4. Marking Messages</h2></div></div></div><p>
There are times that it's useful to ask Mutt to "remember" which message
you're currently looking at, while you move elsewhere in your mailbox.
You can do this with the <span class="quote">“<span class="quote">mark-message</span>”</span> operator, which
is bound to the <span class="quote">“<span class="quote">~</span>”</span> key by default. Press this key to
enter an identifier for the marked message. When you want to return to
this message, press <span class="quote">“<span class="quote">'</span>”</span> and the name that you previously
entered.
</p><p>
(Message marking is really just a shortcut for defining a macro
that returns you to the current message by searching for its
Message-ID. You can choose a different prefix by setting the <a class="link" href="reference.html#mark-macro-prefix" title="3.174. mark_macro_prefix">$mark_macro_prefix</a> variable.)
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="tags"></a>5. Using Tags</h2></div></div></div><p>
Sometimes it is desirable to perform an operation on a group of messages
all at once rather than one at a time. An example might be to save
messages to a mailing list to a separate folder, or to delete all
messages with a given subject. To tag all messages matching a pattern,
use the <code class="literal">&lt;tag-pattern&gt;</code> function, which is bound
to <span class="quote">“<span class="quote">shift-T</span>”</span> by default. Or you can select individual
messages by hand using the <code class="literal">&lt;tag-message&gt;</code>
function, which is bound to <span class="quote">“<span class="quote">t</span>”</span> by default. See <a class="link" href="advancedusage.html#patterns" title="3. Patterns: Searching, Limiting and Tagging">patterns</a> for Mutt's pattern matching syntax.
</p><p>
Once you have tagged the desired messages, you can use the
<span class="quote">“<span class="quote">tag-prefix</span>”</span> operator, which is the <span class="quote">“<span class="quote">;</span>”</span>
(semicolon) key by default. When the <span class="quote">“<span class="quote">tag-prefix</span>”</span> operator
is used, the <span class="emphasis"><em>next</em></span> operation will be applied to all
tagged messages if that operation can be used in that manner. If the
<a class="link" href="reference.html#auto-tag" title="3.23. auto_tag">$auto_tag</a> variable is set, the next
operation applies to the tagged messages automatically, without
requiring the <span class="quote">“<span class="quote">tag-prefix</span>”</span>.
</p><p>
In <a class="link" href="configuration.html#macro" title="10. Keyboard Macros"><span class="command"><strong>macro</strong></span>s</a> or <a class="link" href="configuration.html#push" title="25. Adding Key Sequences to the Keyboard Buffer"><span class="command"><strong>push</strong></span></a> commands, you can use the
<code class="literal">&lt;tag-prefix-cond&gt;</code> operator. If there are no
tagged messages, Mutt will <span class="quote">“<span class="quote">eat</span>”</span> the rest of the macro to
abort it's execution. Mutt will stop <span class="quote">“<span class="quote">eating</span>”</span> the macro
when it encounters the <code class="literal">&lt;end-cond&gt;</code> operator;
after this operator the rest of the macro will be executed as normal.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="hooks"></a>6. Using Hooks</h2></div></div></div><p>
A <span class="emphasis"><em>hook</em></span> is a concept found in many other programs
which allows you to execute arbitrary commands before performing some
operation. For example, you may wish to tailor your configuration based
upon which mailbox you are reading, or to whom you are sending mail. In
the Mutt world, a <span class="emphasis"><em>hook</em></span> consists of a <a class="link" href="advancedusage.html#regexp" title="2. Regular Expressions">regular expression</a> or <a class="link" href="advancedusage.html#patterns" title="3. Patterns: Searching, Limiting and Tagging">pattern</a> along with a configuration
option/command. See:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="link" href="optionalfeatures.html#account-hook" title="7. Managing Multiple Accounts"><span class="command"><strong>account-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#charset-hook" title="8. Defining Aliases for Character Sets"><span class="command"><strong>charset-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#crypt-hook" title="23. Choosing the Cryptographic Key of the Recipient"><span class="command"><strong>crypt-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#fcc-hook" title="19. Specify Default Fcc: Mailbox When Composing"><span class="command"><strong>fcc-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#fcc-save-hook" title="20. Specify Default Save Filename and Default Fcc: Mailbox at Once"><span class="command"><strong>fcc-save-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#folder-hook" title="9. Setting Variables Based Upon Mailbox"><span class="command"><strong>folder-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#charset-hook" title="8. Defining Aliases for Character Sets"><span class="command"><strong>iconv-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#index-format-hook" title="24. Dynamically Changing $index_format using Patterns"><span class="command"><strong>index-format-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#mbox-hook" title="15. Using Multiple Spool Mailboxes"><span class="command"><strong>mbox-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#message-hook" title="22. Change Settings Before Formatting a Message"><span class="command"><strong>message-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#reply-hook"><span class="command"><strong>reply-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#save-hook" title="18. Specify Default Save Mailbox"><span class="command"><strong>save-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#send-hook" title="21. Change Settings Based Upon Message Recipients"><span class="command"><strong>send-hook</strong></span></a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#send2-hook"><span class="command"><strong>send2-hook</strong></span></a>
</p></li></ul></div><p>
for specific details on each type of <span class="emphasis"><em>hook</em></span> available.
Also see <a class="link" href="advancedusage.html#compose-flow" title="18. Message Composition Flow">Message Composition Flow</a> for
an overview of the composition process.
</p><div class="note"><h3 class="title">Note</h3><p>
If a hook changes configuration settings, these changes remain effective
until the end of the current Mutt session. As this is generally not
desired, a <span class="quote">“<span class="quote">default</span>”</span> hook needs to be added before all
other hooks of that type to restore configuration defaults.
</p></div><div class="example"><a id="ex-default-hook"></a><p class="title"><strong>Example 4.5. Specifying a <span class="quote">“<span class="quote">default</span>”</span> hook</strong></p><div class="example-contents"><pre class="screen">
send-hook . 'unmy_hdr From:'
send-hook ~C'^b@b\.b$' my_hdr from: c@c.c
</pre></div></div><br class="example-break" /><p>
In <a class="xref" href="advancedusage.html#ex-default-hook" title="Example 4.5. Specifying a “default” hook">Example 4.5, “Specifying a <span class="quote">“<span class="quote">default</span>”</span> hook”</a>, by default the value of <a class="link" href="reference.html#from" title="3.109. from">$from</a> and <a class="link" href="reference.html#realname" title="3.277. realname">$realname</a> is not overridden. When sending
messages either To: or Cc: to <code class="literal">&lt;b@b.b&gt;</code>, the
From: header is changed to <code class="literal">&lt;c@c.c&gt;</code>.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="pattern-hook"></a>6.1. Message Matching in Hooks</h3></div></div></div><p>
Hooks that act upon messages (<span class="command"><strong>message-hook</strong></span>,
<span class="command"><strong>reply-hook</strong></span>, <span class="command"><strong>send-hook</strong></span>,
<span class="command"><strong>send2-hook</strong></span>, <span class="command"><strong>save-hook</strong></span>,
<span class="command"><strong>fcc-hook</strong></span>, <span class="command"><strong>index-format-hook</strong></span>)
are evaluated in a slightly different
manner. For the other types of hooks, a <a class="link" href="advancedusage.html#regexp" title="2. Regular Expressions">regular
expression</a> is sufficient. But in dealing with messages a finer
grain of control is needed for matching since for different purposes you
want to match different criteria.
</p><p>
Mutt allows the use of the <a class="link" href="advancedusage.html#patterns" title="3. Patterns: Searching, Limiting and Tagging">search
pattern</a> language for matching messages in hook commands. This
works in exactly the same way as it would when
<span class="emphasis"><em>limiting</em></span> or <span class="emphasis"><em>searching</em></span> the
mailbox, except that you are restricted to those operators which match
information Mutt extracts from the header of the message (i.e., from,
to, cc, date, subject, etc.).
</p><p>
For example, if you wanted to set your return address based upon sending
mail to a specific address, you could do something like:
</p><pre class="screen">
send-hook '~t ^me@cs\.hmc\.edu$' 'my_hdr From: Mutt User &lt;user@host&gt;'
</pre><p>
which would execute the given command when sending mail to
<span class="emphasis"><em>me@cs.hmc.edu</em></span>.
</p><p>
However, it is not required that you write the pattern to match using
the full searching language. You can still specify a simple
<span class="emphasis"><em>regular expression</em></span> like the other hooks, in which
case Mutt will translate your pattern into the full language, using the
translation specified by the <a class="link" href="reference.html#default-hook" title="3.75. default_hook">$default_hook</a> variable. The pattern is
translated at the time the hook is declared, so the value of <a class="link" href="reference.html#default-hook" title="3.75. default_hook">$default_hook</a> that is in effect at that
time will be used.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="mailbox-hook"></a>6.2. Mailbox Matching in Hooks</h3></div></div></div><p>
Hooks that match against mailboxes (<span class="command"><strong>folder-hook</strong></span>,
<span class="command"><strong>mbox-hook</strong></span>) apply both <a class="link" href="advancedusage.html#regexp" title="2. Regular Expressions">regular
expression</a> syntax as well as <a class="link" href="advancedusage.html#shortcuts" title="10. Mailbox Shortcuts">mailbox
shortcut</a> expansion on the regexp parameter. There is some
overlap between these, so special attention should be paid to the first
character of the regexp.
</p><pre class="screen">
# Here, ^ will expand to "the current mailbox" not "beginning of string":
folder-hook ^/home/user/Mail/bar "set sort=threads"
# If you want ^ to be interpreted as "beginning of string", one workaround
# is to enclose the regexp in parenthesis:
folder-hook (^/home/user/Mail/bar) "set sort=threads"
# This will expand to the default save folder for the alias "imap.example.com", which
# is probably not what you want:
folder-hook @imap.example.com "set sort=threads"
# A workaround is to use parenthesis or a backslash:
folder-hook (@imap.example.com) "set sort=threads"
folder-hook '\@imap.example.com' "set sort=threads"
</pre><p>
Keep in mind that mailbox shortcut expansion on the regexp parameter
takes place when the hook is initially parsed, not when the hook is
matching against a mailbox. When Mutt starts up and is reading the
.muttrc, some mailbox shortcuts may not be usable. For example, the
"current mailbox" shortcut, ^, will expand to an empty string because no
mailbox has been opened yet. Mutt will issue an error for this case or
if the mailbox shortcut results in an empty regexp.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="setenv"></a>7. Managing the Environment</h2></div></div></div><p>
You can alter the environment that Mutt passes on to its child processes
using the <span class="quote">“<span class="quote">setenv</span>”</span> and <span class="quote">“<span class="quote">unsetenv</span>”</span> operators.
(N.B. These follow Mutt-style syntax, not shell-style!) You can also
query current environment values by prefixing a <span class="quote">“<span class="quote">?</span>”</span> character.
</p><pre class="screen">
setenv TERM vt100
setenv ORGANIZATION "The Mutt Development Team"
unsetenv DISPLAY
setenv ?LESS
</pre></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="query"></a>8. External Address Queries</h2></div></div></div><p>
Mutt supports connecting to external directory databases such as LDAP,
ph/qi, bbdb, or NIS through a wrapper script which connects to Mutt
using a simple interface. Using the <a class="link" href="reference.html#query-command" title="3.271. query_command">$query_command</a> variable, you specify the
wrapper command to use. For example:
</p><pre class="screen">
set query_command = "mutt_ldap_query.pl %s"
</pre><p>
The wrapper script should accept the query on the command-line. It
should return a one line message, then each matching response on a
single line, each line containing a tab separated address then name then
some other optional information. On error, or if there are no matching
addresses, return a non-zero exit code and a one line error message.
</p><p>
An example multiple response output:
</p><pre class="screen">
Searching database ... 20 entries ... 3 matching:
me@cs.hmc.edu Michael Elkins mutt dude
blong@fiction.net Brandon Long mutt and more
roessler@does-not-exist.org Thomas Roessler mutt pgp
</pre><p>
There are two mechanisms for accessing the query function of Mutt. One
is to do a query from the index menu using the
<code class="literal">&lt;query&gt;</code> function (default: Q). This will
prompt for a query, then bring up the query menu which will list the
matching responses. From the query menu, you can select addresses to
create aliases, or to mail. You can tag multiple addresses to mail,
start a new query, or have a new query appended to the current
responses.
</p><p>
The other mechanism for accessing the query function is for address
completion, similar to the alias completion. In any prompt for address
entry, you can use the <code class="literal">&lt;complete-query&gt;</code>
function (default: ^T) to run a query based on the current address you
have typed. Like aliases, Mutt will look for what you have typed back
to the last space or comma. If there is a single response for that
query, Mutt will expand the address in place. If there are multiple
responses, Mutt will activate the query menu. At the query menu, you
can select one or more addresses to be added to the prompt.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="mailbox-formats"></a>9. Mailbox Formats</h2></div></div></div><p>
Mutt supports reading and writing of four different local mailbox
formats: mbox, MMDF, MH and Maildir. The mailbox type is auto detected,
so there is no need to use a flag for different mailbox types. When
creating new mailboxes, Mutt uses the default specified with the <a class="link" href="reference.html#mbox-type" title="3.179. mbox_type">$mbox_type</a> variable. A short description of
the formats follows.
</p><p>
<span class="emphasis"><em>mbox</em></span>. This is a widely used mailbox format for
UNIX. All messages are stored in a single file. Each message has a
line of the form:
</p><pre class="screen">
From me@cs.hmc.edu Fri, 11 Apr 1997 11:44:56 PST
</pre><p>
to denote the start of a new message (this is often referred to as the
<span class="quote">“<span class="quote">From_</span>”</span> line). The mbox format requires mailbox locking, is
prone to mailbox corruption with concurrently writing clients or
misinterpreted From_ lines. Depending on the environment, new mail
detection can be unreliable. Mbox folders are fast to open and easy to
archive.
</p><p>
<span class="emphasis"><em>MMDF</em></span>. This is a variant of the
<span class="emphasis"><em>mbox</em></span> format. Each message is surrounded by lines
containing <span class="quote">“<span class="quote">^A^A^A^A</span>”</span> (four times control-A's). The same
problems as for mbox apply (also with finding the right message
separator as four control-A's may appear in message bodies).
</p><p>
<span class="emphasis"><em>MH</em></span>. A radical departure from
<span class="emphasis"><em>mbox</em></span> and <span class="emphasis"><em>MMDF</em></span>, a mailbox
consists of a directory and each message is stored in a separate file.
The filename indicates the message number (however, this is may not
correspond to the message number Mutt displays). Deleted messages are
renamed with a comma (<span class="quote">“<span class="quote">,</span>”</span>) prepended to the filename. Mutt
detects this type of mailbox by looking for either
<code class="literal">.mh_sequences</code> or <code class="literal">.xmhcache</code> files
(needed to distinguish normal directories from MH mailboxes). MH is more
robust with concurrent clients writing the mailbox, but still may suffer
from lost flags; message corruption is less likely to occur than with
mbox/mmdf. It's usually slower to open compared to mbox/mmdf since many
small files have to be read (Mutt provides <a class="xref" href="optionalfeatures.html#header-caching" title="8.1. Header Caching">Section 8.1, “Header Caching”</a> to greatly speed this process up). Depending
on the environment, MH is not very disk-space efficient.
</p><p>
<span class="emphasis"><em>Maildir</em></span>. The newest of the mailbox formats, used
by the Qmail MTA (a replacement for sendmail). Similar to
<span class="emphasis"><em>MH</em></span>, except that it adds three subdirectories of the
mailbox: <span class="emphasis"><em>tmp</em></span>, <span class="emphasis"><em>new</em></span> and
<span class="emphasis"><em>cur</em></span>. Filenames for the messages are chosen in such
a way they are unique, even when two programs are writing the mailbox
over NFS, which means that no file locking is needed and corruption is
very unlikely. Maildir maybe slower to open without caching in Mutt, it
too is not very disk-space efficient depending on the environment. Since
no additional files are used for metadata (which is embedded in the
message filenames) and Maildir is locking-free, it's easy to sync across
different machines using file-level synchronization tools.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="shortcuts"></a>10. Mailbox Shortcuts</h2></div></div></div><p>
There are a number of built in shortcuts which refer to specific
mailboxes. These shortcuts can be used anywhere you are prompted for a
file or mailbox path or in path-related configuration variables. Note
that these only work at the beginning of a string.
</p><div class="table"><a id="tab-mailbox-shortcuts"></a><p class="title"><strong>Table 4.8. Mailbox shortcuts</strong></p><div class="table-contents"><table class="table" summary="Mailbox shortcuts" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Shortcut</th><th>Refers to...</th></tr></thead><tbody><tr><td><code class="literal">!</code></td><td>your <a class="link" href="reference.html#spoolfile" title="3.370. spoolfile">$spoolfile</a> (incoming) mailbox</td></tr><tr><td><code class="literal">&gt;</code></td><td>your <a class="link" href="reference.html#mbox" title="3.178. mbox">$mbox</a> file</td></tr><tr><td><code class="literal">&lt;</code></td><td>your <a class="link" href="reference.html#record" title="3.279. record">$record</a> file</td></tr><tr><td><code class="literal">^</code></td><td>the current mailbox</td></tr><tr><td><code class="literal">-</code> or <code class="literal">!!</code></td><td>the file you've last visited</td></tr><tr><td><code class="literal">~</code></td><td>your home directory</td></tr><tr><td><code class="literal">=</code> or <code class="literal">+</code></td><td>your <a class="link" href="reference.html#folder" title="3.97. folder">$folder</a> directory</td></tr><tr><td><span class="emphasis"><em>@alias</em></span></td><td>to the <a class="link" href="configuration.html#save-hook" title="18. Specify Default Save Mailbox">default save folder</a> as determined by the address of the alias</td></tr></tbody></table></div></div><br class="table-break" /><p>
For example, to store a copy of outgoing messages in the folder they
were composed in, a <a class="link" href="configuration.html#folder-hook" title="9. Setting Variables Based Upon Mailbox"><span class="command"><strong>folder-hook</strong></span></a> can be used
to set <a class="link" href="reference.html#record" title="3.279. record">$record</a>:
</p><pre class="screen">
folder-hook . 'set record=^'
</pre><p>
Note: the current mailbox shortcut,
<span class="quote">“<span class="quote"><code class="literal">^</code></span>”</span>, has no value in some cases. No
mailbox is opened when Mutt is invoked to send an email from the
command-line. In interactive mode, Mutt reads the muttrc before
opening the mailbox, so immediate expansion won't work as expected
either. This can be an issue when trying to directly assign to <a class="link" href="reference.html#record" title="3.279. record">$record</a>, but also affects the <a class="link" href="configuration.html#fcc-hook" title="19. Specify Default Fcc: Mailbox When Composing">fcc-hook</a> mailbox, which is expanded
immediately too. The folder-hook example above works because the
command is executed later, when the folder-hook fires.
</p><p>
Note: the <a class="link" href="reference.html#record" title="3.279. record">$record</a> shortcut
<span class="quote">“<span class="quote"><code class="literal">&lt;</code></span>”</span> is substituted without any
regard to multiple mailboxes and <a class="link" href="reference.html#fcc-delimiter" title="3.95. fcc_delimiter">$fcc_delimiter</a>. If you use multiple
Fcc mailboxes, and also want to use the
<span class="quote">“<span class="quote"><code class="literal">&lt;</code></span>”</span> mailbox shortcut, it might be
better to set <a class="link" href="reference.html#record" title="3.279. record">$record</a> to the primary
mailbox and use a <a class="link" href="configuration.html#fcc-hook" title="19. Specify Default Fcc: Mailbox When Composing">fcc-hook</a> to set all
mailboxes during message composition.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="using-lists"></a>11. Handling Mailing Lists</h2></div></div></div><p>
Mutt has a few configuration options that make dealing with large
amounts of mail easier. The first thing you must do is to let Mutt know
what addresses you consider to be mailing lists (technically this does
not have to be a mailing list, but that is what it is most often used
for), and what lists you are subscribed to. This is accomplished
through the use of the <a class="link" href="configuration.html#lists" title="14. Mailing Lists"><span class="command"><strong>lists</strong></span>
and <span class="command"><strong>subscribe</strong></span></a> commands in your
<code class="literal">.muttrc</code>. Alternatively or additionally, you can set
<a class="link" href="reference.html#auto-subscribe" title="3.22. auto_subscribe">$auto_subscribe</a> to automatically
subscribe addresses found in a <code class="literal">List-Post</code> header.
</p><p>
Now that Mutt knows what your mailing lists are, it can do several
things, the first of which is the ability to show the name of a list
through which you received a message (i.e., of a subscribed list) in the
<span class="emphasis"><em>index</em></span> menu display. This is useful to distinguish
between personal and list mail in the same mailbox. In the <a class="link" href="reference.html#index-format" title="3.161. index_format">$index_format</a> variable, the expando
<span class="quote">“<span class="quote">%L</span>”</span> will print the string <span class="quote">“<span class="quote">To &lt;list&gt;</span>”</span>
when <span class="quote">“<span class="quote">list</span>”</span> appears in the <span class="quote">“<span class="quote">To</span>”</span> field, and
<span class="quote">“<span class="quote">Cc &lt;list&gt;</span>”</span> when it appears in the <span class="quote">“<span class="quote">Cc</span>”</span>
field (otherwise it prints the name of the author).
</p><p>
Often times the <span class="quote">“<span class="quote">To</span>”</span> and <span class="quote">“<span class="quote">Cc</span>”</span> fields in
mailing list messages tend to get quite large. Most people do not bother
to remove the author of the message they reply to from the list,
resulting in two or more copies being sent to that person. The
<code class="literal">&lt;list-reply&gt;</code> function, which by default is
bound to <span class="quote">“<span class="quote">L</span>”</span> in the <span class="emphasis"><em>index</em></span> menu and
<span class="emphasis"><em>pager</em></span>, helps reduce the clutter by only replying to
the known mailing list addresses instead of all recipients (except as
specified by <code class="literal">Mail-Followup-To</code>, see below).
</p><p>
Mutt also supports the <code class="literal">Mail-Followup-To</code> header. When
you send a message to a list of recipients which includes one or several
known mailing lists, and if the <a class="link" href="reference.html#followup-to" title="3.99. followup_to">$followup_to</a> option is set, Mutt will
generate a Mail-Followup-To header. If any of the recipients are
subscribed mailing lists, this header will contain all the recipients
to whom you send this message, but not your address. This indicates that
group-replies or list-replies (also known as <span class="quote">“<span class="quote">followups</span>”</span>)
to this message should only be sent to the original recipients of the
message, and not separately to you - you'll receive your copy through
one of the mailing lists you are subscribed to. If none of the
recipients are subscribed mailing lists, the header will also contain
your address, ensuring you receive a copy of replies.
</p><p>
Conversely, when group-replying or list-replying to a message which has
a <code class="literal">Mail-Followup-To</code> header, Mutt will respect this
header if the <a class="link" href="reference.html#honor-followup-to" title="3.128. honor_followup_to">$honor_followup_to</a> configuration
variable is set. Using <a class="link" href="gettingstarted.html#list-reply">list-reply</a>
will in this case also make sure that the reply goes to the mailing
list, even if it's not specified in the list of recipients in the
<code class="literal">Mail-Followup-To</code>.
</p><div class="note"><h3 class="title">Note</h3><p>
When header editing is enabled, you can create a
<code class="literal">Mail-Followup-To</code> header manually. Mutt will only
auto-generate this header if it doesn't exist when you send the message.
</p></div><p>
The other method some mailing list admins use is to generate a
<span class="quote">“<span class="quote">Reply-To</span>”</span> field which points back to the mailing list
address rather than the author of the message. This can create problems
when trying to reply directly to the author in private, since most mail
clients will automatically reply to the address given in the
<span class="quote">“<span class="quote">Reply-To</span>”</span> field. Mutt uses the <a class="link" href="reference.html#reply-to" title="3.285. reply_to">$reply_to</a> variable to help decide which
address to use. If set to <span class="emphasis"><em>ask-yes</em></span> or
<span class="emphasis"><em>ask-no</em></span>, you will be prompted as to whether or not
you would like to use the address given in the <span class="quote">“<span class="quote">Reply-To</span>”</span>
field, or reply directly to the address given in the <span class="quote">“<span class="quote">From</span>”</span>
field. When set to <span class="emphasis"><em>yes</em></span>, the
<span class="quote">“<span class="quote">Reply-To</span>”</span> field will be used when present.
</p><p>
While looking at an email message from a mailing list in the index or
pager, you can interact with the list server in the ways defined by RFC
2369, provided the email message specifies how to do so. Invoke the
<a class="link" href="reference.html#tab-list-bindings" title="Table 9.16. Default List Menu Bindings"> list menu</a> (bound to "ESC
L" by default) to see what options are available for a given
message. Common options are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Post to the list</p></li><li class="listitem"><p>Contact the list owner</p></li><li class="listitem"><p>Subscribe to the list</p></li><li class="listitem"><p>Unsubscribe from the list</p></li><li class="listitem"><p>Get help from the list server</p></li><li class="listitem"><p>Get list archive information</p></li></ul></div><p>
Note that many list servers only specify some of these options.
</p><p>
The <span class="quote">“<span class="quote">X-Label:</span>”</span> header field can be used to further identify
mailing lists or list subject matter (or just to annotate messages
individually). The <a class="link" href="reference.html#index-format" title="3.161. index_format">$index_format</a>
variable's <span class="quote">“<span class="quote">%y</span>”</span> and <span class="quote">“<span class="quote">%Y</span>”</span> expandos can be used
to expand <span class="quote">“<span class="quote">X-Label:</span>”</span> fields in the index, and Mutt's
pattern-matcher can match regular expressions to <span class="quote">“<span class="quote">X-Label:</span>”</span>
fields with the <span class="quote">“<span class="quote">~y</span>”</span> selector. <span class="quote">“<span class="quote">X-Label:</span>”</span> is
not a standard message header field, but it can easily be inserted by
procmail and other mail filtering agents.
</p><p>
You can change or delete the <span class="quote">“<span class="quote">X-Label:</span>”</span> field within
Mutt using the <span class="quote">“<span class="quote">edit-label</span>”</span> command, bound to the
<span class="quote">“<span class="quote">y</span>”</span> key by default. This works for tagged messages, too.
While in the edit-label function, pressing the &lt;complete&gt;
binding (TAB, by default) will perform completion against all labels
currently in use.
</p><p>
Lastly, Mutt has the ability to <a class="link" href="reference.html#sort" title="3.362. sort">sort</a> the
mailbox into <a class="link" href="gettingstarted.html#threads" title="5.3. Threaded Mode">threads</a>. A thread is a
group of messages which all relate to the same subject. This is usually
organized into a tree-like structure where a message and all of its
replies are represented graphically. If you've ever used a threaded
news client, this is the same concept. It makes dealing with large
volume mailing lists easier because you can easily delete uninteresting
threads and quickly find topics of value.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="display-munging"></a>12. Display Munging</h2></div></div></div><p>
Working within the confines of a console or terminal window, it is
often useful to be able to modify certain information elements in a
non-destructive way -- to change how they display, without changing
the stored value of the information itself. This is especially so of
message subjects, which may often be polluted with extraneous metadata
that either is reproduced elsewhere, or is of secondary interest.
</p><div class="cmdsynopsis"><p><code class="command">subjectrx</code>
<em class="replaceable"><code>pattern</code></em>
<em class="replaceable"><code>replacement</code></em>
<br /><code class="command">unsubjectrx</code> {
<em class="replaceable"><code>*</code></em>
|
<em class="replaceable"><code>pattern</code></em>
}</p></div><p>
<code class="literal">subjectrx</code> specifies a regular expression
<span class="quote">“<span class="quote">pattern</span>”</span> which, if detected in a message subject, causes
the subject to be replaced with the <span class="quote">“<span class="quote">replacement</span>”</span> value.
The replacement is subject to substitutions in the same way as for the
<a class="link" href="configuration.html#spam" title="28. Spam Detection">spam</a> command: <code class="literal">%L</code> for the text
to the left of the match, <code class="literal">%R</code> for text to the right of the
match, and <code class="literal">%1</code> for the first subgroup in the match (etc).
If you simply want to erase the match, set it to <span class="quote">“<span class="quote">%L%R</span>”</span>.
Any number of <code class="literal">subjectrx</code> commands may coexist.
</p><p>
Note this well: the <span class="quote">“<span class="quote">replacement</span>”</span> value replaces the
entire subject, not just the match!
</p><p>
<code class="literal">unsubjectrx</code> removes a given subjectrx from the
substitution list. If <code class="literal">*</code> is used as the pattern,
all substitutions will be removed.
</p><div class="example"><a id="ex-subjectrx"></a><p class="title"><strong>Example 4.6. Subject Munging</strong></p><div class="example-contents"><pre class="screen">
# Erase [rt #12345] tags from Request Tracker (RT) e-mails
subjectrx '\[rt #[0-9]+\] *' '%L%R'
# Servicedesk is another RT that sends more complex subjects.
# Keep the ticket number.
subjectrx '\[servicedesk #([0-9]+)\] ([^.]+)\.([^.]+) - (new|open|pending|update) - ' '%L[#%1] %R'
# Strip out annoying [listname] prefixes in subjects
subjectrx '\[[^]]*\]:? *' '%L%R'
</pre></div></div><br class="example-break" /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="new-mail"></a>13. New Mail Detection</h2></div></div></div><p>
Mutt supports setups with multiple folders, allowing all of them to be
monitored for new mail (see <a class="xref" href="configuration.html#mailboxes" title="16. Monitoring Incoming Mail">Section 16, “Monitoring Incoming Mail”</a> for details).
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="new-mail-formats"></a>13.1. How New Mail Detection Works</h3></div></div></div><p>
For Mbox and Mmdf folders, new mail is detected by comparing access
and/or modification times of files: Mutt assumes a folder has new mail
if it wasn't accessed after it was last modified. Utilities like
<code class="literal">biff</code> or <code class="literal">frm</code> or any other program
which accesses the mailbox might cause Mutt to never detect new mail for
that mailbox if they do not properly reset the access time. Other
possible causes of Mutt not detecting new mail in these folders are
backup tools (updating access times) or filesystems mounted without
access time update support (for Linux systems, see the
<code class="literal">relatime</code> option).
</p><div class="note"><h3 class="title">Note</h3><p>
Contrary to older Mutt releases, it now maintains the new mail status of
a folder by properly resetting the access time if the folder contains at
least one message which is neither read, nor deleted, nor marked as old.
</p></div><p>
In cases where new mail detection for Mbox or Mmdf folders appears to be
unreliable, the <a class="link" href="reference.html#check-mbox-size" title="3.42. check_mbox_size">$check_mbox_size</a>
option can be used to make Mutt track and consult file sizes for new
mail detection instead which won't work for size-neutral changes.
</p><p>
New mail for Maildir is assumed if there is one message in the
<code class="literal">new/</code> subdirectory which is not marked deleted (see
<a class="link" href="reference.html#maildir-trash" title="3.172. maildir_trash">$maildir_trash</a>). For MH folders, a
mailbox is considered having new mail if there's at least one message in
the <span class="quote">“<span class="quote">unseen</span>”</span> sequence as specified by <a class="link" href="reference.html#mh-seq-unseen" title="3.192. mh_seq_unseen">$mh_seq_unseen</a>.
</p><p>
Mutt does not poll POP3 folders for new mail, it only periodically
checks the currently opened folder (if it's a POP3 folder).
</p><p>
For IMAP, by default Mutt uses recent message counts provided by the
server to detect new mail. If the <a class="link" href="reference.html#imap-idle" title="3.141. imap_idle">$imap_idle</a> option is set, it'll use the IMAP
IDLE extension if advertised by the server.
</p><p>
The <a class="link" href="reference.html#mail-check-recent" title="3.166. mail_check_recent">$mail_check_recent</a>
option changes whether Mutt will notify you of new mail in an
already visited mailbox. When set (the default) it will only notify
you of new mail received since the last time you opened the mailbox.
When unset, Mutt will notify you of any new mail in the mailbox.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="new-mail-polling"></a>13.2. Polling For New Mail</h3></div></div></div><p>
When in the index menu and being idle (also see <a class="link" href="reference.html#timeout" title="3.398. timeout">$timeout</a>), Mutt periodically checks for new
mail in all folders which have been configured via the
<span class="command"><strong>mailboxes</strong></span> command (excepting those specified with
the <code class="literal">-nopoll</code> flag). The interval depends on the
folder type: for local/IMAP folders it consults <a class="link" href="reference.html#mail-check" title="3.165. mail_check">$mail_check</a> and <a class="link" href="reference.html#pop-checkinterval" title="3.251. pop_checkinterval">$pop_checkinterval</a> for POP folders.
</p><p>
Outside the index menu the directory browser supports checking for new
mail using the <code class="literal">&lt;check-new&gt;</code> function which is
unbound by default. Pressing TAB will bring up a menu showing the files
specified by the <span class="command"><strong>mailboxes</strong></span> command, and indicate
which contain new messages. Mutt will automatically enter this mode when
invoked from the command line with the <code class="literal">-y</code> option,
or from the index/pager via the <code class="literal">&lt;browse-mailboxes&gt;</code>
function.
</p><p>
For the pager, index and directory browser menus, Mutt contains the
<code class="literal">&lt;buffy-list&gt;</code> function (bound to
<span class="quote">“<span class="quote">.</span>”</span> by default) which will print a list of folders with new
mail in the command line at the bottom of the screen.
</p><p>
For the index, by default Mutt displays the number of mailboxes with new
mail in the status bar, please refer to the <a class="link" href="reference.html#status-format" title="3.389. status_format">$status_format</a> variable for details.
</p><p>
When changing folders, Mutt fills the prompt with the first folder from
the mailboxes list containing new mail (if any), pressing
<code class="literal">&lt;Space&gt;</code> will cycle through folders with new
mail. The (by default unbound) function
<code class="literal">&lt;next-unread-mailbox&gt;</code> in the index can be used
to immediately open the next folder with unread mail (if any).
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="new-mail-monitoring"></a>13.3. Monitoring New Mail</h3></div></div></div><p>
When the <span class="emphasis"><em>Inotify</em></span> mechanism for monitoring of
files is supported (Linux only) and not disabled at compilation time,
Mutt immediately notifies about new mail for all folders configured
via the <a class="link" href="configuration.html#mailboxes" title="16. Monitoring Incoming Mail"><span class="command"><strong>mailboxes</strong></span></a>
command (excepting those specified with the <code class="literal">-nopoll</code>
flag). Dependent on <a class="link" href="advancedusage.html#mailbox-formats" title="9. Mailbox Formats">mailbox
format</a> also added <span class="emphasis"><em>old</em></span> mails are tracked
(not for Maildir).
</p><p>
No configuration variables are available. Trace output is given when
debugging is enabled via <a class="link" href="reference.html#tab-commandline-options" title="Table 9.1. Command line options">command
line option</a> <code class="literal">-d3</code>. The lower level 2 only shows
errors, the higher level 5 all including raw Inotify events.
</p><div class="note"><h3 class="title">Note</h3><p>
Getting events about new mail is limited to the capabilities of the
underlying mechanism. <span class="emphasis"><em>Inotify</em></span> only reports local
changes, i. e. new mail notification works for mails delivered by an
agent on the same machine as Mutt, but not when delivered remotely on
a network file system as NFS. Also the monitoring handles might fail
in rare conditions, so you better don't completely rely on this
feature.
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="calc-mailbox-counts"></a>13.4. Calculating Mailbox Message Counts</h3></div></div></div><p>
If <a class="link" href="reference.html#mail-check-stats" title="3.167. mail_check_stats">$mail_check_stats</a> is set,
Mutt will periodically calculate the unread, flagged, and total
message counts for each mailbox watched by the
<span class="command"><strong>mailboxes</strong></span> command. (Note: IMAP mailboxes only support
unread and total counts). This calculation takes place at the same
time as new mail polling, but is controlled by a separate timer: <a class="link" href="reference.html#mail-check-stats-interval" title="3.168. mail_check_stats_interval">$mail_check_stats_interval</a>.
</p><p>
The sidebar can display these message counts. See <a class="link" href="reference.html#sidebar-format" title="3.311. sidebar_format">$sidebar_format</a>.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="editing-threads"></a>14. Editing Threads</h2></div></div></div><p>
Mutt has the ability to dynamically restructure threads that are broken
either by misconfigured software or bad behavior from some
correspondents. This allows to clean your mailboxes from these
annoyances which make it hard to follow a discussion.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="link-threads"></a>14.1. Linking Threads</h3></div></div></div><p>
Some mailers tend to <span class="quote">“<span class="quote">forget</span>”</span> to correctly set the
<span class="quote">“<span class="quote">In-Reply-To:</span>”</span> and <span class="quote">“<span class="quote">References:</span>”</span> headers when
replying to a message. This results in broken discussions because Mutt
has not enough information to guess the correct threading. You can fix
this by tagging the reply, then moving to the parent message and using
the <code class="literal">&lt;link-threads&gt;</code> function (bound to &amp; by
default). The reply will then be connected to this parent message.
</p><p>
You can also connect multiple children at once, tagging them and using
the <code class="literal">&lt;tag-prefix&gt;</code> command (<span class="quote">“<span class="quote">;</span>”</span>) or
the <a class="link" href="reference.html#auto-tag" title="3.23. auto_tag">$auto_tag</a> option.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="break-threads"></a>14.2. Breaking Threads</h3></div></div></div><p>
On mailing lists, some people are in the bad habit of starting a new
discussion by hitting <span class="quote">“<span class="quote">reply</span>”</span> to any message from the list
and changing the subject to a totally unrelated one. You can fix such
threads by using the <code class="literal">&lt;break-thread&gt;</code> function
(bound by default to #), which will turn the subthread starting from the
current message into a whole different thread.
</p></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="dsn"></a>15. Delivery Status Notification (DSN) Support</h2></div></div></div><p>
RFC1894 defines a set of MIME content types for relaying information
about the status of electronic mail messages. These can be thought of
as <span class="quote">“<span class="quote">return receipts.</span>”</span>
</p><p>
To support DSN, there are two variables. <a class="link" href="reference.html#dsn-notify" title="3.81. dsn_notify">$dsn_notify</a> is used to request receipts for
different results (such as failed message, message delivered, etc.).
<a class="link" href="reference.html#dsn-return" title="3.82. dsn_return">$dsn_return</a> requests how much of your
message should be returned with the receipt (headers or full message).
</p><p>
When using <a class="link" href="reference.html#sendmail" title="3.305. sendmail">$sendmail</a> for mail delivery,
you need to use either Berkeley sendmail 8.8.x (or greater) a MTA
supporting DSN command line options compatible to Sendmail: The -N and
-R options can be used by the mail client to make requests as to what
type of status messages should be returned. Please consider your MTA
documentation whether DSN is supported.
</p><p>
For SMTP delivery using <a class="link" href="reference.html#smtp-url" title="3.359. smtp_url">$smtp_url</a>, it
depends on the capabilities announced by the server whether Mutt will
attempt to request DSN or not.
</p></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="urlview"></a>16. Start a WWW Browser on URLs</h2></div></div></div><p>
If a message contains URLs, it is efficient to get a menu with all the
URLs and start a WWW browser on one of them. This functionality is
provided by the external urlview program which can be retrieved at
<a class="ulink" href="https://github.com/sigpipe/urlview" target="_top">https://github.com/sigpipe/urlview</a>
and the configuration commands:
</p><pre class="screen">
macro index \cb |urlview\n
macro pager \cb |urlview\n
</pre></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="echo"></a>17. Echoing Text</h2></div></div></div><p>
Usage:
</p><div class="cmdsynopsis"><p><code class="command">echo</code>
<em class="replaceable"><code>message</code></em>
</p></div><p>
You can print messages to the message window using the "echo" command.
This might be useful after a macro finishes executing. After printing
the message, echo will pause for the number of seconds specified by
<a class="link" href="reference.html#sleep-time" title="3.329. sleep_time">$sleep_time</a>.
</p><pre class="screen">
echo "Sourcing muttrc file"
unset confirmappend
macro index ,a "&lt;save-message&gt;=archive&lt;enter&gt;&lt;enter-command&gt;echo 'Saved to archive'&lt;enter&gt;"
</pre></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="compose-flow"></a>18. Message Composition Flow</h2></div></div></div><p>
This is a brief overview of the steps Mutt takes during message
composition. It also shows the order and timing of hook execution.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Reply envelope settings. <a class="link" href="reference.html#reverse-name" title="3.290. reverse_name">$reverse_name</a> processing. To,
Cc, Subject, References header defaults.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#my-hdr" title="17. User-Defined Headers">my_hdr</a> processing for To, Cc,
Bcc, Subject headers.
</p></li><li class="listitem"><p>
Prompts for To, Cc, Bcc, Subject headers.
See <a class="link" href="reference.html#askcc" title="3.12. askcc">$askcc</a>,
<a class="link" href="reference.html#askbcc" title="3.11. askbcc">$askbcc</a>,
<a class="link" href="reference.html#fast-reply" title="3.91. fast_reply">$fast_reply</a>.
</p></li><li class="listitem"><p>
From header setting. Note: this is so <a class="link" href="configuration.html#send-hook" title="21. Change Settings Based Upon Message Recipients">send-hook</a>s below can match ~P, but
From is re-set further below in case a send-hook changes the
value.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#reply-hook">reply-hook</a>
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#send-hook" title="21. Change Settings Based Upon Message Recipients">send-hook</a>
</p></li><li class="listitem"><p>
From header setting.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#my-hdr" title="17. User-Defined Headers">my_hdr</a> processing for From,
Reply-To, Message-ID and user-defined headers. The To, Cc,
Bcc, and Subject headers are ignored at this stage.
</p></li><li class="listitem"><p>
Message body and signature generation.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#send2-hook">send2-hook</a>
</p></li><li class="listitem"><p>
<a class="link" href="reference.html#realname" title="3.277. realname">$realname</a> part of From header setting.
</p></li><li class="listitem"><p>
<a class="link" href="reference.html#editor" title="3.85. editor">$editor</a> invocation for the
message.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#send2-hook">send2-hook</a>
</p></li><li class="listitem"><p>
Cryptographic settings.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#fcc-hook" title="19. Specify Default Fcc: Mailbox When Composing">fcc-hook</a>. Fcc setting.
</p></li><li class="listitem"><p>
<a class="link" href="mimesupport.html#compose-menu" title="1.4. The Compose Menu">Compose menu</a>. Note: <a class="link" href="configuration.html#send2-hook">send2-hook</a> is evaluated each time
the headers are changed.
</p></li><li class="listitem"><p>
<a class="link" href="reference.html#send-multipart-alternative" title="3.303. send_multipart_alternative">$send_multipart_alternative</a>
generation.
</p></li><li class="listitem"><p>
Message encryption and signing. Key selection.
</p></li><li class="listitem"><p>
Fcc saving if <a class="link" href="reference.html#fcc-before-send" title="3.93. fcc_before_send">$fcc_before_send</a> is set. (Note the
variable documentation for caveats of Fcc'ing before sending.)
</p></li><li class="listitem"><p>
Message sending.
</p></li><li class="listitem"><p>
Fcc saving if <a class="link" href="reference.html#fcc-before-send" title="3.93. fcc_before_send">$fcc_before_send</a> is unset
(the default). Note: prior to version 1.12, the Fcc was saved
before sending the message. It is now by default saved
afterwards, but if the saving fails, the user is prompted.
</p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="batch-compose-flow"></a>19. Batch Composition Flow</h2></div></div></div><p>
In batch mode, Mutt performs less steps than interactive mode.
Encryption and Signing are not supported.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="link" href="configuration.html#my-hdr" title="17. User-Defined Headers">my_hdr</a> processing for To, Cc,
Bcc headers. (Subject is not processed.)
</p></li><li class="listitem"><p>
From header setting. Note: this is so <a class="link" href="configuration.html#send-hook" title="21. Change Settings Based Upon Message Recipients">send-hook</a>s below can match ~P, but
From is re-set further below in case a send-hook changes the
value.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#send-hook" title="21. Change Settings Based Upon Message Recipients">send-hook</a>
</p></li><li class="listitem"><p>
From header setting.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#my-hdr" title="17. User-Defined Headers">my_hdr</a> processing for From,
Reply-To, Message-ID and user-defined headers. The To, Cc,
Bcc, Subject, and Return-Path headers are ignored at this
stage.
</p></li><li class="listitem"><p>
Message body is copied from stdin. <a class="link" href="reference.html#signature" title="3.323. signature">$signature</a> is not appended in batch
mode.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#send2-hook">send2-hook</a>
</p></li><li class="listitem"><p>
<a class="link" href="reference.html#realname" title="3.277. realname">$realname</a> part of From header setting.
</p></li><li class="listitem"><p>
<a class="link" href="configuration.html#fcc-hook" title="19. Specify Default Fcc: Mailbox When Composing">fcc-hook</a>. Fcc setting.
</p></li><li class="listitem"><p>
<a class="link" href="reference.html#send-multipart-alternative" title="3.303. send_multipart_alternative">$send_multipart_alternative</a>
generation.
</p></li><li class="listitem"><p>
Fcc saving if <a class="link" href="reference.html#fcc-before-send" title="3.93. fcc_before_send">$fcc_before_send</a> is set. (Note the
variable documentation for caveats of Fcc'ing before sending.)
</p></li><li class="listitem"><p>
Message sending.
</p></li><li class="listitem"><p>
Fcc saving if <a class="link" href="reference.html#fcc-before-send" title="3.93. fcc_before_send">$fcc_before_send</a> is unset
(the default). Note: prior to version 1.12, the Fcc was saved
before sending the message. It is now by default saved
afterwards, but if the saving fails, the user is prompted.
</p></li></ul></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="muttlisp"></a>20. Using MuttLisp (EXPERIMENTAL)</h2></div></div></div><p>
MuttLisp is a Lisp-like enhancement for the Mutt configuration
file. It is currently experimental, meaning new releases may
change or break syntax. MuttLisp is not a real language, and is
not meant to be an alternative to macros. The features are
purposely minimal, with the actual work still being done by Mutt
<a class="link" href="reference.html#commands" title="2. Configuration Commands">commands</a>.
</p><p>
There are two ways to invoke MuttLisp: via the
<code class="literal">run</code> command, or interpolated as a command
argument.
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="run"></a>20.1. Running a command generated by MuttLisp</h3></div></div></div><p>
Usage:
</p><div class="cmdsynopsis"><p><code class="command">run</code>
<em class="replaceable"><code>MuttLisp</code></em>
</p></div><p>
The <code class="literal">run</code> command evaluates the MuttLisp argument.
The output of the MuttLisp is then executed as a
Mutt command, as if it were typed in the muttrc instead.
</p><pre class="screen">
run (concat "set my_name = '" \
(or $ENV_NAME "Test User") "'")
==&gt; generates and runs the line:
set my_name = 'Test User'
</pre><p>
This will set the Mutt <a class="link" href="configuration.html#set-myvar" title="29.3. User-Defined Variables">User-Defined Variable</a>
<code class="literal">$my_name</code> to either the environment variable $ENV_NAME, if
defined, or else "Test User".
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="muttlisp-interpolate"></a>20.2. Interpolating MuttLisp in a Command Argument</h3></div></div></div><p>
The second way of running is directly as a command argument.
An unquoted parenthesis expression will be evaluated, and the result
substituted as the argument.
</p><p>
To avoid breaking existing configurations, this is disabled by
default. It can be enabled by setting <a class="link" href="reference.html#muttlisp-inline-eval" title="3.201. muttlisp_inline_eval">$muttlisp_inline_eval</a>. Before doing so, you should
review your Mutt configuration to ensure you don't have any bare
parenthesis expressions elsewhere, such as the regexp parameter
of a <a class="link" href="configuration.html#folder-hook" title="9. Setting Variables Based Upon Mailbox">folder-hook</a>. These can typically be
surrounded by single or double-quotes to prevent being evaluated as
MuttLisp.
</p><pre class="screen">
set my_name = (or $ENV_NAME "Test User")
</pre><p>
The result of the MuttLisp is directly assigned as the argument.
It isn't reinterpreted, so there is no need for the outer
quotes. This is in contrast with the <a class="link" href="advancedusage.html#run" title="20.1. Running a command generated by MuttLisp">run</a> command, where the output is
reinterpreted by the muttrc parser.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="muttlisp-syntax"></a>20.3. MuttLisp Syntax</h3></div></div></div><p>
MuttLisp was inspired by Lisp, and so follows the same basic
syntax. All statements are surrounded by parenthesis. The first argument
inside the parenthesis is a function to invoke. The remaining arguments
are passed as parameters.
</p><p>
The arguments to functions are read and evaluated using <a class="link" href="configuration.html#muttrc-syntax" title="3. Syntax of Initialization Files">muttrc syntax</a>. This means Mutt
variables or environment variables can be passed directly, or
interpolated inside a double-quoted string.
</p><p>
Although the arguments to a function are evaluated, the result
of the function call is not.
</p><pre class="screen">
echo (concat '$' 'spoolfile')
==&gt; $spoolfile
</pre><p>
MuttLisp has no types - everything is stored and evaluated as
a string, just as with the muttrc. True is defined as a non-empty
string, and false as the empty string.
</p><p>
The muttrc is evaluated line by line, and MuttLisp is similarly
constrained. Input can be continued on more than one line by
placing a backslash at the end of the line.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="muttlisp-funcs"></a>20.4. MuttLisp Functions</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="muttlisp-concat"></a>20.4.1. concat</h4></div></div></div><p>
Combines all arguments into a single string.
</p><pre class="screen">
echo (concat one two three)
==&gt; onetwothree
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="muttlisp-quote"></a>20.4.2. quote</h4></div></div></div><p>
Prevents interpretation of the list. Note that the list must
still obey MuttLisp syntax: single quotes, double quotes,
backticks, and parenthesis are still parsed prior to
<code class="literal">quote</code> running and must be matching.
</p><pre class="screen">
echo (quote one two three)
==&gt; one two three
echo (quote $spoolfile)
==&gt; $spoolfile
echo (quote (one two three))
==&gt; (one two three)
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="muttlisp-equal"></a>20.4.3. equal</h4></div></div></div><p>
Performs a case-sensitive comparison of each argument. Stops evaluating
arguments when it finds the first one that is not equal. Returns
"t" if they are all equal, and the empty string if not.
</p><pre class="screen">
echo (equal one one)
==&gt; "t"
echo (equal one `echo one`)
==&gt; "t"
echo (equal one one two `echo three`)
==&gt; ""
note: `echo three` does not execute.
echo (equal "one two" `echo one two`)
==&gt; ""
note: backticks generate two arguments "one" and "two"
echo (equal "one two" "`echo one two`")
==&gt; "t"
note: backticks inside double quotes generates a single argument: "one two"
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="muttlisp-not"></a>20.4.4. not</h4></div></div></div><p>
Accepts a single argument only.
Returns "t" if the argument evaluates to the empty string.
Otherwise returns the empty string.
</p><pre class="screen">
echo (not one)
==&gt; ""
echo (not "")
==&gt; "t"
echo (not (equal one two))
==&gt; "t"
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="muttlisp-and"></a>20.4.5. and</h4></div></div></div><p>
Returns the first argument that evaluates to the empty string.
Otherwise returns the last argument, or "t" if there are no arguments.
</p><pre class="screen">
echo (and one two)
==&gt; "two"
echo (and "" two `echo three`)
==&gt; ""
note: `echo three` does not execute.
echo (and)
==&gt; "t"
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="muttlisp-or"></a>20.4.6. or</h4></div></div></div><p>
Returns the first argument that evaluates to a non-empty string. Otherwise
returns the empty string.
</p><pre class="screen">
echo (or one two)
==&gt; "one"
echo (or "" two `echo three`)
==&gt; "two"
note: `echo three` does not execute.
echo (or)
==&gt; ""
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="muttlisp-if"></a>20.4.7. if</h4></div></div></div><p>
Requires 2 or 3 arguments. The first is a conditional. If it
evaluates to "true" (a non-empty string), the second argument is
evaluated and returned. Otherwise the third argument is evaluated
and returned.
</p><pre class="screen">
echo (if a one two)
==&gt; "one"
echo (if "" one two)
==&gt; "two"
set spoolfile = "/var/mail/user"
echo (if (equal $spoolfile "/var/mail/user") yes no)
==&gt; "yes"
</pre><p>
Note that boolean configuration variables evaluate to the strings
"yes" or "no". You can see the value of other
kinds of configuration variables using the
<a class="link" href="advancedusage.html#echo" title="17. Echoing Text">echo</a> command.
</p><pre class="screen">
unset allow_ansi
echo $allow_ansi
===&gt; "no"
# the correct way to test a boolean:
echo (if (equal $allow_ansi "yes") "set" "unset")
===&gt; "unset"
# the incorrect way to test a boolean:
echo (if $allow_ansi "set" "unset")
===&gt; "set"
</pre></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="muttlisp-examples"></a>20.5. Examples</h3></div></div></div><p>
It's important to remember that function arguments are
evaluated, but the result is not. Also, the result of an
interpolated command argument is used directly, and needs no
quoting.
</p><pre class="screen">
# A three-way toggle of $index_format:
set muttlisp_inline_eval
set my_idx1 = "one"
set my_idx2 = "two"
set my_idx3 = "three"
set index_format = $my_idx1
macro index i '&lt;enter-command&gt;set index_format = \
(or \
(if (equal $index_format $my_idx1) $my_idx2) \
(if (equal $index_format $my_idx2) $my_idx3) \
$my_idx1) \
&lt;enter&gt;'
</pre><p>
The output of the run command is re-evaluated by the muttrc
parser. So it's important to pay more attention to quoting
issues when generating the command string below.
</p><pre class="screen">
# Conditionally set up background editing in tmux or GNU Screen:
run \
(if (or $STY $TMUX) \
(concat \
'set background_edit;' \
'set editor = "bgedit-screen-tmux.sh vim"') \
(concat \
'unset background_edit;' \
'set editor = "vim"'))
</pre><p>
Because backticks are evaluated by MuttLisp too, we need to use
the run command below and pay close attention to quoting.
</p><pre class="screen">
# Use a Mutt variable inside backticks.
set spoolfile = "/var/mail/testuser"
# This will generate and then run the command string:
# set my_var = "`~/bin/myscript.sh /var/mail/testuser`"
run \
(concat \
'set my_var = "`~/bin/myscript.sh ' \
$spoolfile \
'`"')
</pre></div></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="misc-topics"></a>21. Miscellany</h2></div></div></div><p>
This section documents various features that fit nowhere else.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
Address normalization
</span></dt><dd><p>
Mutt normalizes all e-mail addresses to the simplest form possible. If
an address contains a realname, the form <span class="emphasis"><em>Joe User
&lt;joe@example.com&gt;</em></span> is used and the pure e-mail address
without angle brackets otherwise, i.e. just
<span class="emphasis"><em>joe@example.com</em></span>.
</p><p>
This normalization affects all headers Mutt generates including aliases.
</p></dd><dt><span class="term">
Initial folder selection
</span></dt><dd><p>
The folder Mutt opens at startup is determined as follows: the folder
specified in the <code class="literal">$MAIL</code> environment variable if
present. Otherwise, the value of <code class="literal">$MAILDIR</code> is taken
into account. If that isn't present either, Mutt takes the user's
mailbox in the mailspool as determined at compile-time (which may also
reside in the home directory). The <a class="link" href="reference.html#spoolfile" title="3.370. spoolfile">$spoolfile</a> setting overrides this
selection. Highest priority has the mailbox given with the
<code class="literal">-f</code> command line option.
</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuration.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="mimesupport.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Configuration </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. Mutt's MIME Support</td></tr></table></div></body></html>
Reference in a new issue View git blame Copy permalink