[notmuch] [PATCH] JSON output for notmuch-search and notmuch-show.
Excerpts from Carl Worth's message of Tue Dec 22 21:48:34 -0800 2009: > On Fri, 18 Dec 2009 10:47:33 -0800, Scott Robinson > wrote: > > Resubmit a full patch, or submit another one on top of it? > > A new full patch would be great, thanks! Sadly, I won't be able to make the changes requested. I'm falling off the Internet shortly. Hopefully David, who already put in a couple improvements, can do the finishing touches?
[notmuch] [PATCH] JSON output for notmuch-search and notmuch-show.
On Thu, 31 Dec 2009 00:54:55 -0800, Scott Robinson wrote: > Excerpts from Carl Worth's message of Tue Dec 22 21:48:34 -0800 2009: > > On Fri, 18 Dec 2009 10:47:33 -0800, Scott Robinson > > wrote: > > > Resubmit a full patch, or submit another one on top of it? > > > > A new full patch would be great, thanks! > > Sadly, I won't be able to make the changes requested. I'm falling off the > Internet shortly. > > Hopefully David, who already put in a couple improvements, can do the > finishing > touches? Happy to. Thanks for your big effort so far! d
[notmuch] [PATCH] Add an "--format=(json|text)" command-line option to both notmuch-search and notmuch-show.
From: Scott Robinson
In the case of notmuch-show, "--format=json" also implies
"--entire-thread" as the thread structure is implicit in the emitted
document tree.
As a coincidence to the implementation, multipart message ID numbers are
now incremented with each part printed. This changes the previous
semantics, which were unclear and not necessary related to the actual
ordering of the message parts.
---
This is an updated version of Scott Robinson's patch of
id:1261114167-sup-8228 at lisa. All of the hard work is Scott's. My
changes to Scotts patch are
- change option to --format from --output
- make a couple of calls to function points conditional on the
function pointers being non-null
- updated the built-in documentation and the man page
I also changed the copyright of json.c to Scott. Hope that's OK with
Scott.
Makefile.local |3 +-
json.c | 72 ++
notmuch-client.h |3 +
notmuch-search.c | 163 +---
notmuch-show.c | 278 ++
notmuch.1| 27 +-
notmuch.c| 29 +--
show-message.c |4 +-
8 files changed, 514 insertions(+), 65 deletions(-)
create mode 100644 json.c
diff --git a/Makefile.local b/Makefile.local
index 933ff4c..53b474b 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -18,7 +18,8 @@ notmuch_client_srcs = \
notmuch-tag.c \
notmuch-time.c \
query-string.c \
- show-message.c
+ show-message.c \
+ json.c
notmuch_client_modules = $(notmuch_client_srcs:.c=.o)
notmuch: $(notmuch_client_modules) lib/notmuch.a
diff --git a/json.c b/json.c
new file mode 100644
index 000..3960750
--- /dev/null
+++ b/json.c
@@ -0,0 +1,72 @@
+/* notmuch - Not much of an email program, (just index and search)
+ *
+ * Copyright ?? 2009 Scott Robinson
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see http://www.gnu.org/licenses/ .
+ *
+ * Authors: Scott Robinson
+ *
+ */
+
+#include "notmuch-client.h"
+
+/*
+ * json_quote_str derived from cJSON's print_string_ptr,
+ * Copyright (c) 2009 Dave Gamble
+ */
+
+char *
+json_quote_str(const void *ctx, const char *str)
+{
+const char *ptr;
+char *ptr2;
+char *out;
+int len = 0;
+
+if (!str)
+ return NULL;
+
+for (ptr = str; *ptr; len++, ptr++) {
+ if (*ptr < 32 || *ptr == '\"' || *ptr == '\\')
+ len++;
+}
+
+out = talloc_array (ctx, char, len + 3);
+
+ptr = str;
+ptr2 = out;
+
+*ptr2++ = '\"';
+while (*ptr) {
+ if (*ptr > 31 && *ptr != '\"' && *ptr != '\\') {
+ *ptr2++ = *ptr++;
+ } else {
+ *ptr2++ = '\\';
+ switch (*ptr++) {
+ case '\"': *ptr2++ = '\"'; break;
+ case '\\': *ptr2++ = '\\'; break;
+ case '\b': *ptr2++ = 'b'; break;
+ case '\f': *ptr2++ = 'f'; break;
+ case '\n': *ptr2++ = 'n'; break;
+ case '\r': *ptr2++ = 'r'; break;
+ case '\t': *ptr2++ = 't'; break;
+ default: ptr2--;break;
+ }
+ }
+}
+*ptr2++ = '\"';
+*ptr2++ = '\0';
+
+return out;
+}
diff --git a/notmuch-client.h b/notmuch-client.h
index 50a30fe..7b844b9 100644
--- a/notmuch-client.h
+++ b/notmuch-client.h
@@ -143,6 +143,9 @@ notmuch_status_t
show_message_body (const char *filename,
void (*show_part) (GMimeObject *part, int *part_count));
+char *
+json_quote_str (const void *ctx, const char *str);
+
/* notmuch-config.c */
typedef struct _notmuch_config notmuch_config_t;
diff --git a/notmuch-search.c b/notmuch-search.c
index dc44eb6..482c6e8 100644
--- a/notmuch-search.c
+++ b/notmuch-search.c
@@ -20,8 +20,120 @@
#include "notmuch-client.h"
+typedef struct search_format {
+const char *results_start;
+const char *thread_start;
+void (*thread) (const void *ctx,
+ const char *id,
+ const time_t date,
+ const int matched,
+ const int total,
+ const char *authors,
+ const char *subject);
+const char *tag_start;
+const char *tag;
+const char *tag_sep;
+const char *tag_end;
+const char *thread_se
[notmuch] [PATCH] notmuch.pod: pod version of documentation, converted by rman, massaged by hand.
From: David Bremner
Some places I deleted a bit of the continuity text introducing a
command because I didn't see how to make it work with the slightly
more structured layout.
---
The idea here is to be able to generate the online help and the man page from
one source.
To generate a man page:
pod2man notmuch.pod > notmuch.1
To generate help for a specific notmuch subcommand
podselect -section 'Commands/subcommand.*' notmuch.pod | pod2text -c
In principle the output from podselect could be compiled into notmuch.
I'm not sure if the terminal escape codes are a good idea or not for
that application, but they make pretty output.
podselect and pod2man are included with perl 5.10.0; I'm not sure
before that.
notmuch.pod | 344 +++
1 files changed, 344 insertions(+), 0 deletions(-)
create mode 100644 notmuch.pod
diff --git a/notmuch.pod b/notmuch.pod
new file mode 100644
index 000..680b5af
--- /dev/null
+++ b/notmuch.pod
@@ -0,0 +1,344 @@
+=head1 Name
+notmuch - thread-based email index, search, and tagging
+
+=head1 Synopsis
+
+=over
+
+=item B I [I ...]
+
+=back
+
+=head1 Description
+
+Notmuch is a command-line based
+program for indexing, searching, reading, and tagging large collections
+of email messages.
+ The quickest way to get started with Notmuch is to simply
+invoke the B command with no arguments, which will interactively
+guide you through the process of indexing your mail.
+
+=head1 Note
+
+While the command-line
+program B provides powerful functionality, it does not provide the
+most convenient interface for that functionality. More sophisticated interfaces
+are expected to be built on top of either the command-line interface, or
+more likely, on top of the notmuch library interface. See
http://notmuchmail.org
+for more about alternate interfaces to notmuch.
+
+=head1 Commands
+
+=head2 setup
+
+Interactively sets up notmuch for first use. The setup command will
+prompt for your full name, your primary email address, any alternate
+email addresses you use, and the directory containing your email
+archives. Your answers will be written to a configuration file in
+${NOTMUCH_CONFIG} (if set) or ${HOME}/.notmuch-config . This
+configuration file will be created with descriptive comments, making
+it easy to edit by hand later to change the configuration. Or you can
+run B again to change the configuration.
+
+The mail directory you specify can contain any number of
+sub-directories and should primarily contain only files with
+individual email messages (eg. maildir or mh archives are perfect). If
+there are other, non-email files (such as indexes maintained by other
+email programs) then notmuch will do its best to detect those and
+ignore them.
+
+Mail storage that uses mbox format, (where one mbox file contains many
+messages), will not work with notmuch. If that's how your mail is
+currently stored, it is recommended you first convert it to maildir
+format with a utility such as mb2md before running B
+
+Invoking B with no command argument will run B if the
+setup command has not previously been completed.
+
+=head2 new
+
+Find and import any new messages to the database. The B command
+scans all sub-directories of the database, performing full-text
+indexing on new messages that are found. Each new message will
+automatically be tagged with both the B and B tags.
+You should run B once after first running B to
create the initial database. The first run may take a long
+time if you have a significant amount of mail (several hundred
+thousand messages or more). Subsequently, you should run B whenever new mail is delivered and you wish to incorporate it
+into the database. These subsequent runs will be much quicker than
+the initial run.
+
+Note:
+B runs (other than the first run) will skip any read-only
directories,
+so you can use that to mark directories that will not receive any new mail
+(and make B even faster).
+Invoking B with no command argument
+will run B if B has previously been completed, but
B has not previously been run.
+Several of the notmuch commands accept
+search terms with a common syntax. See the B section below for
+more details on the supported syntax.
+The B and B commands are
+used to query the email database.
+
+=head2 search [options...] ...
+
+Search for
+messages matching the given search terms, and display as results the threads
+containing the matched messages.
+The output consists of one line per thread,
+giving a thread ID, the date of the newest (or oldest, depending on the
+sort option) matched message in the thread, the number of matched messages
+and total messages in the thread, the names of all participants in the
+thread, and the subject of the newest (or oldest) message.
+Supported options
+for B include
+
+=over
+
+=item B<--sort=>(B|B)
+
+This option can be used
+to present results in either chronological order (B) or reverse
+chronological order (B).
+Note:
[notmuch] [PATCH] Add an "--format=(json|text)" command-line option to both notmuch-search and notmuch-show.
Excerpts from david's message of Thu Dec 31 07:17:40 -0800 2009: > I also changed the copyright of json.c to Scott. Hope that's OK with > Scott. That is totally OK. Thank you for carrying this patch to conclusion! Can't wait to see how notmuch has evolved in six or so months...
Re: [notmuch] [PATCH] JSON output for notmuch-search and notmuch-show.
Excerpts from Carl Worth's message of Tue Dec 22 21:48:34 -0800 2009: > On Fri, 18 Dec 2009 10:47:33 -0800, Scott Robinson wrote: > > Resubmit a full patch, or submit another one on top of it? > > A new full patch would be great, thanks! Sadly, I won't be able to make the changes requested. I'm falling off the Internet shortly. Hopefully David, who already put in a couple improvements, can do the finishing touches? ___ notmuch mailing list notmuch@notmuchmail.org http://notmuchmail.org/mailman/listinfo/notmuch
Re: [notmuch] [PATCH] JSON output for notmuch-search and notmuch-show.
On Thu, 31 Dec 2009 00:54:55 -0800, Scott Robinson wrote: > Excerpts from Carl Worth's message of Tue Dec 22 21:48:34 -0800 2009: > > On Fri, 18 Dec 2009 10:47:33 -0800, Scott Robinson > > wrote: > > > Resubmit a full patch, or submit another one on top of it? > > > > A new full patch would be great, thanks! > > Sadly, I won't be able to make the changes requested. I'm falling off the > Internet shortly. > > Hopefully David, who already put in a couple improvements, can do the > finishing > touches? Happy to. Thanks for your big effort so far! d ___ notmuch mailing list notmuch@notmuchmail.org http://notmuchmail.org/mailman/listinfo/notmuch
[notmuch] [PATCH] Add an "--format=(json|text)" command-line option to both notmuch-search and notmuch-show.
From: Scott Robinson
In the case of notmuch-show, "--format=json" also implies
"--entire-thread" as the thread structure is implicit in the emitted
document tree.
As a coincidence to the implementation, multipart message ID numbers are
now incremented with each part printed. This changes the previous
semantics, which were unclear and not necessary related to the actual
ordering of the message parts.
---
This is an updated version of Scott Robinson's patch of
id:1261114167-sup-8...@lisa. All of the hard work is Scott's. My
changes to Scotts patch are
- change option to --format from --output
- make a couple of calls to function points conditional on the
function pointers being non-null
- updated the built-in documentation and the man page
I also changed the copyright of json.c to Scott. Hope that's OK with
Scott.
Makefile.local |3 +-
json.c | 72 ++
notmuch-client.h |3 +
notmuch-search.c | 163 +---
notmuch-show.c | 278 ++
notmuch.1| 27 +-
notmuch.c| 29 +--
show-message.c |4 +-
8 files changed, 514 insertions(+), 65 deletions(-)
create mode 100644 json.c
diff --git a/Makefile.local b/Makefile.local
index 933ff4c..53b474b 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -18,7 +18,8 @@ notmuch_client_srcs = \
notmuch-tag.c \
notmuch-time.c \
query-string.c \
- show-message.c
+ show-message.c \
+ json.c
notmuch_client_modules = $(notmuch_client_srcs:.c=.o)
notmuch: $(notmuch_client_modules) lib/notmuch.a
diff --git a/json.c b/json.c
new file mode 100644
index 000..3960750
--- /dev/null
+++ b/json.c
@@ -0,0 +1,72 @@
+/* notmuch - Not much of an email program, (just index and search)
+ *
+ * Copyright © 2009 Scott Robinson
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see http://www.gnu.org/licenses/ .
+ *
+ * Authors: Scott Robinson
+ *
+ */
+
+#include "notmuch-client.h"
+
+/*
+ * json_quote_str derived from cJSON's print_string_ptr,
+ * Copyright (c) 2009 Dave Gamble
+ */
+
+char *
+json_quote_str(const void *ctx, const char *str)
+{
+const char *ptr;
+char *ptr2;
+char *out;
+int len = 0;
+
+if (!str)
+ return NULL;
+
+for (ptr = str; *ptr; len++, ptr++) {
+ if (*ptr < 32 || *ptr == '\"' || *ptr == '\\')
+ len++;
+}
+
+out = talloc_array (ctx, char, len + 3);
+
+ptr = str;
+ptr2 = out;
+
+*ptr2++ = '\"';
+while (*ptr) {
+ if (*ptr > 31 && *ptr != '\"' && *ptr != '\\') {
+ *ptr2++ = *ptr++;
+ } else {
+ *ptr2++ = '\\';
+ switch (*ptr++) {
+ case '\"': *ptr2++ = '\"'; break;
+ case '\\': *ptr2++ = '\\'; break;
+ case '\b': *ptr2++ = 'b'; break;
+ case '\f': *ptr2++ = 'f'; break;
+ case '\n': *ptr2++ = 'n'; break;
+ case '\r': *ptr2++ = 'r'; break;
+ case '\t': *ptr2++ = 't'; break;
+ default: ptr2--;break;
+ }
+ }
+}
+*ptr2++ = '\"';
+*ptr2++ = '\0';
+
+return out;
+}
diff --git a/notmuch-client.h b/notmuch-client.h
index 50a30fe..7b844b9 100644
--- a/notmuch-client.h
+++ b/notmuch-client.h
@@ -143,6 +143,9 @@ notmuch_status_t
show_message_body (const char *filename,
void (*show_part) (GMimeObject *part, int *part_count));
+char *
+json_quote_str (const void *ctx, const char *str);
+
/* notmuch-config.c */
typedef struct _notmuch_config notmuch_config_t;
diff --git a/notmuch-search.c b/notmuch-search.c
index dc44eb6..482c6e8 100644
--- a/notmuch-search.c
+++ b/notmuch-search.c
@@ -20,8 +20,120 @@
#include "notmuch-client.h"
+typedef struct search_format {
+const char *results_start;
+const char *thread_start;
+void (*thread) (const void *ctx,
+ const char *id,
+ const time_t date,
+ const int matched,
+ const int total,
+ const char *authors,
+ const char *subject);
+const char *tag_start;
+const char *tag;
+const char *tag_sep;
+const char *tag_end;
+const char *thread_
[notmuch] [PATCH] notmuch.pod: pod version of documentation, converted by rman, massaged by hand.
From: David Bremner
Some places I deleted a bit of the continuity text introducing a
command because I didn't see how to make it work with the slightly
more structured layout.
---
The idea here is to be able to generate the online help and the man page from
one source.
To generate a man page:
pod2man notmuch.pod > notmuch.1
To generate help for a specific notmuch subcommand
podselect -section 'Commands/subcommand.*' notmuch.pod | pod2text -c
In principle the output from podselect could be compiled into notmuch.
I'm not sure if the terminal escape codes are a good idea or not for
that application, but they make pretty output.
podselect and pod2man are included with perl 5.10.0; I'm not sure
before that.
notmuch.pod | 344 +++
1 files changed, 344 insertions(+), 0 deletions(-)
create mode 100644 notmuch.pod
diff --git a/notmuch.pod b/notmuch.pod
new file mode 100644
index 000..680b5af
--- /dev/null
+++ b/notmuch.pod
@@ -0,0 +1,344 @@
+=head1 Name
+notmuch - thread-based email index, search, and tagging
+
+=head1 Synopsis
+
+=over
+
+=item B I [I ...]
+
+=back
+
+=head1 Description
+
+Notmuch is a command-line based
+program for indexing, searching, reading, and tagging large collections
+of email messages.
+ The quickest way to get started with Notmuch is to simply
+invoke the B command with no arguments, which will interactively
+guide you through the process of indexing your mail.
+
+=head1 Note
+
+While the command-line
+program B provides powerful functionality, it does not provide the
+most convenient interface for that functionality. More sophisticated interfaces
+are expected to be built on top of either the command-line interface, or
+more likely, on top of the notmuch library interface. See
http://notmuchmail.org
+for more about alternate interfaces to notmuch.
+
+=head1 Commands
+
+=head2 setup
+
+Interactively sets up notmuch for first use. The setup command will
+prompt for your full name, your primary email address, any alternate
+email addresses you use, and the directory containing your email
+archives. Your answers will be written to a configuration file in
+${NOTMUCH_CONFIG} (if set) or ${HOME}/.notmuch-config . This
+configuration file will be created with descriptive comments, making
+it easy to edit by hand later to change the configuration. Or you can
+run B again to change the configuration.
+
+The mail directory you specify can contain any number of
+sub-directories and should primarily contain only files with
+individual email messages (eg. maildir or mh archives are perfect). If
+there are other, non-email files (such as indexes maintained by other
+email programs) then notmuch will do its best to detect those and
+ignore them.
+
+Mail storage that uses mbox format, (where one mbox file contains many
+messages), will not work with notmuch. If that's how your mail is
+currently stored, it is recommended you first convert it to maildir
+format with a utility such as mb2md before running B
+
+Invoking B with no command argument will run B if the
+setup command has not previously been completed.
+
+=head2 new
+
+Find and import any new messages to the database. The B command
+scans all sub-directories of the database, performing full-text
+indexing on new messages that are found. Each new message will
+automatically be tagged with both the B and B tags.
+You should run B once after first running B to
create the initial database. The first run may take a long
+time if you have a significant amount of mail (several hundred
+thousand messages or more). Subsequently, you should run B whenever new mail is delivered and you wish to incorporate it
+into the database. These subsequent runs will be much quicker than
+the initial run.
+
+Note:
+B runs (other than the first run) will skip any read-only
directories,
+so you can use that to mark directories that will not receive any new mail
+(and make B even faster).
+Invoking B with no command argument
+will run B if B has previously been completed, but
B has not previously been run.
+Several of the notmuch commands accept
+search terms with a common syntax. See the B section below for
+more details on the supported syntax.
+The B and B commands are
+used to query the email database.
+
+=head2 search [options...] ...
+
+Search for
+messages matching the given search terms, and display as results the threads
+containing the matched messages.
+The output consists of one line per thread,
+giving a thread ID, the date of the newest (or oldest, depending on the
+sort option) matched message in the thread, the number of matched messages
+and total messages in the thread, the names of all participants in the
+thread, and the subject of the newest (or oldest) message.
+Supported options
+for B include
+
+=over
+
+=item B<--sort=>(B|B)
+
+This option can be used
+to present results in either chronological order (B) or reverse
+chronological order (B).
+Not
Re: [notmuch] [PATCH] Add an "--format=(json|text)" command-line option to both notmuch-search and notmuch-show.
Excerpts from david's message of Thu Dec 31 07:17:40 -0800 2009: > I also changed the copyright of json.c to Scott. Hope that's OK with > Scott. That is totally OK. Thank you for carrying this patch to conclusion! Can't wait to see how notmuch has evolved in six or so months... ___ notmuch mailing list notmuch@notmuchmail.org http://notmuchmail.org/mailman/listinfo/notmuch
