9f/ebdec1d022c1448e4a3daed62567992c04c576

   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
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -0.7\r
  10 X-Spam-Level: \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
  18         [18.7.68.37])\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
  59         EjOe2gIAAA==\r
  60 X-BeenThere: notmuch@notmuchmail.org\r
  61 X-Mailman-Version: 2.1.13\r
  62 Precedence: list\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
  73 \r
  74 ---\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
  80 \r
  81 diff --git a/devel/schemata b/devel/schemata\r
  82 new file mode 100644\r
  83 index 0000000..d90d4c6\r
  84 --- /dev/null\r
  85 +++ b/devel/schemata\r
  86 @@ -0,0 +1,135 @@\r
  87 +This file describes the schemata used for notmuch's structured output\r
  88 +format (currently JSON).\r
  89 +\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
  95 +string).\r
  96 +\r
  97 +Common non-terminals\r
  98 +--------------------\r
  99 +\r
 100 +# Number of seconds since the Epoch\r
 101 +unix_time = int\r
 102 +\r
 103 +# Thread ID, sans "thread:"\r
 104 +threadid = string\r
 105 +\r
 106 +# Message ID, sans "id:"\r
 107 +messageid = string\r
 108 +\r
 109 +notmuch show schema\r
 110 +-------------------\r
 111 +\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
 115 +\r
 116 +# Top-level messages in a thread (show_messages)\r
 117 +thread = [thread_node*]\r
 118 +\r
 119 +# A message and its replies (show_messages)\r
 120 +thread_node = [\r
 121 +    message?,                 # present if --entire-thread or matched\r
 122 +    [thread_node*]            # children of message\r
 123 +]\r
 124 +\r
 125 +# A message (show_message)\r
 126 +message = {\r
 127 +    # (format_message_json)\r
 128 +    id:             messageid,\r
 129 +    match:          bool,\r
 130 +    filename:      string,\r
 131 +    timestamp:      unix_time, # date header as unix time\r
 132 +    date_relative:  string,   # user-friendly timestamp\r
 133 +    tags:           [string*],\r
 134 +\r
 135 +    headers:        headers,\r
 136 +    body:           [part]\r
 137 +}\r
 138 +\r
 139 +# A MIME part (show_message_body)\r
 140 +part = {\r
 141 +    # format_part_start_json\r
 142 +    id:             int|string, # part id (currently DFS part number)\r
 143 +\r
 144 +    # format_part_encstatus_json\r
 145 +    encstatus?:     encstatus,\r
 146 +\r
 147 +    # format_part_sigstatus_json\r
 148 +    sigstatus?:     sigstatus,\r
 149 +\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
 161 +}\r
 162 +\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
 165 +headers = {\r
 166 +    Subject:        string,\r
 167 +    From:           string,\r
 168 +    To?:            string,\r
 169 +    Cc?:            string,\r
 170 +    Bcc?:           string,\r
 171 +    Date:           string\r
 172 +}\r
 173 +\r
 174 +# Encryption status (format_part_encstatus_json)\r
 175 +encstatus = [{status: "good"|"bad"}]\r
 176 +\r
 177 +# Signature status (format_part_sigstatus_json)\r
 178 +sigstatus = [signature*]\r
 179 +\r
 180 +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
 187 +    userid?:        string\r
 188 +    # if status is not "good":\r
 189 +    keyid?:         string\r
 190 +    # if the signature has errors:    \r
 191 +    errors?:        int\r
 192 +}\r
 193 +\r
 194 +notmuch search schema\r
 195 +---------------------\r
 196 +\r
 197 +# --output=summary\r
 198 +summary = [thread*]\r
 199 +\r
 200 +# --output=threads\r
 201 +threads = [threadid*]\r
 202 +\r
 203 +# --output=messages\r
 204 +messages = [messageid*]\r
 205 +\r
 206 +# --output=files\r
 207 +files = [string*]\r
 208 +\r
 209 +# --output=tags\r
 210 +tags = [string*]\r
 211 +\r
 212 +thread = {\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
 220 +    subject:        string\r
 221 +}\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
 227                     const int total,\r
 228                     const char *authors,\r
 229                     const char *subject);\r
 230 +\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
 234      "[",\r
 235         "{",\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
 241  static void\r
 242  format_part_end_json (GMimeObject *part);\r
 243  \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
 247      "[", NULL,\r
 248         "{", format_message_json,\r
 249 -- \r
 250 1.7.7.3\r
 251 \r