kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

json-writer: add docstrings to jw_* functions 

Add a docstring for each function that manipulates json_writers.

Helped-by: Junio C Hamano <gitster@pobox.com>
Helped-by: Patrick Steinhardt <ps@pks.im>
Helped-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
Acked-by: Karthik Nayak <karthik.188@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
maint
Lucas Seiki Oshiro 2025-05-15 22:01:58 -03:00 committed by Junio C Hamano
parent cb96e1697a
commit fba60a4841
2 changed files with 143 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
json-writer.c
View File

@ -268,10 +268,6 @@ static void append_sub_jw(struct json_writer *jw,
strbuf_addbuf(&jw->json, &value->json);
}

/*
* Append existing (properly terminated) JSON sub-data (object or array)
* as-is onto the given JSON data.
*/
void jw_object_sub_jw(struct json_writer *jw, const char *key,
const struct json_writer *value)
{

143
json-writer.h
View File

@ -69,42 +69,185 @@ struct json_writer
.open_stack = STRBUF_INIT, \
}

/*
* Initialize a json_writer with empty values.
*/
void jw_init(struct json_writer *jw);

/*
* Release the internal buffers of a json_writer.
*/
void jw_release(struct json_writer *jw);

/*
* Begin the json_writer using an object as the top-level data structure. If
* pretty is set to 1, the result will be a human-readable and indented JSON,
* and if it is set to 0 the result will be minified single-line JSON.
*/
void jw_object_begin(struct json_writer *jw, int pretty);

/*
* Begin the json_writer using an array as the top-level data structure. If
* pretty is set to 1, the result will be a human-readable and indented JSON,
* and if it is set to 0 the result will be minified single-line JSON.
*/
void jw_array_begin(struct json_writer *jw, int pretty);

/*
* Append a string field to the current object of the json_writer, given its key
* and its value. Trigger a BUG when not in an object.
*/
void jw_object_string(struct json_writer *jw, const char *key,
const char *value);

/*
* Append an int field to the current object of the json_writer, given its key
* and its value. Trigger a BUG when not in an object.
*/
void jw_object_intmax(struct json_writer *jw, const char *key, intmax_t value);

/*
* Append a double field to the current object of the json_writer, given its key
* and its value. The precision parameter defines the number of significant
* digits, where -1 can be used for maximum precision. Trigger a BUG when not in
* an object.
*/
void jw_object_double(struct json_writer *jw, const char *key, int precision,
double value);

/*
* Append a boolean field set to true to the current object of the json_writer,
* given its key. Trigger a BUG when not in an object.
*/
void jw_object_true(struct json_writer *jw, const char *key);

/*
* Append a boolean field set to false to the current object of the json_writer,
* given its key. Trigger a BUG when not in an object.
*/
void jw_object_false(struct json_writer *jw, const char *key);

/*
* Append a boolean field to the current object of the json_writer, given its
* key and its value. Trigger a BUG when not in an object.
*/
void jw_object_bool(struct json_writer *jw, const char *key, int value);

/*
* Append a null field to the current object of the json_writer, given its key.
* Trigger a BUG when not in an object.
*/
void jw_object_null(struct json_writer *jw, const char *key);

/*
* Append a field to the current object of the json_writer, given its key and
* another json_writer that represents its content. Trigger a BUG when not in
* an object.
*/
void jw_object_sub_jw(struct json_writer *jw, const char *key,
const struct json_writer *value);

/*
* Start an object as the value of a field in the current object of the
* json_writer. Trigger a BUG when not in an object.
*/
void jw_object_inline_begin_object(struct json_writer *jw, const char *key);

/*
* Start an array as the value of a field in the current object of the
* json_writer. Trigger a BUG when not in an object.
*/
void jw_object_inline_begin_array(struct json_writer *jw, const char *key);

/*
* Append a string value to the current array of the json_writer. Trigger a BUG
* when not in an array.
*/
void jw_array_string(struct json_writer *jw, const char *value);

/*
* Append an int value to the current array of the json_writer. Trigger a BUG
* when not in an array.
*/
void jw_array_intmax(struct json_writer *jw, intmax_t value);

/*
* Append a double value to the current array of the json_writer. The precision
* parameter defines the number of significant digits, where -1 can be used for
* maximum precision. Trigger a BUG when not in an array.
*/
void jw_array_double(struct json_writer *jw, int precision, double value);

/*
* Append a true value to the current array of the json_writer. Trigger a BUG
* when not in an array.
*/
void jw_array_true(struct json_writer *jw);

/*
* Append a false value to the current array of the json_writer. Trigger a BUG
* when not in an array.
*/
void jw_array_false(struct json_writer *jw);

/*
* Append a boolean value to the current array of the json_writer. Trigger a BUG
* when not in an array.
*/
void jw_array_bool(struct json_writer *jw, int value);

/*
* Append a null value to the current array of the json_writer. Trigger a BUG
* when not in an array.
*/
void jw_array_null(struct json_writer *jw);

/*
* Append a json_writer as a value to the current array of the
* json_writer. Trigger a BUG when not in an array.
*/
void jw_array_sub_jw(struct json_writer *jw, const struct json_writer *value);

/*
* Append the first argc values from the argv array of strings to the current
* array of the json_writer. Trigger a BUG when not in an array.
*
* This function does not provide safety for cases where the array has less than
* argc values.
*/
void jw_array_argc_argv(struct json_writer *jw, int argc, const char **argv);

/*
* Append a null-terminated array of strings to the current array of the
* json_writer. Trigger a BUG when not in an array.
*/
void jw_array_argv(struct json_writer *jw, const char **argv);

/*
* Start an object as a value in the current array of the json_writer. Trigger a
* BUG when not in an array.
*/
void jw_array_inline_begin_object(struct json_writer *jw);

/*
* Start an array as a value in the current array. Trigger a BUG when not in an
* array.
*/
void jw_array_inline_begin_array(struct json_writer *jw);

/*
* Return whether the json_writer is terminated. In other words, if the all the
* objects and arrays are already closed.
*/
int jw_is_terminated(const struct json_writer *jw);

/*
* Terminates the current object or array of the json_writer. In other words,
* append a ] if the current array is not closed or } if the current object
* is not closed.
*
* Abort the execution if there's no object or array that can be terminated.
*/
void jw_end(struct json_writer *jw);

#endif /* JSON_WRITER_H */