diff options
author | craven@gmx.net <craven@gmx.net> | 2012-07-23 12:39:44 +0200 |
---|---|---|
committer | David Bremner <bremner@debian.org> | 2012-07-24 09:26:49 -0300 |
commit | 41becc0c9dfabbd59a1c96bdedc99a785539a93b (patch) | |
tree | 6ac3b2d3694d1bc3ed5c289ddf10ae62c3182895 | |
parent | 90c41e39d982ac9bf317374c6f20a0855614f2dd (diff) |
Add support for structured output formatters.
This patch adds a new struct type sprinter_t, which is used for
structured formatting, e.g. JSON or S-Expressions. The structure printer
is heavily based on code from Austin Clements
(id:87d34hsdx8.fsf@awakening.csail.mit.edu).
It includes the following functions:
/* Start a new map/dictionary structure. This should be followed by
* a sequence of alternating calls to map_key and one of the
* value-printing functions until the map is ended by end.
*/
void (*begin_map) (struct sprinter *);
/* Start a new list/array structure.
*/
void (*begin_list) (struct sprinter *);
/* End the last opened list or map structure.
*/
void (*end) (struct sprinter *);
/* Print one string/integer/boolean/null element (possibly inside a
* list or map, followed or preceded by separators).
* For string, the char * must be UTF-8 encoded.
*/
void (*string) (struct sprinter *, const char *);
void (*integer) (struct sprinter *, int);
void (*boolean) (struct sprinter *, notmuch_bool_t);
void (*null) (struct sprinter *);
/* Print the key of a map's key/value pair. The char * must be UTF-8
* encoded.
*/
void (*map_key) (struct sprinter *, const char *);
/* Insert a separator (usually extra whitespace) for improved
* readability without affecting the abstract syntax of the
* structure being printed.
* For JSON, this could simply be a line break.
*/
void (*separator) (struct sprinter *);
/* Set the current string prefix. This only affects the text
* printer, which will print this string, followed by a colon,
* before any string. For other printers, this does nothing.
*/
void (*set_prefix) (struct sprinter *, const char *);
To support the plain text format properly, the following additional
function must also be implemented:
/* Set the current string prefix. This only affects the text
* printer, which will print this string, followed by a colon,
* before any string. For other printers, this does nothing.
*/
void (*set_prefix) (struct sprinter *, const char *);
The structure also contains a flag that should be set to FALSE in all
custom printers and to TRUE in the plain text formatter.
/* True if this is the special-cased plain text printer.
*/
notmuch_bool_t is_text_printer;
The printer can (and should) use internal state to insert delimiters
and syntax at the correct places.
Example:
format->begin_map(format);
format->map_key(format, "foo");
format->begin_list(format);
format->integer(format, 1);
format->integer(format, 2);
format->integer(format, 3);
format->end(format);
format->map_key(format, "bar");
format->begin_map(format);
format->map_key(format, "baaz");
format->string(format, "hello world");
format->end(format);
format->end(format);
would output JSON as follows:
{"foo": [1, 2, 3], "bar": { "baaz": "hello world"}}
-rw-r--r-- | sprinter.h | 58 |
1 files changed, 58 insertions, 0 deletions
diff --git a/sprinter.h b/sprinter.h new file mode 100644 index 0000000..77dc26f --- /dev/null +++ b/sprinter.h @@ -0,0 +1,58 @@ +#ifndef NOTMUCH_SPRINTER_H +#define NOTMUCH_SPRINTER_H + +/* Necessary for notmuch_bool_t */ +#include "notmuch-client.h" + +/* Structure printer interface. This is used to create output + * structured as maps (with key/value pairs), lists and primitives + * (strings, integers and booleans). + */ +typedef struct sprinter { + /* Start a new map/dictionary structure. This should be followed by + * a sequence of alternating calls to map_key and one of the + * value-printing functions until the map is ended by end. + */ + void (*begin_map) (struct sprinter *); + + /* Start a new list/array structure. + */ + void (*begin_list) (struct sprinter *); + + /* End the last opened list or map structure. + */ + void (*end) (struct sprinter *); + + /* Print one string/integer/boolean/null element (possibly inside a + * list or map, followed or preceded by separators). + * For string, the char * must be UTF-8 encoded. + */ + void (*string) (struct sprinter *, const char *); + void (*integer) (struct sprinter *, int); + void (*boolean) (struct sprinter *, notmuch_bool_t); + void (*null) (struct sprinter *); + + /* Print the key of a map's key/value pair. The char * must be UTF-8 + * encoded. + */ + void (*map_key) (struct sprinter *, const char *); + + /* Insert a separator (usually extra whitespace) for improved + * readability without affecting the abstract syntax of the + * structure being printed. + * For JSON, this could simply be a line break. + */ + void (*separator) (struct sprinter *); + + /* Set the current string prefix. This only affects the text + * printer, which will print this string, followed by a colon, + * before any string. For other printers, this does nothing. + */ + void (*set_prefix) (struct sprinter *, const char *); + + /* True if this is the special-cased plain text printer. + */ + notmuch_bool_t is_text_printer; +} sprinter_t; + +#endif // NOTMUCH_SPRINTER_H |