--- 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