From 8f5be32912920c2c5eca7084885c0e2498540311 Mon Sep 17 00:00:00 2001
From: Stefano Zacchiroli <zack@upsilon.cc>
Date: Sun, 25 Mar 2012 15:55:44 +0200
Subject: [PATCH] contrib: new utility mutt-notmuch for Mutt integration

---
 contrib/mutt-notmuch/Makefile       |   12 ++
 contrib/mutt-notmuch/README         |   58 +++++++++
 contrib/mutt-notmuch/mutt-notmuch   |  234 +++++++++++++++++++++++++++++++++++
 contrib/mutt-notmuch/mutt-notmuch.1 |  210 +++++++++++++++++++++++++++++++
 4 files changed, 514 insertions(+), 0 deletions(-)
 create mode 100644 contrib/mutt-notmuch/Makefile
 create mode 100644 contrib/mutt-notmuch/README
 create mode 100755 contrib/mutt-notmuch/mutt-notmuch
 create mode 100644 contrib/mutt-notmuch/mutt-notmuch.1

diff --git a/contrib/mutt-notmuch/Makefile b/contrib/mutt-notmuch/Makefile
new file mode 100644
index 0000000..b78953d
--- /dev/null
+++ b/contrib/mutt-notmuch/Makefile
@@ -0,0 +1,12 @@
+NAME = mutt-notmuch
+
+all: $(NAME) $(NAME).1
+
+$(NAME).1: $(NAME)
+	pod2man $< > $@
+
+README.html: README
+	markdown $< > $@
+
+clean:
+	rm -f mutt-notmuch.1 README.html
diff --git a/contrib/mutt-notmuch/README b/contrib/mutt-notmuch/README
new file mode 100644
index 0000000..e72aa91
--- /dev/null
+++ b/contrib/mutt-notmuch/README
@@ -0,0 +1,58 @@
+mutt-notmuch: Notmuch (of a) helper for Mutt
+============================================
+
+mutt-notmuch provide integration among the [Mutt] [1] mail user agent and the
+[Notmuch] [2] mail indexer.
+
+mutt-notmuch offer two basic integration features. The first one is the ability
+of stating a **search query interactively** and then jump to a fresh Maildir
+containing its search results only. The second one is the ability to
+**reconstruct threads on the fly** starting from the currently highlighted
+mail, which comes handy when a thread has been split across different maildirs,
+archived, or the like.
+
+mutt-notmuch enables to trigger mail searches via a Mutt macro (F8 being my
+choice) and reconstruct threads via another (F9). Check the manpage for the
+2-liner configuration snippet for your ~/.muttrc.
+
+A [blog style introduction] [3] to mutt-notmuch is available and includes some
+more rationale for its existence.
+
+Arguably, some of the logics of mutt-notmuch could disappear by adding support
+for a --output=symlinks flag to notmuch.
+
+
+[1]: http://www.mutt.org/
+[2]: http://notmuchmail.org/
+[3]: http://upsilon.cc/~zack/blog/posts/2011/01/how_to_use_Notmuch_with_Mutt/
+
+
+Requirements
+------------
+
+To *run* mutt-notmuch you will need Perl with the following libraries:
+
+- Mail::Box <http://search.cpan.org/~markov/Mail-Box/>
+  (Debian package: libmail-box-perl)
+- Mail::Internet <http://search.cpan.org/~markov/MailTools/>
+  (Debian package: libmailtools-perl)
+- String::ShellQuote <http://search.cpan.org/~rosch/String-ShellQuote/ShellQuote.pm>
+  (Debian package: libstring-shellquote-perl)
+- Term::ReadLine <http://search.cpan.org/~hayashi/Term-ReadLine-Gnu/>
+  (Debian package: libterm-readline-gnu-perl)
+
+To *build* mutt-notmuch documentation you will need:
+
+- pod2man (coming with Perl) to generate the manpage
+- markdown to generate README.html out of this file
+
+
+License
+-------
+
+mutt-notmuch is copyright (C) 2011-2012 Stefano Zacchiroli <zack@upsilon.cc>.
+
+mutt-notmuch is released under the terms of the GNU General Public License
+(GPL), version 3 or above. A copy of the license is available online at
+<http://www.gnu.org/licenses/>.
+
diff --git a/contrib/mutt-notmuch/mutt-notmuch b/contrib/mutt-notmuch/mutt-notmuch
new file mode 100755
index 0000000..31cb539
--- /dev/null
+++ b/contrib/mutt-notmuch/mutt-notmuch
@@ -0,0 +1,234 @@
+#!/usr/bin/perl -w
+#
+# mutt-notmuch - notmuch (of a) helper for Mutt
+#
+# Copyright: © 2011-2012 Stefano Zacchiroli <zack@upsilon.cc> 
+# License: GNU General Public License (GPL), version 3 or above
+#
+# See the bottom of this file for more documentation.
+# A manpage can be obtained by running "pod2man mutt-notmuch > mutt-notmuch.1"
+
+use strict;
+use warnings;
+
+use File::Path;
+use Getopt::Long qw(:config no_getopt_compat);
+use Mail::Internet;
+use Mail::Box::Maildir;
+use Pod::Usage;
+use String::ShellQuote;
+use Term::ReadLine;
+
+
+# create an empty maildir (if missing) or empty an existing maildir"
+sub empty_maildir($) {
+    my ($maildir) = (@_);
+    rmtree($maildir) if (-d $maildir);
+    my $folder = new Mail::Box::Maildir(folder => $maildir,
+					create => 1);
+    $folder->close();
+}
+
+# search($maildir, $query)
+# search mails according to $query with notmuch; store results in $maildir
+sub search($$) {
+    my ($maildir, $query) = @_;
+    $query = shell_quote($query);
+
+    empty_maildir($maildir);
+    system("notmuch search --output=files $query"
+	   . " | sed -e 's: :\\\\ :g'"
+	   . " | xargs --no-run-if-empty ln -s -t $maildir/cur/");
+}
+
+sub prompt($$) {
+    my ($text, $default) = @_;
+    my $query = "";
+    my $term = Term::ReadLine->new( "mutt-notmuch" );
+    $term->ornaments( 0 );
+    $term->unbind_key( ord( "\t" ) );
+    $term->MinLine( 3 );
+    if ($ENV{MUTT_NOTMUCH_HISTFILE} && -r "$ENV{MUTT_NOTMUCH_HISTFILE}") {
+      $term->ReadHistory("$ENV{MUTT_NOTMUCH_HISTFILE}");
+    } elsif (-r "$ENV{HOME}/.mutt-notmuch.history") {
+      $term->ReadHistory("$ENV{HOME}/.mutt-notmuch.history");
+    }
+    while (1) {
+	chomp($query = $term->readline($text, $default));
+	if ($query eq "?") {
+	    system("man", "notmuch");
+	} else {
+       if (!$ENV{MUTT_NOTMUCH_HISTFILE} ||
+           !$term->WriteHistory("$ENV{MUTT_NOTMUCH_HISTFILE}")) {
+         $term->WriteHistory("$ENV{HOME}/.mutt-notmuch.history");
+       }
+	    return $query;
+	}
+    }
+}
+
+sub get_message_id() {
+    my $mail = Mail::Internet->new(\*STDIN);
+    $mail->head->get("message-id") =~ /^<(.*)>$/;	# get message-id
+    return $1;
+}
+
+sub search_action($$@) {
+    my ($interactive, $results_dir, @params) = @_;
+
+    if (! $interactive) {
+	search($results_dir, join(' ', @params));
+    } else {
+	my $query = prompt("search ('?' for man): ", join(' ', @params));
+	if ($query ne "") {
+	    search($results_dir,$query);
+	}
+    }
+}
+
+sub thread_action(@) {
+    my ($results_dir, @params) = @_;
+    my $mid = get_message_id();
+    my $tid = `notmuch search --output=threads id:$mid`;# get thread id
+    chomp($tid);
+
+    search($results_dir, $tid);
+}
+
+sub tag_action(@) {
+    my $mid = get_message_id();
+
+    system("notmuch tag "
+	   . shell_quote(join(' ', @_))
+	   . " id:$mid");
+}
+
+sub die_usage() {
+    my %podflags = ( "verbose" => 1,
+		    "exitval" => 2 );
+    pod2usage(%podflags);
+}
+
+sub main() {
+    my $results_dir = "$ENV{HOME}/.cache/mutt_results";
+    my $interactive = 0;
+    my $help_needed = 0;
+
+    my $getopt = GetOptions(
+	"h|help" => \$help_needed,
+	"o|output-dir=s" => \$results_dir,
+	"p|prompt" => \$interactive);
+    if (! $getopt || $#ARGV < 0) { die_usage() };
+    my ($action, @params) = ($ARGV[0], @ARGV[1..$#ARGV]);
+
+    foreach my $param (@params) {
+      $param =~ s/folder:=/folder:/g;
+    }
+
+    if ($help_needed) {
+	die_usage();
+    } elsif ($action eq "search" && $#ARGV == 0 && ! $interactive) {
+	print STDERR "Error: no search term provided\n\n";
+	die_usage();
+    } elsif ($action eq "search") {
+	search_action($interactive, $results_dir, @params);
+    } elsif ($action eq "thread") {
+	thread_action($results_dir, @params);
+    } elsif ($action eq "tag") {
+	tag_action(@params);
+    } else {
+	die_usage();
+    }
+}
+
+main();
+
+__END__
+
+=head1 NAME
+
+mutt-notmuch - notmuch (of a) helper for Mutt
+
+=head1 SYNOPSIS
+
+=over
+
+=item B<mutt-notmuch> [I<OPTION>]... search [I<SEARCH-TERM>]...
+
+=item B<mutt-notmuch> [I<OPTION>]... thread < I<MAIL>
+
+=item B<mutt-notmuch> [I<OPTION>]... tag [I<TAGS>]... < I<MAIL>
+
+=back
+
+=head1 DESCRIPTION
+
+mutt-notmuch is a frontend to the notmuch mail indexer capable of populating
+maildir with search results.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -o DIR
+
+=item --output-dir DIR
+
+Store search results as (symlink) messages under maildir DIR. Beware: DIR will
+be overwritten. (Default: F<~/.cache/mutt_results/>)
+
+=item -p
+
+=item --prompt
+
+Instead of using command line search terms, prompt the user for them (only for
+"search").
+
+=item -h
+
+=item --help
+
+Show usage information and exit.
+
+=back
+
+=head1 INTEGRATION WITH MUTT
+
+mutt-notmuch can be used to integrate notmuch with the Mutt mail user agent
+(unsurprisingly, given the name). To that end, you should define the following
+macros in your F<~/.muttrc> (replacing F<~/bin/mutt-notmuch> for the actual
+location of mutt-notmuch on your system):
+
+    macro index <F8> \
+          "<enter-command>unset wait_key<enter><shell-escape>~/bin/mutt-notmuch --prompt search<enter><change-folder-readonly>~/.cache/mutt_results<enter>" \
+          "search mail (using notmuch)"
+    macro index <F9> \
+          "<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>" \
+          "search and reconstruct owning thread (using notmuch)"
+    macro index <F6> \
+          "<enter-command>unset wait_key<enter><pipe-message>~/bin/mutt-notmuch tag -inbox<enter>" \
+          "remove message from inbox (using notmuch)"
+
+The first macro (activated by <F8>) will prompt the user for notmuch search
+terms and then jump to a temporary maildir showing search results. The second
+macro (activated by <F9>) will reconstruct the thread corresponding to the
+current mail and show it as search results. The third macro (activated by <F6>)
+removes the tag C<inbox> from the current message; by changing C<-inbox> this
+macro may be customised to add or remove tags appropriate to the users notmuch
+work-flow.
+
+To keep notmuch index current you should then periodically run C<notmuch
+new>. Depending on your local mail setup, you might want to do that via cron,
+as a hook triggered by mail retrieval, etc.
+
+=head1 SEE ALSO
+
+mutt(1), notmuch(1)
+
+=head1 AUTHOR
+
+Copyright: (C) 2011-2012 Stefano Zacchiroli <zack@upsilon.cc>
+
+License: GNU General Public License (GPL), version 3 or higher
+
+=cut
diff --git a/contrib/mutt-notmuch/mutt-notmuch.1 b/contrib/mutt-notmuch/mutt-notmuch.1
new file mode 100644
index 0000000..fe5e653
--- /dev/null
+++ b/contrib/mutt-notmuch/mutt-notmuch.1
@@ -0,0 +1,210 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.el \{\
+.    de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "MUTT-NOTMUCH 1"
+.TH MUTT-NOTMUCH 1 "2012-03-25" "perl v5.14.2" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+mutt\-notmuch \- notmuch (of a) helper for Mutt
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.IP "\fBmutt-notmuch\fR [\fI\s-1OPTION\s0\fR]... search [\fISEARCH-TERM\fR]..." 4
+.IX Item "mutt-notmuch [OPTION]... search [SEARCH-TERM]..."
+.PD 0
+.IP "\fBmutt-notmuch\fR [\fI\s-1OPTION\s0\fR]... thread < \fI\s-1MAIL\s0\fR" 4
+.IX Item "mutt-notmuch [OPTION]... thread < MAIL"
+.IP "\fBmutt-notmuch\fR [\fI\s-1OPTION\s0\fR]... tag [\fI\s-1TAGS\s0\fR]... < \fI\s-1MAIL\s0\fR" 4
+.IX Item "mutt-notmuch [OPTION]... tag [TAGS]... < MAIL"
+.PD
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+mutt-notmuch is a frontend to the notmuch mail indexer capable of populating
+maildir with search results.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\-o \s-1DIR\s0" 4
+.IX Item "-o DIR"
+.PD 0
+.IP "\-\-output\-dir \s-1DIR\s0" 4
+.IX Item "--output-dir DIR"
+.PD
+Store search results as (symlink) messages under maildir \s-1DIR\s0. Beware: \s-1DIR\s0 will
+be overwritten. (Default: \fI~/.cache/mutt_results/\fR)
+.IP "\-p" 4
+.IX Item "-p"
+.PD 0
+.IP "\-\-prompt" 4
+.IX Item "--prompt"
+.PD
+Instead of using command line search terms, prompt the user for them (only for
+\&\*(L"search\*(R").
+.IP "\-h" 4
+.IX Item "-h"
+.PD 0
+.IP "\-\-help" 4
+.IX Item "--help"
+.PD
+Show usage information and exit.
+.SH "INTEGRATION WITH MUTT"
+.IX Header "INTEGRATION WITH MUTT"
+mutt-notmuch can be used to integrate notmuch with the Mutt mail user agent
+(unsurprisingly, given the name). To that end, you should define the following
+macros in your \fI~/.muttrc\fR (replacing \fI~/bin/mutt\-notmuch\fR for the actual
+location of mutt-notmuch on your system):
+.PP
+.Vb 9
+\&    macro index <F8> \e
+\&          "<enter\-command>unset wait_key<enter><shell\-escape>~/bin/mutt\-notmuch \-\-prompt search<enter><change\-folder\-readonly>~/.cache/mutt_results<enter>" \e
+\&          "search mail (using notmuch)"
+\&    macro index <F9> \e
+\&          "<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>" \e
+\&          "search and reconstruct owning thread (using notmuch)"
+\&    macro index <F6> \e
+\&          "<enter\-command>unset wait_key<enter><pipe\-message>~/bin/mutt\-notmuch tag \-inbox<enter>" \e
+\&          "remove message from inbox (using notmuch)"
+.Ve
+.PP
+The first macro (activated by <F8>) will prompt the user for notmuch search
+terms and then jump to a temporary maildir showing search results. The second
+macro (activated by <F9>) will reconstruct the thread corresponding to the
+current mail and show it as search results. The third macro (activated by <F6>)
+removes the tag \f(CW\*(C`inbox\*(C'\fR from the current message; by changing \f(CW\*(C`\-inbox\*(C'\fR this
+macro may be customised to add or remove tags appropriate to the users notmuch
+work-flow.
+.PP
+To keep notmuch index current you should then periodically run \f(CW\*(C`notmuch
+new\*(C'\fR. Depending on your local mail setup, you might want to do that via cron,
+as a hook triggered by mail retrieval, etc.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fImutt\fR\|(1), \fInotmuch\fR\|(1)
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+Copyright: (C) 2011\-2012 Stefano Zacchiroli <zack@upsilon.cc>
+.PP
+License: \s-1GNU\s0 General Public License (\s-1GPL\s0), version 3 or higher
-- 
1.7.9.1