Add structured output formatter for JSON and plain text (but don't use them yet).
[notmuch] / sprinter.h
1 #ifndef NOTMUCH_SPRINTER_H
2 #define NOTMUCH_SPRINTER_H
3
4 /* Necessary for notmuch_bool_t */
5 #include "notmuch-client.h"
6
7 /* Structure printer interface. This is used to create output
8  * structured as maps (with key/value pairs), lists and primitives
9  * (strings, integers and booleans).
10  */
11 typedef struct sprinter {
12     /* Start a new map/dictionary structure. This should be followed by
13      * a sequence of alternating calls to map_key and one of the
14      * value-printing functions until the map is ended by end.
15      */
16     void (*begin_map) (struct sprinter *);
17
18     /* Start a new list/array structure.
19      */
20     void (*begin_list) (struct sprinter *);
21
22     /* End the last opened list or map structure.
23      */
24     void (*end) (struct sprinter *);
25
26     /* Print one string/integer/boolean/null element (possibly inside a
27      * list or map, followed or preceded by separators).
28      * For string, the char * must be UTF-8 encoded.
29      */
30     void (*string) (struct sprinter *, const char *);
31     void (*integer) (struct sprinter *, int);
32     void (*boolean) (struct sprinter *, notmuch_bool_t);
33     void (*null) (struct sprinter *);
34
35     /* Print the key of a map's key/value pair. The char * must be UTF-8
36      * encoded.
37      */
38     void (*map_key) (struct sprinter *, const char *);
39
40     /* Insert a separator (usually extra whitespace) for improved
41      * readability without affecting the abstract syntax of the
42      * structure being printed.
43      * For JSON, this could simply be a line break.
44      */
45     void (*separator) (struct sprinter *);
46
47     /* Set the current string prefix. This only affects the text
48      * printer, which will print this string, followed by a colon,
49      * before any string. For other printers, this does nothing.
50      */
51     void (*set_prefix) (struct sprinter *, const char *);
52
53     /* True if this is the special-cased plain text printer.
54      */
55     notmuch_bool_t is_text_printer;
56 } sprinter_t;
57
58
59 /* Create a new unstructured printer that emits the default text format
60  * for "notmuch search". */
61 struct sprinter *
62 sprinter_text_create (const void *ctx, FILE *stream);
63
64 /* Create a new structure printer that emits JSON. */
65 struct sprinter *
66 sprinter_json_create (const void *ctx, FILE *stream);
67
68 #endif // NOTMUCH_SPRINTER_H