diff options
| -rw-r--r-- | devel/schemata | 2 | ||||
| -rw-r--r-- | notmuch-client.h | 45 | ||||
| -rw-r--r-- | notmuch.c | 32 |
3 files changed, 79 insertions, 0 deletions
diff --git a/devel/schemata b/devel/schemata index d1ab983a..292f2876 100644 --- a/devel/schemata +++ b/devel/schemata @@ -14,6 +14,8 @@ 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 -------------------- diff --git a/notmuch-client.h b/notmuch-client.h index 1c336dcb..d7b352e8 100644 --- a/notmuch-client.h +++ b/notmuch-client.h @@ -117,6 +117,51 @@ chomp_newline (char *str) str[strlen(str)-1] = '\0'; } +/* Exit status code indicating the requested format version is too old + * (support for that version has been dropped). CLI code should use + * notmuch_exit_if_unsupported_format rather than directly exiting + * with this code. + */ +#define NOTMUCH_EXIT_FORMAT_TOO_OLD 20 +/* Exit status code indicating the requested format version is newer + * than the version supported by the CLI. CLI code should use + * notmuch_exit_if_unsupported_format rather than directly exiting + * with this code. + */ +#define NOTMUCH_EXIT_FORMAT_TOO_NEW 21 + +/* The current structured output format version. Requests for format + * versions above this will return an error. Backwards-incompatible + * changes such as removing map fields, changing the meaning of map + * fields, or changing the meanings of list elements should increase + * this. New (required) map fields can be added without increasing + * this. + */ +#define NOTMUCH_FORMAT_CUR 1 +/* The minimum supported structured output format version. Requests + * for format versions below this will return an error. */ +#define NOTMUCH_FORMAT_MIN 1 + +/* The output format version requested by the caller on the command + * line. If no format version is requested, this will be set to + * NOTMUCH_FORMAT_CUR. Even though the command-line option is + * per-command, this is global because commands can share structured + * output code. + */ +extern int notmuch_format_version; + +/* Commands that support structured output should support the + * following argument + * { NOTMUCH_OPT_INT, ¬much_format_version, "format-version", 0, 0 } + * and should invoke notmuch_exit_if_unsupported_format to check the + * requested version. If notmuch_format_version is outside the + * supported range, this will print a detailed diagnostic message for + * the user and exit with NOTMUCH_EXIT_FORMAT_TOO_{OLD,NEW} to inform + * the invoking program of the problem. + */ +void +notmuch_exit_if_unsupported_format (void); + notmuch_crypto_context_t * notmuch_crypto_get_context (notmuch_crypto_t *crypto, const char *protocol); @@ -82,6 +82,8 @@ static command_t commands[] = { "This message, or more detailed help for the named command." } }; +int notmuch_format_version; + static void usage (FILE *out) { @@ -109,6 +111,33 @@ usage (FILE *out) "and \"notmuch help search-terms\" for the common search-terms syntax.\n\n"); } +void +notmuch_exit_if_unsupported_format (void) +{ + if (notmuch_format_version > NOTMUCH_FORMAT_CUR) { + fprintf (stderr, "\ +A caller requested output format version %d, but the installed notmuch\n\ +CLI only supports up to format version %d. You may need to upgrade your\n\ +notmuch CLI.\n", + notmuch_format_version, NOTMUCH_FORMAT_CUR); + exit (NOTMUCH_EXIT_FORMAT_TOO_NEW); + } else if (notmuch_format_version < NOTMUCH_FORMAT_MIN) { + fprintf (stderr, "\ +A caller requested output format version %d, which is no longer supported\n\ +by the notmuch CLI (it requires at least version %d). You may need to\n\ +upgrade your notmuch front-end.\n", + notmuch_format_version, NOTMUCH_FORMAT_MIN); + exit (NOTMUCH_EXIT_FORMAT_TOO_OLD); + } else if (notmuch_format_version != NOTMUCH_FORMAT_CUR) { + /* Warn about old version requests so compatibility issues are + * less likely when we drop support for a deprecated format + * versions. */ + fprintf (stderr, "\ +A caller requested deprecated output format version %d, which may not\n\ +be supported in the future.\n", notmuch_format_version); + } +} + static void exec_man (const char *page) { @@ -242,6 +271,9 @@ main (int argc, char *argv[]) g_mime_init (0); g_type_init (); + /* Globally default to the current output format version. */ + notmuch_format_version = NOTMUCH_FORMAT_CUR; + if (argc == 1) return notmuch (local); |