doc/sexp: document range queries.
[notmuch] / sprinter.h
1 #ifndef NOTMUCH_SPRINTER_H
2 #define NOTMUCH_SPRINTER_H
3
4 /* Necessary for bool */
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     /*
13      * Open notmuch database
14      */
15     notmuch_database_t *notmuch;
16
17     /* Start a new map/dictionary structure. This should be followed by
18      * a sequence of alternating calls to map_key and one of the
19      * value-printing functions until the map is ended by end.
20      */
21     void (*begin_map)(struct sprinter *);
22
23     /* Start a new list/array structure.
24      */
25     void (*begin_list)(struct sprinter *);
26
27     /* End the last opened list or map structure.
28      */
29     void (*end)(struct sprinter *);
30
31     /* Print one string/integer/boolean/null element (possibly inside
32      * a list or map, followed or preceded by separators).  For string
33      * and string_len, the char * must be UTF-8 encoded.  string_len
34      * allows non-terminated strings and strings with embedded NULs
35      * (though the handling of the latter is format-dependent). For
36      * string (but not string_len) the string pointer passed may be
37      * NULL.
38      */
39     void (*string)(struct sprinter *, const char *);
40     void (*string_len)(struct sprinter *, const char *, size_t);
41     void (*integer)(struct sprinter *, int64_t);
42     void (*boolean)(struct sprinter *, bool);
43     void (*null)(struct sprinter *);
44
45     /* Print the key of a map's key/value pair. The char * must be UTF-8
46      * encoded.
47      */
48     void (*map_key)(struct sprinter *, const char *);
49
50     /* Insert a separator (usually extra whitespace). For the text
51      * printers, this is a syntactic separator. For the structured
52      * printers, this is for improved readability without affecting
53      * the abstract syntax of the structure being printed. For JSON,
54      * this could simply be a line break.
55      */
56     void (*separator)(struct sprinter *);
57
58     /* Set the current string prefix. This only affects the text
59      * printer, which will print this string, followed by a colon,
60      * before any string. For other printers, this does nothing.
61      */
62     void (*set_prefix)(struct sprinter *, const char *);
63
64     /* True if this is the special-cased plain text printer.
65      */
66     bool is_text_printer;
67 } sprinter_t;
68
69
70 /* Create a new unstructured printer that emits the default text format
71  * for "notmuch search". */
72 struct sprinter *
73 sprinter_text_create (notmuch_database_t *db, FILE *stream);
74
75 /* Create a new unstructured printer that emits the text format for
76  * "notmuch search", with each field separated by a null character
77  * instead of the newline character. */
78 struct sprinter *
79 sprinter_text0_create (notmuch_database_t *db, FILE *stream);
80
81 /* Create a new structure printer that emits JSON. */
82 struct sprinter *
83 sprinter_json_create (notmuch_database_t *db, FILE *stream);
84
85 /* Create a new structure printer that emits S-Expressions. */
86 struct sprinter *
87 sprinter_sexp_create (notmuch_database_t *db, FILE *stream);
88
89 #endif // NOTMUCH_SPRINTER_H