98/c4662af2dbe36c5e6f343c4cd2f2378975fedd

   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
   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 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
  18         [18.9.25.12])\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
  63 Precedence: list\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
  74 \r
  75 ---\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
  81 \r
  82 diff --git a/devel/schemata b/devel/schemata\r
  83 new file mode 100644\r
  84 index 0000000..24ad775\r
  85 --- /dev/null\r
  86 +++ b/devel/schemata\r
  87 @@ -0,0 +1,138 @@\r
  88 +This file describes the schemata used for notmuch's structured output\r
  89 +format (currently JSON).\r
  90 +\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
  96 +string).\r
  97 +\r
  98 +Common non-terminals\r
  99 +--------------------\r
 100 +\r
 101 +# Number of seconds since the Epoch\r
 102 +unix_time = int\r
 103 +\r
 104 +# Thread ID, sans "thread:"\r
 105 +threadid = string\r
 106 +\r
 107 +# Message ID, sans "id:"\r
 108 +messageid = string\r
 109 +\r
 110 +notmuch show schema\r
 111 +-------------------\r
 112 +\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
 116 +\r
 117 +# Top-level messages in a thread (show_messages)\r
 118 +thread = [thread_node*]\r
 119 +\r
 120 +# A message and its replies (show_messages)\r
 121 +thread_node = [\r
 122 +    message?,                 # present if --entire-thread or matched\r
 123 +    [thread_node*]            # children of message\r
 124 +]\r
 125 +\r
 126 +# A message (show_message)\r
 127 +message = {\r
 128 +    # (format_message_json)\r
 129 +    id:             messageid,\r
 130 +    match:          bool,\r
 131 +    filename:      string,\r
 132 +    timestamp:      unix_time, # date header as unix time\r
 133 +    date_relative:  string,   # user-friendly timestamp\r
 134 +    tags:           [string*],\r
 135 +\r
 136 +    headers:        headers,\r
 137 +    body:           [part]\r
 138 +}\r
 139 +\r
 140 +# A MIME part (show_message_body)\r
 141 +part = {\r
 142 +    # format_part_start_json\r
 143 +    id:             int|string, # part id (currently DFS part number)\r
 144 +\r
 145 +    # format_part_encstatus_json\r
 146 +    encstatus?:     encstatus,\r
 147 +\r
 148 +    # format_part_sigstatus_json\r
 149 +    sigstatus?:     sigstatus,\r
 150 +\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
 164 +    content?:       string\r
 165 +}\r
 166 +\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
 169 +headers = {\r
 170 +    Subject:        string,\r
 171 +    From:           string,\r
 172 +    To?:            string,\r
 173 +    Cc?:            string,\r
 174 +    Bcc?:           string,\r
 175 +    Date:           string\r
 176 +}\r
 177 +\r
 178 +# Encryption status (format_part_encstatus_json)\r
 179 +encstatus = [{status: "good"|"bad"}]\r
 180 +\r
 181 +# Signature status (format_part_sigstatus_json)\r
 182 +sigstatus = [signature*]\r
 183 +\r
 184 +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
 191 +    userid?:        string\r
 192 +    # if status is not "good":\r
 193 +    keyid?:         string\r
 194 +    # if the signature has errors:\r
 195 +    errors?:        int\r
 196 +}\r
 197 +\r
 198 +notmuch search schema\r
 199 +---------------------\r
 200 +\r
 201 +# --output=summary\r
 202 +summary = [thread*]\r
 203 +\r
 204 +# --output=threads\r
 205 +threads = [threadid*]\r
 206 +\r
 207 +# --output=messages\r
 208 +messages = [messageid*]\r
 209 +\r
 210 +# --output=files\r
 211 +files = [string*]\r
 212 +\r
 213 +# --output=tags\r
 214 +tags = [string*]\r
 215 +\r
 216 +thread = {\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
 224 +    subject:        string\r
 225 +}\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
 231                     const int total,\r
 232                     const char *authors,\r
 233                     const char *subject);\r
 234 +\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
 238      "[",\r
 239         "{",\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
 245  static void\r
 246  format_part_end_json (GMimeObject *part);\r
 247  \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
 251      "[", NULL,\r
 252         "{", format_message_json,\r
 253 -- \r
 254 1.7.7.3\r
 255 \r