X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=devel%2Fschemata;h=41dc4a60fff36608e25425c7f113c6f2a1b667b0;hp=728a46f214ac5a1597c48a62f6d00efbd41ffcd6;hb=60ac94fe58635f9c40724afa0f35965fc9ff1afc;hpb=2ee1d8e1c70ce20728bc3faada389a4802636352

diff --git a/devel/schemata b/devel/schemata
index 728a46f2..41dc4a60 100644
--- a/devel/schemata
+++ b/devel/schemata
@@ -1,5 +1,5 @@
 This file describes the schemata used for notmuch's structured output
-format (currently JSON).
+format (currently JSON and S-Expressions).
 
 []'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
@@ -8,6 +8,24 @@ values.  An object field marked '?' is optional.  |'s indicate
 alternates (e.g., int|string means something can be an int or a
 string).
 
+For S-Expression output, lists are printed delimited by () instead of
+[]. Objects are printed as p-lists, i.e. lists where the keys and values
+are interleaved. Keys are printed as keywords (symbols preceded by a
+colon), e.g. (:id "123" :time 54321 :from "foobar"). Null is printed as
+nil, true as t and false as nil.
+
+This is version 2 of the structured output format.
+
+Version history
+---------------
+
+v1
+- First versioned schema release.
+- Added part.content-length and part.content-transfer-encoding fields.
+
+v2
+- Added the thread_summary.query field.
+
 Common non-terminals
 --------------------
 
@@ -32,13 +50,13 @@ thread = [thread_node*]
 
 # A message and its replies (show_messages)
 thread_node = [
-    message?,                 # present if --entire-thread or matched
+    message|null,             # null if not matched and not --entire-thread
     [thread_node*]            # children of message
 ]
 
-# A message (show_message)
+# A message (format_part_sprinter)
 message = {
-    # (format_message_json)
+    # (format_message_sprinter)
     id:             messageid,
     match:          bool,
     filename:	    string,
@@ -47,21 +65,16 @@ message = {
     tags:           [string*],
 
     headers:        headers,
-    body:           [part]
+    body?:          [part]    # omitted if --body=false
 }
 
-# A MIME part (show_message_body)
+# A MIME part (format_part_sprinter)
 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/":
@@ -74,29 +87,35 @@ part = {
     # A leaf part's body content is optional, but may be included if
     # it can be correctly encoded as a string.  Consumers should use
     # this in preference to fetching the part content separately.
-    content?:       string
+    content?:       string,
+    # If a leaf part's body content is not included, the length of
+    # the encoded content (in bytes) may be given instead.
+    content-length?: int,
+    # If a leaf part's body content is not included, its transfer encoding
+    # may be given.  Using this and the encoded content length, it is
+    # possible for the consumer to estimate the decoded content length.
+    content-transfer-encoding?: string
 }
 
-# The headers of a message (format_headers_json with raw headers
-# and reply = FALSE) or a part (format_headers_message_part_json
-# with pretty-printed headers)
+# The headers of a message or part (format_headers_sprinter with reply = FALSE)
 headers = {
     Subject:        string,
     From:           string,
     To?:            string,
     Cc?:            string,
     Bcc?:           string,
+    Reply-To?:      string,
     Date:           string
 }
 
-# Encryption status (format_part_encstatus_json)
+# Encryption status (format_part_sprinter)
 encstatus = [{status: "good"|"bad"}]
 
-# Signature status (format_part_sigstatus_json)
+# Signature status (format_part_sigstatus_sprinter)
 sigstatus = [signature*]
 
 signature = {
-    # signature_status_to_string
+    # (signature_status_to_string)
     status:         "none"|"good"|"bad"|"error"|"unknown",
     # if status is "good":
     fingerprint?:   string,
@@ -113,21 +132,21 @@ notmuch search schema
 ---------------------
 
 # --output=summary
-summary = [thread*]
+search_summary = [thread_summary*]
 
 # --output=threads
-threads = [threadid*]
+search_threads = [threadid*]
 
 # --output=messages
-messages = [messageid*]
+search_messages = [messageid*]
 
 # --output=files
-files = [string*]
+search_files = [string*]
 
 # --output=tags
-tags = [string*]
+search_tags = [string*]
 
-thread = {
+thread_summary = {
     thread:         threadid,
     timestamp:      unix_time,
     date_relative:  string,   # user-friendly timestamp
@@ -135,21 +154,30 @@ thread = {
     total:          int,      # total messages in thread
     authors:        string,   # comma-separated names with | between
                               # matched and unmatched
-    subject:        string
+    subject:        string,
+    tags:           [string*],
+
+    # Two stable query strings identifying exactly the matched and
+    # unmatched messages currently in this thread.  The messages
+    # matched by these queries will not change even if more messages
+    # arrive in the thread.  If there are no matched or unmatched
+    # messages, the corresponding query will be null (there is no
+    # query that matches nothing).  (Added in schema version 2.)
+    query:          [string|null, string|null],
 }
 
 notmuch reply schema
 --------------------
 
 reply = {
-    # The headers of the constructed reply (format_headers_json with
-    # raw headers and reply = TRUE)
+    # The headers of the constructed reply
     reply-headers: reply_headers,
 
-    # As in the show format (format_part_json)
+    # As in the show format (format_part_sprinter)
     original: message
 }
 
+# Reply headers (format_headers_sprinter with reply = TRUE)
 reply_headers = {
     Subject:        string,
     From:           string,