From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id 674EE429E31 for ; Tue, 14 Feb 2012 09:34:02 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -0.7 X-Spam-Level: X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id xUeE7P45OOid for ; Tue, 14 Feb 2012 09:33:59 -0800 (PST) Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU [18.7.68.37]) by olra.theworths.org (Postfix) with ESMTP id 9BEAB431FBC for ; Tue, 14 Feb 2012 09:33:56 -0800 (PST) X-AuditID: 12074425-b7f4a6d0000008e0-a0-4f3a9b038ca9 Received: from mailhub-auth-4.mit.edu ( [18.7.62.39]) by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP id D0.E3.02272.30B9A3F4; Tue, 14 Feb 2012 12:33:55 -0500 (EST) Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id q1EHXtRI019622; Tue, 14 Feb 2012 12:33:55 -0500 Received: from drake.mit.edu (209-6-116-242.c3-0.arl-ubr1.sbo-arl.ma.cable.rcn.com [209.6.116.242]) (authenticated bits=0) (User authenticated as amdragon@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q1EHXr3j016486 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT); Tue, 14 Feb 2012 12:33:54 -0500 (EST) Received: from amthrax by drake.mit.edu with local (Exim 4.77) (envelope-from ) id 1RxMGH-000271-7w; Tue, 14 Feb 2012 12:33:53 -0500 From: Austin Clements To: notmuch@notmuchmail.org Subject: [PATCH 1/8] Document the JSON schemata used by show and search Date: Tue, 14 Feb 2012 12:33:36 -0500 Message-Id: <1329240823-7856-2-git-send-email-amdragon@mit.edu> X-Mailer: git-send-email 1.7.7.3 In-Reply-To: <1329240823-7856-1-git-send-email-amdragon@mit.edu> References: <1329240823-7856-1-git-send-email-amdragon@mit.edu> X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFjrOIsWRmVeSWpSXmKPExsUixG6nrss828rfoHutlcWRPbPYLa5u7We3 uH5zJrMDs8fOWXfZPZ6tusXs0fRjMWsAcxSXTUpqTmZZapG+XQJXRvuqC4wFP9UrenZfYGtg nCXbxcjJISFgInGudR0jhC0mceHeerYuRi4OIYF9jBJXTr1ghHA2MEoc/bCTBcK5zyTx8eId qLL5jBJ3vzwC62cT0JDYtn85mC0iIC2x8+5sVhCbWSBe4kjberC4sIC7xKT/E1lAbBYBVYkf bZfYuxg5OHgF7CVWvGSGOENB4tzqc+wgNqeAg8T+ff/BxggBlVy6u5VlAiP/AkaGVYyyKblV urmJmTnFqcm6xcmJeXmpRboWermZJXqpKaWbGMHh5aK6g3HCIaVDjAIcjEo8vAYWlv5CrIll xZW5hxglOZiURHmFZ1j5C/El5adUZiQWZ8QXleakFh9ilOBgVhLh3TQdKMebklhZlVqUD5OS 5mBREufV1HrnJySQnliSmp2aWpBaBJOV4eBQkuBlmwXUKFiUmp5akZaZU4KQZuLgBBnOAzT8 y0yQ4cUFibnFmekQ+VOMilLivG9BEgIgiYzSPLheWPy/YhQHekWYVw5kBQ8wdcB1vwIazAQ0 ePtpC5DBJYkIKakGRmN185uzsuS+b+SpP8Cknf/lUAO/V4bQrjMTP+WtSvz5RX3ZRRWhFxed XppVV62WM7jf8nuaPFfZAsfy7Ol/PKa9+3pV6rHgP8aMHTVOU3ztZ63bI+G96ky/s80jW921 R1MsPiQ7up1fVa29p7TiwMGdsnlP51Wv/RH1d7m1XMP1s/wzslNvpymxFGckGmoxFxUnAgDD EjOe2gIAAA== X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 14 Feb 2012 17:34:03 -0000 --- devel/schemata | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ notmuch-search.c | 3 + notmuch-show.c | 2 + 3 files changed, 140 insertions(+), 0 deletions(-) create mode 100644 devel/schemata diff --git a/devel/schemata b/devel/schemata new file mode 100644 index 0000000..d90d4c6 --- /dev/null +++ b/devel/schemata @@ -0,0 +1,135 @@ +This file describes the schemata used for notmuch's structured output +format (currently JSON). + +[]'s indicate lists. List items can be marked with a '?', meaning +they are optional; or a '*', meaning there can be zero or more of that +item. {}'s indicate an object that maps from field identifiers to +values. An object field marked '?' is optional. |'s indicate +alternates (e.g., int|string means something can be an int or a +string). + +Common non-terminals +-------------------- + +# Number of seconds since the Epoch +unix_time = int + +# Thread ID, sans "thread:" +threadid = string + +# Message ID, sans "id:" +messageid = string + +notmuch show schema +------------------- + +# A top-level set of threads (do_show) +# Returned by notmuch show without a --part argument +thread_set = [thread*] + +# Top-level messages in a thread (show_messages) +thread = [thread_node*] + +# A message and its replies (show_messages) +thread_node = [ + message?, # present if --entire-thread or matched + [thread_node*] # children of message +] + +# A message (show_message) +message = { + # (format_message_json) + id: messageid, + match: bool, + filename: string, + timestamp: unix_time, # date header as unix time + date_relative: string, # user-friendly timestamp + tags: [string*], + + headers: headers, + body: [part] +} + +# A MIME part (show_message_body) +part = { + # format_part_start_json + id: int|string, # part id (currently DFS part number) + + # format_part_encstatus_json + encstatus?: encstatus, + + # format_part_sigstatus_json + sigstatus?: sigstatus, + + # format_part_content_json + content-type: string, + content-id?: string, + # if content-type starts with "multipart/": + content: [part*], + # if content-type is "message/rfc822": + content: [{headers: headers, body: [part]}], + # otherwise (leaf parts): + filename?: string, + content-charset?: string, + content?: string # pre-fetched body content +} + +# The headers of a message (format_headers_json with raw headers) or +# a part (format_headers_message_part_json with pretty-printed headers) +headers = { + Subject: string, + From: string, + To?: string, + Cc?: string, + Bcc?: string, + Date: string +} + +# Encryption status (format_part_encstatus_json) +encstatus = [{status: "good"|"bad"}] + +# Signature status (format_part_sigstatus_json) +sigstatus = [signature*] + +signature = { + # signature_status_to_string + status: "none"|"good"|"bad"|"error"|"unknown", + # if status is "good": + fingerprint?: string, + created?: unix_time, + expires?: unix_time, + userid?: string + # if status is not "good": + keyid?: string + # if the signature has errors: + errors?: int +} + +notmuch search schema +--------------------- + +# --output=summary +summary = [thread*] + +# --output=threads +threads = [threadid*] + +# --output=messages +messages = [messageid*] + +# --output=files +files = [string*] + +# --output=tags +tags = [string*] + +thread = { + thread: threadid, + timestamp: unix_time, + date_relative: string, # user-friendly timestamp + matched: int, # number of matched messages + total: int, # total messages in thread + authors: string, # comma-separated names with | between + # matched and unmatched + subject: string +} diff --git a/notmuch-search.c b/notmuch-search.c index d504051..92ce38a 100644 --- a/notmuch-search.c +++ b/notmuch-search.c @@ -90,6 +90,9 @@ format_thread_json (const void *ctx, const int total, const char *authors, const char *subject); + +/* Any changes to the JSON format should be reflected in the file + * devel/schemata. */ static const search_format_t format_json = { "[", "{", diff --git a/notmuch-show.c b/notmuch-show.c index d930f94..93fb16f 100644 --- a/notmuch-show.c +++ b/notmuch-show.c @@ -65,6 +65,8 @@ format_part_content_json (GMimeObject *part); static void format_part_end_json (GMimeObject *part); +/* Any changes to the JSON format should be reflected in the file + * devel/schemata. */ static const notmuch_show_format_t format_json = { "[", NULL, "{", format_message_json, -- 1.7.7.3