Update mutt-notmuch
[dotfiles/scripts.git] / mutt-notmuch
1 #!/usr/bin/perl -w
2 #
3 # mutt-notmuch - notmuch (of a) helper for Mutt
4 #
5 # Copyright: © 2011 Stefano Zacchiroli <zack@upsilon.cc> 
6 # License: GNU General Public License (GPL), version 3 or above
7 #
8 # See the bottom of this file for more documentation.
9 # A manpage can be obtained by running "pod2man mutt-notmuch > mutt-notmuch.1"
10
11 use strict;
12 use warnings;
13
14 use File::Path;
15 use Getopt::Long;
16 use Mail::Internet;
17 use Mail::Box::Maildir;
18 use Pod::Usage;
19
20
21 # create an empty maildir (if missing) or empty an existing maildir"
22 sub empty_maildir($) {
23     my ($maildir) = (@_);
24     rmtree($maildir) if (-d $maildir);
25     my $folder = new Mail::Box::Maildir(folder => $maildir,
26                                         create => 1);
27     $folder->close();
28 }
29
30 # search($maildir, $query)
31 # search mails according to $query with notmuch; store results in $maildir
32 sub search($$) {
33     my ($maildir, $query) = @_;
34
35     empty_maildir($maildir);
36     system("notmuch search --output=files $query"
37            . " | sed -e 's: :\\\\ :g'"
38            . " | xargs --no-run-if-empty ln -s -t $maildir/cur/");
39 }
40
41 sub prompt($) {
42     my ($text) = @_;
43     my $query = "";
44     while (1) {
45         print $text;
46         chomp($query = <STDIN>);
47         if ($query eq "?") {
48             system("man notmuch");
49         } else {
50             return $query;
51         }
52     }
53 }
54
55 sub get_message_id() {
56     my $mail = Mail::Internet->new(\*STDIN);
57     $mail->head->get("message-id") =~ /^<(.*)>$/;       # get message-id
58     return $1;
59 }
60
61 sub search_action($$@) {
62     my ($interactive, $results_dir, @params) = @_;
63
64     if (! $interactive) {
65         search($results_dir, join(' ', @params));
66     } else {
67         my $query = prompt("search ('?' for man): ");
68         if ($query ne "") {
69             search($results_dir,$query);
70         }
71     }
72 }
73
74 sub thread_action(@) {
75     my ($results_dir, @params) = @_;
76     my $mid = get_message_id();
77     my $tid = `notmuch search --output=threads id:$mid`;# get thread id
78     chomp($tid);
79
80     search($results_dir, $tid);
81 }
82
83 sub tag_action(@) {
84     my $mid = get_message_id();
85
86     system("notmuch tag ".join(' ', @_)." id:$mid");
87 }
88
89 sub die_usage() {
90     my %podflags = ( "verbose" => 1,
91                     "exitval" => 2 );
92     pod2usage(%podflags);
93 }
94
95 sub main() {
96     my $results_dir = "$ENV{HOME}/.cache/mutt_results";
97     my $interactive = 0;
98     my $help_needed = 0;
99
100     my $getopt = GetOptions(
101         "h|help" => \$help_needed,
102         "o|output-dir=s" => \$results_dir,
103         "p|prompt" => \$interactive);
104     if (! $getopt || $#ARGV < 0) { die_usage() };
105     my ($action, @params) = ($ARGV[0], @ARGV[1..$#ARGV]);
106
107     if ($help_needed) {
108         die_usage();
109     } elsif ($action eq "search" && $#ARGV == 0 && ! $interactive) {
110         print STDERR "Error: no search term provided\n\n";
111         die_usage();
112     } elsif ($action eq "search") {
113         search_action($interactive, $results_dir, @params);
114     } elsif ($action eq "thread") {
115         thread_action($results_dir, @params);
116     } elsif ($action eq "tag") {
117         tag_action(@params);
118     } else {
119         die_usage();
120     }
121 }
122
123 main();
124
125 __END__
126
127 =head1 NAME
128
129 mutt-notmuch - notmuch (of a) helper for Mutt
130
131 =head1 SYNOPSIS
132
133 =over
134
135 =item B<mutt-notmuch> [I<OPTION>]... search [I<SEARCH-TERM>]...
136
137 =item B<mutt-notmuch> [I<OPTION>]... thread < I<MAIL>
138
139 =item B<mutt-notmuch> [I<OPTION>]... tag [I<TAGS>]... < I<MAIL>
140
141 =back
142
143 =head1 DESCRIPTION
144
145 mutt-notmuch is a frontend to the notmuch mail indexer capable of populating
146 maildir with search results.
147
148 =head1 OPTIONS
149
150 =over 4
151
152 =item -o DIR
153
154 =item --output-dir DIR
155
156 Store search results as (symlink) messages under maildir DIR. Beware: DIR will
157 be overwritten. (Default: F<~/.cache/mutt_results/>)
158
159 =item -p
160
161 =item --prompt
162
163 Instead of using command line search terms, prompt the user for them (only for
164 "search").
165
166 =item -h
167
168 =item --help
169
170 Show usage information and exit.
171
172 =back
173
174 =head1 INTEGRATION WITH MUTT
175
176 mutt-notmuch can be used to integrate notmuch with the Mutt mail user agent
177 (unsurprisingly, given the name). To that end, you should define the following
178 macros in your F<~/.muttrc> (replacing F<~/bin/mutt-notmuch> for the actual
179 location of mutt-notmuch on your system):
180
181     macro index <F8> \
182           "<enter-command>unset wait_key<enter><shell-escape>~/bin/mutt-notmuch --prompt search<enter><change-folder-readonly>~/.cache/mutt_results<enter>" \
183           "search mail (using notmuch)"
184     macro index <F9> \
185           "<enter-command>unset wait_key<enter><pipe-message>~/bin/mutt-notmuch thread<enter><change-folder-readonly>~/.cache/mutt_results<enter><enter-command>set wait_key<enter>" \
186           "search and reconstruct owning thread (using notmuch)"
187     macro index <F6> \
188           "<enter-command>unset wait_key<enter><pipe-message>~/bin/mutt-notmuch tag -inbox<enter>" \
189           "remove message from inbox (using notmuch)"
190
191 The first macro (activated by <F8>) will prompt the user for notmuch search
192 terms and then jump to a temporary maildir showing search results. The second
193 macro (activated by <F9>) will reconstruct the thread corresponding to the
194 current mail and show it as search results. The third macro (activated by <F6>)
195 removes the tag C<inbox> from the current message; by changing C<-inbox> this
196 macro may be customised to add or remove tags appropriate to the users notmuch
197 work-flow.
198
199 To keep notmuch index current you should then periodically run C<notmuch
200 new>. Depending on your local mail setup, you might want to do that via cron,
201 as a hook triggered by mail retrieval, etc.
202
203 =head1 SEE ALSO
204
205 mutt(1), notmuch(1)
206
207 =head1 AUTHOR
208
209 Copyright: (C) 2011 Stefano Zacchiroli <zack@upsilon.cc>
210
211 License: GNU General Public License (GPL), version 3 or higher
212
213 =cut