From 661c35712343408b4c034e13fc6cc8be7d580e21 Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Sun, 19 Feb 2012 19:26:23 -0500 Subject: Document the JSON schemata used by show and search --- devel/schemata | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 devel/schemata (limited to 'devel/schemata') diff --git a/devel/schemata b/devel/schemata new file mode 100644 index 0000000..24ad775 --- /dev/null +++ b/devel/schemata @@ -0,0 +1,138 @@ +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, + # 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 +} + +# 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 +} -- cgit v1.2.3 From 5abc9c1097a54e0e8b62e468d51728edb26b9101 Mon Sep 17 00:00:00 2001 From: Adam Wolfe Gordon Date: Sun, 18 Mar 2012 10:32:37 -0600 Subject: schemata: Add documentation for JSON reply format. --- devel/schemata | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) (limited to 'devel/schemata') diff --git a/devel/schemata b/devel/schemata index 24ad775..728a46f 100644 --- a/devel/schemata +++ b/devel/schemata @@ -77,8 +77,9 @@ part = { content?: string } -# The headers of a message (format_headers_json with raw headers) or -# a part (format_headers_message_part_json with pretty-printed headers) +# 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) headers = { Subject: string, From: string, @@ -136,3 +137,25 @@ thread = { # matched and unmatched subject: string } + +notmuch reply schema +-------------------- + +reply = { + # The headers of the constructed reply (format_headers_json with + # raw headers and reply = TRUE) + reply-headers: reply_headers, + + # As in the show format (format_part_json) + original: message +} + +reply_headers = { + Subject: string, + From: string, + To?: string, + Cc?: string, + Bcc?: string, + In-reply-to: string, + References: string +} -- cgit v1.2.3 From 98cad5a207438601942ecb8142a41133d54f0fbc Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Sat, 7 Apr 2012 20:57:45 -0400 Subject: Sync schemata with current code structure The schema itself hasn't changed, but many of the references to functions in notmuch-show.c were out of date. --- devel/schemata | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) (limited to 'devel/schemata') diff --git a/devel/schemata b/devel/schemata index 728a46f..977cea7 100644 --- a/devel/schemata +++ b/devel/schemata @@ -36,7 +36,7 @@ thread_node = [ [thread_node*] # children of message ] -# A message (show_message) +# A message (format_part_json) message = { # (format_message_json) id: messageid, @@ -50,18 +50,13 @@ message = { body: [part] } -# A MIME part (show_message_body) +# A MIME part (format_part_json) 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/": @@ -77,9 +72,7 @@ part = { content?: 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_json with reply = FALSE) headers = { Subject: string, From: string, @@ -89,14 +82,14 @@ headers = { Date: string } -# Encryption status (format_part_encstatus_json) +# Encryption status (format_part_json) encstatus = [{status: "good"|"bad"}] # Signature status (format_part_sigstatus_json) sigstatus = [signature*] signature = { - # signature_status_to_string + # (signature_status_to_string) status: "none"|"good"|"bad"|"error"|"unknown", # if status is "good": fingerprint?: string, @@ -142,14 +135,14 @@ 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) original: message } +# Reply headers (format_headers_json with reply = TRUE) reply_headers = { Subject: string, From: string, -- cgit v1.2.3 From fdce20d365d58491bd82a5944915843972fc0f00 Mon Sep 17 00:00:00 2001 From: Mark Walters Date: Sat, 16 Jun 2012 11:21:45 +0100 Subject: Update devel/schemata for --entire-thread=false Also remove the Json --entire-thread item from devel/TODO. --- devel/TODO | 2 -- devel/schemata | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) (limited to 'devel/schemata') diff --git a/devel/TODO b/devel/TODO index 7b750af..eb757af 100644 --- a/devel/TODO +++ b/devel/TODO @@ -92,8 +92,6 @@ and email address in the From: line. We could also then easily support "notmuch compose --from " to support getting at alternate email addresses. -Fix the --format=json option to not imply --entire-thread. - Implement "notmuch search --exclude-threads=" to allow for excluding muted threads, (and any other negative, thread-based filtering that the user wants to do). diff --git a/devel/schemata b/devel/schemata index 977cea7..8fcab8e 100644 --- a/devel/schemata +++ b/devel/schemata @@ -32,7 +32,7 @@ thread = [thread_node*] # A message and its replies (show_messages) thread_node = [ - message?, # present if --entire-thread or matched + message?, # null if not matched and not --entire-thread [thread_node*] # children of message ] -- cgit v1.2.3 From 51a7cd3ddb5a902fe46cb6d16b1999c73af0d33a Mon Sep 17 00:00:00 2001 From: Mark Walters Date: Sat, 30 Jun 2012 12:14:15 +0100 Subject: Minor correction to devel/schemata In id:"87sjdm12d1.fsf@awakening.csail.mit.edu" Austin pointed out that devel/schemata needs a slight correction with the new --entire-thread=false option. This is that correction. --- devel/schemata | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'devel/schemata') diff --git a/devel/schemata b/devel/schemata index 8fcab8e..f7e1b69 100644 --- a/devel/schemata +++ b/devel/schemata @@ -32,7 +32,7 @@ thread = [thread_node*] # A message and its replies (show_messages) thread_node = [ - message?, # null if not matched and not --entire-thread + message|null, # null if not matched and not --entire-thread [thread_node*] # children of message ] -- cgit v1.2.3 From e7f5302114da0b86c6682cc676607c0d64c55e5e Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Tue, 3 Jul 2012 01:47:38 -0400 Subject: Add missing "tags" field to search schema This field is output by search, but it didn't make it into the documentation. --- devel/schemata | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'devel/schemata') diff --git a/devel/schemata b/devel/schemata index f7e1b69..6677a1c 100644 --- a/devel/schemata +++ b/devel/schemata @@ -128,7 +128,8 @@ thread = { total: int, # total messages in thread authors: string, # comma-separated names with | between # matched and unmatched - subject: string + subject: string, + tags: [string*] } notmuch reply schema -- cgit v1.2.3 From ed93d7919914d5eb11263cbc4ef864ad0bd54bff Mon Sep 17 00:00:00 2001 From: Mark Walters Date: Tue, 24 Jul 2012 19:23:30 +0100 Subject: schemata: update for --body=true|false option Previously body: was a compulsory field in a message. The new --body=false option causes notmuch show to omit this field so update schemata to reflect this. --- devel/schemata | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'devel/schemata') diff --git a/devel/schemata b/devel/schemata index 6677a1c..9cb25f5 100644 --- a/devel/schemata +++ b/devel/schemata @@ -47,7 +47,7 @@ message = { tags: [string*], headers: headers, - body: [part] + body?: [part] # omitted if --body=false } # A MIME part (format_part_json) -- cgit v1.2.3