mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-12-26 11:24:53 +01:00
1c6195b9e3
Currently there is a period of pain whenever we make backward-incompatible changes to the structured output format, which discourages not only backward-incompatible improvements to the format, but also backwards-compatible additions that may not be "perfect". In the end, these problems limit experimentation and innovation. This series of patches introduces a way for CLI callers to request a specific format version on the command line and to determine if the CLI does not supported the requested version (and perhaps present a useful diagnostic to the user). Since the caller requests a format version, it's also possible for the CLI to support multiple incompatible versions simultaneously, unlike the alternate approach of including version information in the output. This patch lays the groundwork by introducing a versioning convention, standard exit codes, and a utility function to check the requested version and produce standardized diagnostic messages and exit statuses.
164 lines
4.4 KiB
Text
164 lines
4.4 KiB
Text
This file describes the schemata used for notmuch's structured output
|
|
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
|
|
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).
|
|
|
|
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 1 of the structured output format.
|
|
|
|
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|null, # null if not matched and not --entire-thread
|
|
[thread_node*] # children of message
|
|
]
|
|
|
|
# A message (format_part_sprinter)
|
|
message = {
|
|
# (format_message_sprinter)
|
|
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] # omitted if --body=false
|
|
}
|
|
|
|
# A MIME part (format_part_sprinter)
|
|
part = {
|
|
id: int|string, # part id (currently DFS part number)
|
|
|
|
encstatus?: encstatus,
|
|
sigstatus?: sigstatus,
|
|
|
|
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 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_sprinter)
|
|
encstatus = [{status: "good"|"bad"}]
|
|
|
|
# Signature status (format_part_sigstatus_sprinter)
|
|
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,
|
|
tags: [string*]
|
|
}
|
|
|
|
notmuch reply schema
|
|
--------------------
|
|
|
|
reply = {
|
|
# The headers of the constructed reply
|
|
reply-headers: reply_headers,
|
|
|
|
# As in the show format (format_part_sprinter)
|
|
original: message
|
|
}
|
|
|
|
# Reply headers (format_headers_sprinter with reply = TRUE)
|
|
reply_headers = {
|
|
Subject: string,
|
|
From: string,
|
|
To?: string,
|
|
Cc?: string,
|
|
Bcc?: string,
|
|
In-reply-to: string,
|
|
References: string
|
|
}
|