X-Git-Url: http://mj.ucw.cz/gitweb/?a=blobdiff_plain;f=ucw-json%2Fjson.h;h=369598b705f9ab255eaeed90c2c715aa8103559c;hb=HEAD;hp=5340a30e1ea57f15f4048b4f6ef94e08efc81c5f;hpb=5b7aeae4b33b686e52304127d1648f7b71c9b405;p=libucw.git diff --git a/ucw-json/json.h b/ucw-json/json.h index 5340a30e..369598b7 100644 --- a/ucw-json/json.h +++ b/ucw-json/json.h @@ -10,36 +10,134 @@ #ifndef _UCW_JSON_JSON_H #define _UCW_JSON_JSON_H -#include -#include #include #include #ifdef CONFIG_UCW_CLEAN_ABI -// FIXME +#define json_array_append ucw_json_array_append +#define json_delete ucw_json_delete +#define json_new ucw_json_new +#define json_new_array ucw_json_new_array +#define json_new_node ucw_json_new_node +#define json_new_number ucw_json_new_number +#define json_new_object ucw_json_new_object +#define json_next_token ucw_json_next_token +#define json_next_value ucw_json_next_value +#define json_number_to_int ucw_json_number_to_int +#define json_number_to_s64 ucw_json_number_to_s64 +#define json_number_to_u64 ucw_json_number_to_u64 +#define json_number_to_uint ucw_json_number_to_uint +#define json_object_get ucw_json_object_get +#define json_object_set ucw_json_object_set +#define json_parse ucw_json_parse +#define json_peek_token ucw_json_peek_token +#define json_pop ucw_json_pop +#define json_push ucw_json_push +#define json_reset ucw_json_reset +#define json_set_input ucw_json_set_input +#define json_set_output ucw_json_set_output +#define json_write ucw_json_write +#define json_write_value ucw_json_write_value #endif /*** - * === FIXME + * === JSON library context + * + * The context structure remembers the whole state of the JSON + * library. All JSON values are allocated from a memory pool associated + * with the context. By default, their lifetime is the same as that + * of the context. + * + * Alternatively, you can mark the current state of the context + * with json_push() and return to the marked state later using + * json_pop(). All JSON values created between these two operations + * are released afterwards. See json_push() for details. ***/ +/** + * The context is represented a pointer to this structure. + * The fields marked with [*] are publicly accessible, the rest is private. + **/ struct json_context { + // Memory management struct mempool *pool; struct mempool_state init_state; - // FIXME: Size limit? + // Parser context struct fastbuf *in_fb; - uint in_line; - bool in_eof; + uint in_line; // [*] Current line number + uint in_column; // [*] Current column number + bool in_eof; // End of file was encountered struct json_node *next_token; struct json_node *trivial_token; int next_char; + + // Formatter context + struct fastbuf *out_fb; + uint out_indent; + uint format_options; // [*] Formatting options (a combination of JSON_FORMAT_xxx) }; +/** Creates a new JSON context. **/ struct json_context *json_new(void); + +/** Deletes a JSON context, deallocating all memory associated with it. **/ void json_delete(struct json_context *js); + +/** + * Recycles a JSON context. All state is reset, allocated objects are freed. + * This is equivalent to mp_delete() followed by mp_new(), but it is faster + * and the address of the context is preserved. + **/ void json_reset(struct json_context *js); +/** + * Push the current state of the context onto state stack. + * + * Between json_push() and the associated json_pop(), only newly + * created JSON values can be modified. Older values can be only + * inspected, never modified. In particular, new values cannot be + * inserted to old arrays nor objects. + * + * If you are using json_peek_token(), the saved tokens cannot + * be carried over push/pop boundary. + **/ +void json_push(struct json_context *js); + +/** + * Create a copy of a string in JSON memory. + * + * For example, this is useful when you want to use a string of unknown + * lifetime as a key in json_object_set(). + **/ +static inline const char *json_strdup(struct json_context *js, const char *str) +{ + return mp_strdup(js->pool, str); +} + +/** + * Pop state of the context off state stack. All JSON values created + * since the state was saved by json_push() are released. + **/ +void json_pop(struct json_context *js); + +/*** + * === JSON values + * + * Each JSON value is represented by <>, + * which is either an elementary value (null, boolean, number, string), + * or a container (array, object) pointing to other values. + * + * A value can belong to multiple containers simultaneously, so in general, + * the relationships between values need not form a tree, but a directed + * acyclic graph. + * + * You are allowed to read contents of nodes directly, but construction + * and modification of nodes must be always performed using the appropriate + * library functions. + ***/ + +/** Node types **/ enum json_node_type { JSON_INVALID, JSON_NULL, @@ -48,7 +146,9 @@ enum json_node_type { JSON_STRING, JSON_ARRAY, JSON_OBJECT, - // These are not real nodes, but raw tokens + // These are not real nodes, but raw tokens. + // They are not present in the tree of values, but you may see them + // if you call json_next_token() and friends. JSON_BEGIN_ARRAY, JSON_END_ARRAY, JSON_BEGIN_OBJECT, @@ -58,44 +158,70 @@ enum json_node_type { JSON_EOF, }; +/** Each value is represented by a single node. **/ struct json_node { enum json_node_type type; - union { + union { // Data specific to individual value types bool boolean; double number; const char *string; - struct json_node **elements; // Growing array - struct json_pair *pairs; // Growing array + struct json_node **elements; // Arrays: Growing array of values + struct json_pair *pairs; // Objects: Growing array of pairs }; }; +/** Attributes of objects are stored as (key, value) pairs of this format. **/ struct json_pair { const char *key; struct json_node *value; // FIXME: Hash table }; +// Used internally struct json_node *json_new_node(struct json_context *js, enum json_node_type type); -static inline struct json_node *json_new_null(struct json_context *js) +/** Creates a new null value. **/ +static inline struct json_node *json_new_null(struct json_context *js UNUSED) { - return json_new_node(js, JSON_NULL); + static const struct json_node static_null = { .type = JSON_NULL }; + return (struct json_node *) &static_null; } -static inline struct json_node *json_new_bool(struct json_context *js, bool value) +/** Creates a new boolean value. **/ +static inline struct json_node *json_new_bool(struct json_context *js UNUSED, bool value) { - struct json_node *n = json_new_node(js, JSON_BOOLEAN); - n->boolean = value; - return n; + static const struct json_node static_bool[2] = { + [0] = { .type = JSON_BOOLEAN, { .boolean = 0 } }, + [1] = { .type = JSON_BOOLEAN, { .boolean = 1 } }, + }; + return (struct json_node *) &static_bool[value]; } -static inline struct json_node *json_new_number(struct json_context *js, double value) -{ - struct json_node *n = json_new_node(js, JSON_NUMBER); - n->number = value; - return n; -} +/** Creates a new numeric value. The @value must be a finite number. **/ +struct json_node *json_new_number(struct json_context *js, double value); + +/** + * Convert a numeric value to an `int`. Returns false if the value + * is not numeric or if it is too large for an int. + **/ +bool json_number_to_int(struct json_node *num, int *dest); + +/** Same as above, but for `uint`. **/ +bool json_number_to_uint(struct json_node *num, uint *dest); + +/** Same as above, but for `s64`. **/ +bool json_number_to_s64(struct json_node *num, s64 *dest); + +/** Same as above, but for `u64`. **/ +bool json_number_to_u64(struct json_node *num, u64 *dest); +/** + * Creates a new string value. The @value is kept only as a reference. + * + * String values can contain an arbitrary UTF-8 string with no null + * characters. However, it is not recommended to use UTF-8 values outside + * the range of UniCode codepoints (0 to 0x10ffff). + **/ static inline struct json_node *json_new_string_ref(struct json_context *js, const char *value) { struct json_node *n = json_new_node(js, JSON_STRING); @@ -103,25 +229,91 @@ static inline struct json_node *json_new_string_ref(struct json_context *js, con return n; } +/** Creates a new string value, making a private copy of @value. **/ static inline struct json_node *json_new_string(struct json_context *js, const char *value) { return json_new_string_ref(js, mp_strdup(js->pool, value)); } +/** Creates a new array value with no elements. **/ struct json_node *json_new_array(struct json_context *js); + +/** Appends a new element to the given array. **/ void json_array_append(struct json_node *array, struct json_node *elt); +/** Creates a new object value with no attributes. **/ struct json_node *json_new_object(struct json_context *js); -// FIXME: key must not be freed + +/** + * Adds a new (@key, @value) pair to the given object. If @key is already + * present, the pair is replaced. If @value is NULL, no new pair is created + * and a pre-existing pair is deleted. + * + * The @key is referenced by the object, you must not free it during + * the lifetime of the object. When in doubt, use json_strdup(). + **/ void json_object_set(struct json_node *n, const char *key, struct json_node *value); + +/** Returns the value associated with @key, or NULL if no such value exists. **/ struct json_node *json_object_get(struct json_node *n, const char *key); +/*** + * === Parser + * + * The simplest way to parse a complete JSON file is to call json_parse(), + * which returns a value tree representing the contents of the file. + * + * Alternatively, you can read the input token by token: call json_set_input() + * and then repeat json_next_token(). If you are parsing huge JSON files, + * you probably want to do json_push() first, then scan and process some + * tokens, and then json_pop(). + * + * All parsing functions throw LibUCW exceptions of class `ucw.json.parse` + * upon errors. If you want to catch them, call the parser inside + * a transaction. + ***/ + +/** Parses a JSON file from the given fastbuf stream. **/ +struct json_node *json_parse(struct json_context *js, struct fastbuf *fb); + +/** Selects the given fastbuf stream as parser input. **/ void json_set_input(struct json_context *js, struct fastbuf *in); -struct json_node *json_peek_token(struct json_context *js); + +/** Reads the next token from the input. **/ struct json_node *json_next_token(struct json_context *js); -struct json_node *json_next_object(struct json_context *js); +/** Reads the next token, but keeps it in the input. **/ +struct json_node *json_peek_token(struct json_context *js); + +/** Reads the next JSON value, including nested values. **/ +struct json_node *json_next_value(struct json_context *js); -struct json_node *json_parse(struct json_context *js, struct fastbuf *fb); +/*** + * === Writer + * + * JSON files can be produced by simply calling json_write(). + * + * If you want to generate the output on the fly (for example if it is huge), + * call json_set_output() and then iterate json_write_value(). + * + * By default, we produce a single-line compact representation, + * but you can choose differently by setting the appropriate + * `format_options` in the `json_context`. + ***/ + +/** Writes a JSON file to the given fastbuf stream, containing the JSON value @n. **/ +void json_write(struct json_context *js, struct fastbuf *fb, struct json_node *n); + +/** Selects the given fastbuf stream as output. **/ +void json_set_output(struct json_context *js, struct fastbuf *fb); + +/** Writes a single JSON value to the output stream. **/ +void json_write_value(struct json_context *js, struct json_node *n); + +/** Formatting options. The `format_options` field in the context is a bitwise OR of these flags. **/ +enum json_format_option { + JSON_FORMAT_ESCAPE_NONASCII = 1, // Produce pure ASCII output by escaping all Unicode characters in strings + JSON_FORMAT_INDENT = 2, // Produce pretty indented output +}; #endif