1 Return-Path: <amthrax@drake.mit.edu>
\r
2 X-Original-To: notmuch@notmuchmail.org
\r
3 Delivered-To: notmuch@notmuchmail.org
\r
4 Received: from localhost (localhost [127.0.0.1])
\r
5 by olra.theworths.org (Postfix) with ESMTP id 674EE429E31
\r
6 for <notmuch@notmuchmail.org>; Tue, 14 Feb 2012 09:34:02 -0800 (PST)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5
\r
12 tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled
\r
13 Received: from olra.theworths.org ([127.0.0.1])
\r
14 by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
\r
15 with ESMTP id xUeE7P45OOid for <notmuch@notmuchmail.org>;
\r
16 Tue, 14 Feb 2012 09:33:59 -0800 (PST)
\r
17 Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU
\r
19 by olra.theworths.org (Postfix) with ESMTP id 9BEAB431FBC
\r
20 for <notmuch@notmuchmail.org>; Tue, 14 Feb 2012 09:33:56 -0800 (PST)
\r
21 X-AuditID: 12074425-b7f4a6d0000008e0-a0-4f3a9b038ca9
\r
22 Received: from mailhub-auth-4.mit.edu ( [18.7.62.39])
\r
23 by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP
\r
24 id D0.E3.02272.30B9A3F4; Tue, 14 Feb 2012 12:33:55 -0500 (EST)
\r
25 Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])
\r
26 by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id q1EHXtRI019622;
\r
27 Tue, 14 Feb 2012 12:33:55 -0500
\r
28 Received: from drake.mit.edu
\r
29 (209-6-116-242.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com
\r
30 [209.6.116.242]) (authenticated bits=0)
\r
31 (User authenticated as amdragon@ATHENA.MIT.EDU)
\r
32 by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q1EHXr3j016486
\r
33 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);
\r
34 Tue, 14 Feb 2012 12:33:54 -0500 (EST)
\r
35 Received: from amthrax by drake.mit.edu with local (Exim 4.77)
\r
36 (envelope-from <amthrax@drake.mit.edu>)
\r
37 id 1RxMGH-000271-7w; Tue, 14 Feb 2012 12:33:53 -0500
\r
38 From: Austin Clements <amdragon@MIT.EDU>
\r
39 To: notmuch@notmuchmail.org
\r
40 Subject: [PATCH 1/8] Document the JSON schemata used by show and search
\r
41 Date: Tue, 14 Feb 2012 12:33:36 -0500
\r
42 Message-Id: <1329240823-7856-2-git-send-email-amdragon@mit.edu>
\r
43 X-Mailer: git-send-email 1.7.7.3
\r
44 In-Reply-To: <1329240823-7856-1-git-send-email-amdragon@mit.edu>
\r
45 References: <1329240823-7856-1-git-send-email-amdragon@mit.edu>
\r
46 X-Brightmail-Tracker:
\r
47 H4sIAAAAAAAAA+NgFjrOIsWRmVeSWpSXmKPExsUixG6nrss828rfoHutlcWRPbPYLa5u7We3
\r
48 uH5zJrMDs8fOWXfZPZ6tusXs0fRjMWsAcxSXTUpqTmZZapG+XQJXRvuqC4wFP9UrenZfYGtg
\r
49 nCXbxcjJISFgInGudR0jhC0mceHeerYuRi4OIYF9jBJXTr1ghHA2MEoc/bCTBcK5zyTx8eId
\r
50 qLL5jBJ3vzwC62cT0JDYtn85mC0iIC2x8+5sVhCbWSBe4kjberC4sIC7xKT/E1lAbBYBVYkf
\r
51 bZfYuxg5OHgF7CVWvGSGOENB4tzqc+wgNqeAg8T+ff/BxggBlVy6u5VlAiP/AkaGVYyyKblV
\r
52 urmJmTnFqcm6xcmJeXmpRboWermZJXqpKaWbGMHh5aK6g3HCIaVDjAIcjEo8vAYWlv5CrIll
\r
53 xZW5hxglOZiURHmFZ1j5C/El5adUZiQWZ8QXleakFh9ilOBgVhLh3TQdKMebklhZlVqUD5OS
\r
54 5mBREufV1HrnJySQnliSmp2aWpBaBJOV4eBQkuBlmwXUKFiUmp5akZaZU4KQZuLgBBnOAzT8
\r
55 y0yQ4cUFibnFmekQ+VOMilLivG9BEgIgiYzSPLheWPy/YhQHekWYVw5kBQ8wdcB1vwIazAQ0
\r
56 ePtpC5DBJYkIKakGRmN185uzsuS+b+SpP8Cknf/lUAO/V4bQrjMTP+WtSvz5RX3ZRRWhFxed
\r
57 XppVV62WM7jf8nuaPFfZAsfy7Ol/PKa9+3pV6rHgP8aMHTVOU3ztZ63bI+G96ky/s80jW921
\r
58 R1MsPiQ7up1fVa29p7TiwMGdsnlP51Wv/RH1d7m1XMP1s/wzslNvpymxFGckGmoxFxUnAgDD
\r
60 X-BeenThere: notmuch@notmuchmail.org
\r
61 X-Mailman-Version: 2.1.13
\r
63 List-Id: "Use and development of the notmuch mail system."
\r
64 <notmuch.notmuchmail.org>
\r
65 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
66 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
67 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
68 List-Post: <mailto:notmuch@notmuchmail.org>
\r
69 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
70 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
71 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
72 X-List-Received-Date: Tue, 14 Feb 2012 17:34:03 -0000
\r
75 devel/schemata | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
\r
76 notmuch-search.c | 3 +
\r
77 notmuch-show.c | 2 +
\r
78 3 files changed, 140 insertions(+), 0 deletions(-)
\r
79 create mode 100644 devel/schemata
\r
81 diff --git a/devel/schemata b/devel/schemata
\r
82 new file mode 100644
\r
83 index 0000000..d90d4c6
\r
85 +++ b/devel/schemata
\r
87 +This file describes the schemata used for notmuch's structured output
\r
88 +format (currently JSON).
\r
90 +[]'s indicate lists. List items can be marked with a '?', meaning
\r
91 +they are optional; or a '*', meaning there can be zero or more of that
\r
92 +item. {}'s indicate an object that maps from field identifiers to
\r
93 +values. An object field marked '?' is optional. |'s indicate
\r
94 +alternates (e.g., int|string means something can be an int or a
\r
97 +Common non-terminals
\r
98 +--------------------
\r
100 +# Number of seconds since the Epoch
\r
103 +# Thread ID, sans "thread:"
\r
106 +# Message ID, sans "id:"
\r
107 +messageid = string
\r
109 +notmuch show schema
\r
110 +-------------------
\r
112 +# A top-level set of threads (do_show)
\r
113 +# Returned by notmuch show without a --part argument
\r
114 +thread_set = [thread*]
\r
116 +# Top-level messages in a thread (show_messages)
\r
117 +thread = [thread_node*]
\r
119 +# A message and its replies (show_messages)
\r
121 + message?, # present if --entire-thread or matched
\r
122 + [thread_node*] # children of message
\r
125 +# A message (show_message)
\r
127 + # (format_message_json)
\r
130 + filename: string,
\r
131 + timestamp: unix_time, # date header as unix time
\r
132 + date_relative: string, # user-friendly timestamp
\r
135 + headers: headers,
\r
139 +# A MIME part (show_message_body)
\r
141 + # format_part_start_json
\r
142 + id: int|string, # part id (currently DFS part number)
\r
144 + # format_part_encstatus_json
\r
145 + encstatus?: encstatus,
\r
147 + # format_part_sigstatus_json
\r
148 + sigstatus?: sigstatus,
\r
150 + # format_part_content_json
\r
151 + content-type: string,
\r
152 + content-id?: string,
\r
153 + # if content-type starts with "multipart/":
\r
154 + content: [part*],
\r
155 + # if content-type is "message/rfc822":
\r
156 + content: [{headers: headers, body: [part]}],
\r
157 + # otherwise (leaf parts):
\r
158 + filename?: string,
\r
159 + content-charset?: string,
\r
160 + content?: string # pre-fetched body content
\r
163 +# The headers of a message (format_headers_json with raw headers) or
\r
164 +# a part (format_headers_message_part_json with pretty-printed headers)
\r
174 +# Encryption status (format_part_encstatus_json)
\r
175 +encstatus = [{status: "good"|"bad"}]
\r
177 +# Signature status (format_part_sigstatus_json)
\r
178 +sigstatus = [signature*]
\r
181 + # signature_status_to_string
\r
182 + status: "none"|"good"|"bad"|"error"|"unknown",
\r
183 + # if status is "good":
\r
184 + fingerprint?: string,
\r
185 + created?: unix_time,
\r
186 + expires?: unix_time,
\r
188 + # if status is not "good":
\r
190 + # if the signature has errors:
\r
194 +notmuch search schema
\r
195 +---------------------
\r
197 +# --output=summary
\r
198 +summary = [thread*]
\r
200 +# --output=threads
\r
201 +threads = [threadid*]
\r
203 +# --output=messages
\r
204 +messages = [messageid*]
\r
213 + thread: threadid,
\r
214 + timestamp: unix_time,
\r
215 + date_relative: string, # user-friendly timestamp
\r
216 + matched: int, # number of matched messages
\r
217 + total: int, # total messages in thread
\r
218 + authors: string, # comma-separated names with | between
\r
219 + # matched and unmatched
\r
222 diff --git a/notmuch-search.c b/notmuch-search.c
\r
223 index d504051..92ce38a 100644
\r
224 --- a/notmuch-search.c
\r
225 +++ b/notmuch-search.c
\r
226 @@ -90,6 +90,9 @@ format_thread_json (const void *ctx,
\r
228 const char *authors,
\r
229 const char *subject);
\r
231 +/* Any changes to the JSON format should be reflected in the file
\r
232 + * devel/schemata. */
\r
233 static const search_format_t format_json = {
\r
236 diff --git a/notmuch-show.c b/notmuch-show.c
\r
237 index d930f94..93fb16f 100644
\r
238 --- a/notmuch-show.c
\r
239 +++ b/notmuch-show.c
\r
240 @@ -65,6 +65,8 @@ format_part_content_json (GMimeObject *part);
\r
242 format_part_end_json (GMimeObject *part);
\r
244 +/* Any changes to the JSON format should be reflected in the file
\r
245 + * devel/schemata. */
\r
246 static const notmuch_show_format_t format_json = {
\r
248 "{", format_message_json,
\r