From d13810dc1e044446ad5eb85474c87e20924f9473 Mon Sep 17 00:00:00 2001 From: Stefano Zacchiroli Date: Mon, 26 Mar 2012 10:45:58 +0200 Subject: [PATCH] contrib: new mutt-notmuch utility for Mutt integration --- contrib/notmuch-mutt/.gitignore | 2 + contrib/notmuch-mutt/Makefile | 12 ++ contrib/notmuch-mutt/README | 59 +++++++ contrib/notmuch-mutt/notmuch-mutt | 238 +++++++++++++++++++++++++++ contrib/notmuch-mutt/notmuch-mutt.rc | 9 + 5 files changed, 320 insertions(+) create mode 100644 contrib/notmuch-mutt/.gitignore create mode 100644 contrib/notmuch-mutt/Makefile create mode 100644 contrib/notmuch-mutt/README create mode 100755 contrib/notmuch-mutt/notmuch-mutt create mode 100644 contrib/notmuch-mutt/notmuch-mutt.rc diff --git a/contrib/notmuch-mutt/.gitignore b/contrib/notmuch-mutt/.gitignore new file mode 100644 index 00000000..682a5779 --- /dev/null +++ b/contrib/notmuch-mutt/.gitignore @@ -0,0 +1,2 @@ +notmuch-mutt.1 +README.html diff --git a/contrib/notmuch-mutt/Makefile b/contrib/notmuch-mutt/Makefile new file mode 100644 index 00000000..87f9031c --- /dev/null +++ b/contrib/notmuch-mutt/Makefile @@ -0,0 +1,12 @@ +NAME = notmuch-mutt + +all: $(NAME) $(NAME).1 + +$(NAME).1: $(NAME) + pod2man $< > $@ + +README.html: README + markdown $< > $@ + +clean: + rm -f notmuch-mutt.1 README.html diff --git a/contrib/notmuch-mutt/README b/contrib/notmuch-mutt/README new file mode 100644 index 00000000..382ac911 --- /dev/null +++ b/contrib/notmuch-mutt/README @@ -0,0 +1,59 @@ +notmuch-mutt: Notmuch (of a) helper for Mutt +============================================ + +notmuch-mutt provide integration among the [Mutt] [1] mail user agent and the +[Notmuch] [2] mail indexer. + +notmuch-mutt offer two main 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. + +notmuch-mutt enables to trigger mail searches via a Mutt macro (usually F8) and +reconstruct threads via another (usually F9). Check the manpage for the 2-liner +configuration snippet for your Mutt configuration files (~/.muttrc, +/etc/Muttrc, or a /etc/Muttrc.d snippet). + +A [blog style introduction] [3] to notmuch-mutt is available and includes some +more rationale for its existence. + +Arguably, some of the logics of notmuch-mutt 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* notmuch-mutt you will need Perl with the following libraries: + +- Mail::Box + (Debian package: libmail-box-perl) +- Mail::Internet + (Debian package: libmailtools-perl) +- String::ShellQuote + (Debian package: libstring-shellquote-perl) +- Term::ReadLine + (Debian package: libterm-readline-gnu-perl) + +To *build* notmuch-mutt documentation you will need: + +- pod2man (coming with Perl) to generate the manpage +- markdown to generate README.html out of this file + + +License +------- + +notmuch-mutt is copyright (C) 2011-2012 Stefano Zacchiroli . + +notmuch-mutt 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 +. + diff --git a/contrib/notmuch-mutt/notmuch-mutt b/contrib/notmuch-mutt/notmuch-mutt new file mode 100755 index 00000000..9176ed51 --- /dev/null +++ b/contrib/notmuch-mutt/notmuch-mutt @@ -0,0 +1,238 @@ +#!/usr/bin/perl -w +# +# notmuch-mutt - notmuch (of a) helper for Mutt +# +# Copyright: © 2011-2012 Stefano Zacchiroli +# 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 notmuch-mutt > notmuch-mutt.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; + + +my $xdg_cache_dir = "$ENV{HOME}/.cache"; +$xdg_cache_dir = $ENV{XDG_CACHE_HOME} if $ENV{XDG_CACHE_HOME}; +my $cache_dir = "$xdg_cache_dir/notmuch/mutt"; + + +# 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( "notmuch-mutt" ); + my $histfile = "$cache_dir/history"; + + $term->ornaments( 0 ); + $term->unbind_key( ord( "\t" ) ); + $term->MinLine( 3 ); + $histfile = $ENV{MUTT_NOTMUCH_HISTFILE} if $ENV{MUTT_NOTMUCH_HISTFILE}; + $term->ReadHistory($histfile) if (-r $histfile); + while (1) { + chomp($query = $term->readline($text, $default)); + if ($query eq "?") { + system("man", "notmuch"); + } else { + $term->WriteHistory($histfile); + 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 $search_cmd = 'notmuch search --output=threads ' . shell_quote("id:$mid"); + my $tid = `$search_cmd`; # 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() { + mkpath($cache_dir) unless (-d $cache_dir); + + my $results_dir = "$cache_dir/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 + +notmuch-mutt - notmuch (of a) helper for Mutt + +=head1 SYNOPSIS + +=over + +=item B [I