1@c This is part of the GNU Mailutils manual.
2@c Copyright (C) 1999--2021 Free Software Foundation, Inc.
3@c See file mailutils.texi for copying conditions.
4@comment *******************************************************************
5@pindex readmsg
6
7The @command{readmsg} utility extracts messages from a mailbox
8according to the criteria specified in the command line.  These
9criteria are:
10
11@enumerate
12@item A lone @samp{*} means ``select all messages in the mailbox''.
13
14@item
15A list of message numbers may be specified.  Values
16of @samp{0} and @samp{$} in the list both mean the last
17message in the mailbox.  For example:
18
19@example
20readmsg 1 3 0
21@end example
22
23@noindent
24extracts three messages from the folder: the first, the third, and the last.
25
26@item
27Finally, the selection may be some text to match.  This will select a mail
28message which exactly matches the specified text.  For example,
29
30@example
31readmsg staff meeting
32@end example
33
34@noindent
35extracts the message which contains the words @samp{staff meeting}.
36Note that it will not match a message containing @samp{Staff Meeting}
37-- the matching is case sensitive by default.  This can changed using
38the @option{-i} (@option{--ignorecase}) option.  Two more options are
39provided to control the matching algorithm: the @option{-g}
40(@option{--glob}) option instructs @command{readmsg} to treat
41arguments as shell globbing patterns and the @option{-r}
42(@option{--regex}) option instructs it to treat them as POSIX extended
43regular expressions.  Needless to say, when using any of the two latter
44options, you should pay attention to escape the matching pattern to
45prevent it from being interpreted by the shell.  E.g.:
46
47@example
48readmsg --regex 'staff.*meeting'
49@end example
50@end enumerate
51
52Unless requested otherwise, only the first message that matches the
53pattern is printed.
54
55At least one command line argument or one informational option must be
56present in @command{readmsg} invocation.  Informational options are:
57@option{--help} (@option{-?}), @option{--usage}, and
58@option{--version} (@option{-V}).
59
60@menu
61* Opt-readmsg::   Invocation of @command{readmsg}.
62* Conf-readmsg::  Configuration of @command{readmsg}.
63@end menu
64
65@node Opt-readmsg
66@subsection Invocation of @command{readmsg}.
67
68@table @option
69@item -a
70@itemx --show-all
71If a pattern is used for selection, show all messages that match pattern
72by default only the first one is presented.
73
74@item -d
75@itemx --debug
76Display mailbox debugging information.
77
78@item -e
79@itemx --exact
80Look for messages containing exactly the words given as arguments.
81This is the default.  Other options changing this behavior are:
82@option{--glob}, @option{--regex}, and @option{--ignorecase}.
83
84@item -f @var{mailbox}
85@itemx --folder=@var{mailbox}
86Specified the default mailbox.
87
88@item -g
89@itemx --glob
90Treat non-option arguments as shell globbing patterns.  For example,
91to select the first message with words @samp{morning} and
92@samp{coffee} with anything bewteen them:
93
94@example
95readmsg --glob 'morning*coffee'
96@end example
97
98@noindent
99(notice quoting, which prevents the shell from interpreting the
100@samp{*} prematurely).
101
102@item -h
103@itemx --header
104Show the entire header and ignore the weedlist.
105
106@item -i
107@itemx --ignorecase
108Ignore the case of letters when looking for matching messages.  E.g.:
109
110@example
111readmsg --glob --ignorecase 'morning*coffee'
112@end example
113
114@item -n
115@itemx --no-header
116Do not print the message header.
117
118@item -p
119@itemx --form-feed
120Put form-feed (Control-L) between messages instead of newline.
121
122@item -r
123@itemx --regex
124Treat non-option arguments as POSIX extended regular expressions.
125
126@anchor{weedlist option}
127@item  -w @var{weedlist}
128@itemx --weedlist=@var{weedlist}
129A whitespace or coma separated list of header names to show per message.
130Default is @option{--weedlist="From Subject Date To CC Apparently-"}.
131@end table
132
133See also @ref{Common Options}.
134
135@node Conf-readmsg
136@subsection Configuration of @command{readmsg}.
137
138Following configuration statements affect the behavior of
139@command{readmsg}:
140
141@deffn {Readmsg Conf} header @var{bool}
142If @var{bool} is @samp{true}, display entire headers.
143@end deffn
144
145@deffn {Readmsg Conf} weedlist @var{str}
146Set the weedlist.  The @var{str} argument is
147a string, containing a list of header names, separated by whitespace,
148commands or colons.  This corresponds to the @option{--weedlist} command
149line option (@pxref{Opt-readmsg, --weedlist}).
150@end deffn
151
152@deffn {Readmsg Conf} no-header @var{bool}
153If @var{bool} is @samp{true}, exclude all headers.
154@end deffn
155
156@deffn {Readmsg Conf} form-feeds @var{bool}
157If @var{bool} is @samp{true}, output formfeed character between
158messages.
159@end deffn
160
161@deffn {Readmsg Conf} folder @var{url}
162Set the @acronym{URL} of the mailbox folder to read.
163@end deffn
164
165@deffn {Readmsg Conf} show-all-match @var{bool}
166If @var{bool} is @samp{true}, print all messages matching pattern, not
167only the first.
168@end deffn
169
170@multitable @columnfractions 0.3 0.6
171@headitem Statement @tab Reference
172@item debug         @tab @xref{Debug Statement}.
173@item tls           @tab @xref{TLS Statement}.
174@item mailbox       @tab @xref{Mailbox Statement}.
175@item locking       @tab @xref{Locking Statement}.
176@end multitable
177