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 DD13B431FC2
\r
6 for <notmuch@notmuchmail.org>; Sun, 19 Feb 2012 16:26:39 -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 SQ85omdwlsoP for <notmuch@notmuchmail.org>;
\r
16 Sun, 19 Feb 2012 16:26:37 -0800 (PST)
\r
17 Received: from dmz-mailsec-scanner-1.mit.edu (DMZ-MAILSEC-SCANNER-1.MIT.EDU
\r
19 by olra.theworths.org (Postfix) with ESMTP id 59B33431FC0
\r
20 for <notmuch@notmuchmail.org>; Sun, 19 Feb 2012 16:26:36 -0800 (PST)
\r
21 X-AuditID: 1209190c-b7fad6d000000920-ee-4f41933b7b1a
\r
22 Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])
\r
23 by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP
\r
24 id BE.CF.02336.B33914F4; Sun, 19 Feb 2012 19:26:35 -0500 (EST)
\r
25 Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])
\r
26 by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id q1K0QZLd016444;
\r
27 Sun, 19 Feb 2012 19:26:35 -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 q1K0QX8V000298
\r
33 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);
\r
34 Sun, 19 Feb 2012 19:26:34 -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 1RzH5N-0001yC-8V; Sun, 19 Feb 2012 19:26:33 -0500
\r
38 From: Austin Clements <amdragon@MIT.EDU>
\r
39 To: notmuch@notmuchmail.org
\r
40 Subject: [PATCH v2 1/8] Document the JSON schemata used by show and search
\r
41 Date: Sun, 19 Feb 2012 19:26:23 -0500
\r
42 Message-Id: <1329697590-7404-2-git-send-email-amdragon@mit.edu>
\r
43 X-Mailer: git-send-email 1.7.7.3
\r
44 In-Reply-To: <1329697590-7404-1-git-send-email-amdragon@mit.edu>
\r
45 References: <1329240823-7856-1-git-send-email-amdragon@mit.edu>
\r
46 <1329697590-7404-1-git-send-email-amdragon@mit.edu>
\r
47 X-Brightmail-Tracker:
\r
48 H4sIAAAAAAAAA+NgFtrDIsWRmVeSWpSXmKPExsUixCmqrGs92dHf4GSvocX1mzOZLd6snMfq
\r
49 wORx+OtCFo9nq24xBzBFcdmkpOZklqUW6dslcGXs3rWfqWCFZsWGJW3MDYyL5LoYOTkkBEwk
\r
50 /v1cyghhi0lcuLeerYuRi0NIYB+jxOX2u8wQzgZGiXPvWqGc+0wSXx/8Y4Rw5jNKLNsxhQWk
\r
51 n01AQ2Lb/uVgs0QEpCV23p3NCmIzC1hJHL66CcwWFvCSmHlkOtAODg4WAVWJ1f06IGFeAXuJ
\r
52 06d+Q52hIHFu9Tl2kBJOAQeJ1TtcQcJCAqUSR55sYZrAyL+AkWEVo2xKbpVubmJmTnFqsm5x
\r
53 cmJeXmqRrqFebmaJXmpK6SZGcCBJ8uxgfHNQ6RCjAAejEg+vVJmDvxBrYllxZe4hRkkOJiVR
\r
54 3nWTHP2F+JLyUyozEosz4otKc1KLDzFKcDArifAusAfK8aYkVlalFuXDpKQ5WJTEeVW03vkJ
\r
55 CaQnlqRmp6YWpBbBZGU4OJQkeHeBDBUsSk1PrUjLzClBSDNxcIIM5wEaPhukhre4IDG3ODMd
\r
56 In+KUVFKnLceJCEAksgozYPrhUX6K0ZxoFeEeVeAVPEAkwRc9yugwUxAg3mF7EAGlyQipKQa
\r
57 GNu/b7WzTF33aH9Y3fWGnyJK1ebvyrqebQ7cb5TI9/p/xbK5O1Iv6M4qPsYsd2Nqi/D5eTdb
\r
58 sqTXyj08461lNo/73G7B7BsnzXp7Jbdee/Ph820D4a5nXs0PlvkeEJhRe3faD21/y8+FX2OL
\r
59 DRbwuc144LVHYmNAV0vd5QiRjTy6Eo1X9RVaM5VYijMSDbWYi4oTAekS3ijPAgAA
\r
60 Cc: tomi.ollila@iki.fi
\r
61 X-BeenThere: notmuch@notmuchmail.org
\r
62 X-Mailman-Version: 2.1.13
\r
64 List-Id: "Use and development of the notmuch mail system."
\r
65 <notmuch.notmuchmail.org>
\r
66 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
67 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
68 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
69 List-Post: <mailto:notmuch@notmuchmail.org>
\r
70 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
71 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
72 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
73 X-List-Received-Date: Mon, 20 Feb 2012 00:26:40 -0000
\r
76 devel/schemata | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
\r
77 notmuch-search.c | 3 +
\r
78 notmuch-show.c | 2 +
\r
79 3 files changed, 143 insertions(+), 0 deletions(-)
\r
80 create mode 100644 devel/schemata
\r
82 diff --git a/devel/schemata b/devel/schemata
\r
83 new file mode 100644
\r
84 index 0000000..24ad775
\r
86 +++ b/devel/schemata
\r
88 +This file describes the schemata used for notmuch's structured output
\r
89 +format (currently JSON).
\r
91 +[]'s indicate lists. List items can be marked with a '?', meaning
\r
92 +they are optional; or a '*', meaning there can be zero or more of that
\r
93 +item. {}'s indicate an object that maps from field identifiers to
\r
94 +values. An object field marked '?' is optional. |'s indicate
\r
95 +alternates (e.g., int|string means something can be an int or a
\r
98 +Common non-terminals
\r
99 +--------------------
\r
101 +# Number of seconds since the Epoch
\r
104 +# Thread ID, sans "thread:"
\r
107 +# Message ID, sans "id:"
\r
108 +messageid = string
\r
110 +notmuch show schema
\r
111 +-------------------
\r
113 +# A top-level set of threads (do_show)
\r
114 +# Returned by notmuch show without a --part argument
\r
115 +thread_set = [thread*]
\r
117 +# Top-level messages in a thread (show_messages)
\r
118 +thread = [thread_node*]
\r
120 +# A message and its replies (show_messages)
\r
122 + message?, # present if --entire-thread or matched
\r
123 + [thread_node*] # children of message
\r
126 +# A message (show_message)
\r
128 + # (format_message_json)
\r
131 + filename: string,
\r
132 + timestamp: unix_time, # date header as unix time
\r
133 + date_relative: string, # user-friendly timestamp
\r
136 + headers: headers,
\r
140 +# A MIME part (show_message_body)
\r
142 + # format_part_start_json
\r
143 + id: int|string, # part id (currently DFS part number)
\r
145 + # format_part_encstatus_json
\r
146 + encstatus?: encstatus,
\r
148 + # format_part_sigstatus_json
\r
149 + sigstatus?: sigstatus,
\r
151 + # format_part_content_json
\r
152 + content-type: string,
\r
153 + content-id?: string,
\r
154 + # if content-type starts with "multipart/":
\r
155 + content: [part*],
\r
156 + # if content-type is "message/rfc822":
\r
157 + content: [{headers: headers, body: [part]}],
\r
158 + # otherwise (leaf parts):
\r
159 + filename?: string,
\r
160 + content-charset?: string,
\r
161 + # A leaf part's body content is optional, but may be included if
\r
162 + # it can be correctly encoded as a string. Consumers should use
\r
163 + # this in preference to fetching the part content separately.
\r
167 +# The headers of a message (format_headers_json with raw headers) or
\r
168 +# a part (format_headers_message_part_json with pretty-printed headers)
\r
178 +# Encryption status (format_part_encstatus_json)
\r
179 +encstatus = [{status: "good"|"bad"}]
\r
181 +# Signature status (format_part_sigstatus_json)
\r
182 +sigstatus = [signature*]
\r
185 + # signature_status_to_string
\r
186 + status: "none"|"good"|"bad"|"error"|"unknown",
\r
187 + # if status is "good":
\r
188 + fingerprint?: string,
\r
189 + created?: unix_time,
\r
190 + expires?: unix_time,
\r
192 + # if status is not "good":
\r
194 + # if the signature has errors:
\r
198 +notmuch search schema
\r
199 +---------------------
\r
201 +# --output=summary
\r
202 +summary = [thread*]
\r
204 +# --output=threads
\r
205 +threads = [threadid*]
\r
207 +# --output=messages
\r
208 +messages = [messageid*]
\r
217 + thread: threadid,
\r
218 + timestamp: unix_time,
\r
219 + date_relative: string, # user-friendly timestamp
\r
220 + matched: int, # number of matched messages
\r
221 + total: int, # total messages in thread
\r
222 + authors: string, # comma-separated names with | between
\r
223 + # matched and unmatched
\r
226 diff --git a/notmuch-search.c b/notmuch-search.c
\r
227 index d504051..92ce38a 100644
\r
228 --- a/notmuch-search.c
\r
229 +++ b/notmuch-search.c
\r
230 @@ -90,6 +90,9 @@ format_thread_json (const void *ctx,
\r
232 const char *authors,
\r
233 const char *subject);
\r
235 +/* Any changes to the JSON format should be reflected in the file
\r
236 + * devel/schemata. */
\r
237 static const search_format_t format_json = {
\r
240 diff --git a/notmuch-show.c b/notmuch-show.c
\r
241 index d930f94..93fb16f 100644
\r
242 --- a/notmuch-show.c
\r
243 +++ b/notmuch-show.c
\r
244 @@ -65,6 +65,8 @@ format_part_content_json (GMimeObject *part);
\r
246 format_part_end_json (GMimeObject *part);
\r
248 +/* Any changes to the JSON format should be reflected in the file
\r
249 + * devel/schemata. */
\r
250 static const notmuch_show_format_t format_json = {
\r
252 "{", format_message_json,
\r