{"thread":{"id":"63467","subject":"[GSoC PATCH v3 0/2] json-writer: describe the jw_* functions","startedAt":"2025-05-16T01:02:27Z","lastAt":"2025-05-16T16:42:34Z","messageCount":5,"participants":["Lucas Seiki Oshiro","Karthik Nayak","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":2},"messages":[{"id":"518193","messageId":"20250516010159.27042-1-lucasseikioshiro@gmail.com","threadId":"63467","inReplyTo":null,"subject":"[GSoC PATCH v3 0/2] json-writer: describe the jw_* functions","fromName":"Lucas Seiki Oshiro","fromEmail":"lucasseikioshiro@gmail.com","sentAt":"2025-05-16T01:01:57Z","receivedAt":"2025-05-16T01:02:27Z","isPatch":true,"sender":{"key":"lucasseikioshiro@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701580?v=4"},"body":"Hello, again!\n\nIn this v3 I did some minor adjustments based on the review of v2\n(https://lore.kernel.org/git/20250512020935.73140-1-lucasseikioshiro@gmail.com/).\n\nLucas Seiki Oshiro (2):\n json-writer: add docstrings to jw_* functions\n json-writer: describe the usage of jw_* functions\n\n json-writer.c | 4 --\n json-writer.h | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++\n 2 files changed, 171 insertions(+), 4 deletions(-)\n\n-- \n2.39.5 (Apple Git-154)\n\n"},{"id":"518194","messageId":"20250516010159.27042-2-lucasseikioshiro@gmail.com","threadId":"63467","inReplyTo":"20250516010159.27042-1-lucasseikioshiro@gmail.com","subject":"[GSoC PATCH v3 1/2] json-writer: add docstrings to jw_* functions","fromName":"Lucas Seiki Oshiro","fromEmail":"lucasseikioshiro@gmail.com","sentAt":"2025-05-16T01:01:58Z","receivedAt":"2025-05-16T01:02:35Z","isPatch":true,"sender":{"key":"lucasseikioshiro@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701580?v=4"},"body":"Add a docstring for each function that manipulates json_writers.\n\nHelped-by: Junio C Hamano \nHelped-by: Patrick Steinhardt \nHelped-by: Karthik Nayak \nSigned-off-by: Lucas Seiki Oshiro \n---\n json-writer.c | 4 --\n json-writer.h | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++\n 2 files changed, 143 insertions(+), 4 deletions(-)\n\ndiff --git a/json-writer.c b/json-writer.c\nindex 8c5187e9fd..34577dc25f 100644\n--- a/json-writer.c\n+++ b/json-writer.c\n@@ -268,10 +268,6 @@ static void append_sub_jw(struct json_writer *jw,\n \tstrbuf_addbuf(&jw->json, &value->json);\n }\n \n-/*\n- * Append existing (properly terminated) JSON sub-data (object or array)\n- * as-is onto the given JSON data.\n- */\n void jw_object_sub_jw(struct json_writer *jw, const char *key,\n \t\t const struct json_writer *value)\n {\ndiff --git a/json-writer.h b/json-writer.h\nindex 04413bd1af..0e8e6c3ddc 100644\n--- a/json-writer.h\n+++ b/json-writer.h\n@@ -69,42 +69,185 @@ struct json_writer\n \t.open_stack = STRBUF_INIT, \\\n }\n \n+/*\n+ * Initialize a json_writer with empty values.\n+ */\n void jw_init(struct json_writer *jw);\n+\n+/*\n+ * Release the internal buffers of a json_writer.\n+ */\n void jw_release(struct json_writer *jw);\n \n+/*\n+ * Begin the json_writer using an object as the top-level data structure. If\n+ * pretty is set to 1, the result will be a human-readable and indented JSON,\n+ * and if it is set to 0 the result will be minified single-line JSON.\n+ */\n void jw_object_begin(struct json_writer *jw, int pretty);\n+\n+/*\n+ * Begin the json_writer using an array as the top-level data structure. If\n+ * pretty is set to 1, the result will be a human-readable and indented JSON,\n+ * and if it is set to 0 the result will be minified single-line JSON.\n+ */\n void jw_array_begin(struct json_writer *jw, int pretty);\n \n+/*\n+ * Append a string field to the current object of the json_writer, given its key\n+ * and its value. Trigger a BUG when not in an object.\n+ */\n void jw_object_string(struct json_writer *jw, const char *key,\n \t\t const char *value);\n+\n+/*\n+ * Append an int field to the current object of the json_writer, given its key\n+ * and its value. Trigger a BUG when not in an object.\n+ */\n void jw_object_intmax(struct json_writer *jw, const char *key, intmax_t value);\n+\n+/*\n+ * Append a double field to the current object of the json_writer, given its key\n+ * and its value. The precision parameter defines the number of significant\n+ * digits, where -1 can be used for maximum precision. Trigger a BUG when not in\n+ * an object.\n+ */\n void jw_object_double(struct json_writer *jw, const char *key, int precision,\n \t\t double value);\n+\n+/*\n+ * Append a boolean field set to true to the current object of the json_writer,\n+ * given its key. Trigger a BUG when not in an object.\n+ */\n void jw_object_true(struct json_writer *jw, const char *key);\n+\n+/*\n+ * Append a boolean field set to false to the current object of the json_writer,\n+ * given its key. Trigger a BUG when not in an object.\n+ */\n void jw_object_false(struct json_writer *jw, const char *key);\n+\n+/*\n+ * Append a boolean field to the current object of the json_writer, given its\n+ * key and its value. Trigger a BUG when not in an object.\n+ */\n void jw_object_bool(struct json_writer *jw, const char *key, int value);\n+\n+/*\n+ * Append a null field to the current object of the json_writer, given its key.\n+ * Trigger a BUG when not in an object.\n+ */\n void jw_object_null(struct json_writer *jw, const char *key);\n+\n+/*\n+ * Append a field to the current object of the json_writer, given its key and\n+ * another json_writer that represents its content. Trigger a BUG when not in\n+ * an object.\n+ */\n void jw_object_sub_jw(struct json_writer *jw, const char *key,\n \t\t const struct json_writer *value);\n \n+/*\n+ * Start an object as the value of a field in the current object of the\n+ * json_writer. Trigger a BUG when not in an object.\n+ */\n void jw_object_inline_begin_object(struct json_writer *jw, const char *key);\n+\n+/*\n+ * Start an array as the value of a field in the current object of the\n+ * json_writer. Trigger a BUG when not in an object.\n+ */\n void jw_object_inline_begin_array(struct json_writer *jw, const char *key);\n \n+/*\n+ * Append a string value to the current array of the json_writer. Trigger a BUG\n+ * when not in an array.\n+ */\n void jw_array_string(struct json_writer *jw, const char *value);\n+\n+/*\n+ * Append an int value to the current array of the json_writer. Trigger a BUG\n+ * when not in an array.\n+ */\n void jw_array_intmax(struct json_writer *jw, intmax_t value);\n+\n+/*\n+ * Append a double value to the current array of the json_writer. The precision\n+ * parameter defines the number of significant digits, where -1 can be used for\n+ * maximum precision. Trigger a BUG when not in an array.\n+ */\n void jw_array_double(struct json_writer *jw, int precision, double value);\n+\n+/*\n+ * Append a true value to the current array of the json_writer. Trigger a BUG\n+ * when not in an array.\n+ */\n void jw_array_true(struct json_writer *jw);\n+\n+/*\n+ * Append a false value to the current array of the json_writer. Trigger a BUG\n+ * when not in an array.\n+ */\n void jw_array_false(struct json_writer *jw);\n+\n+/*\n+ * Append a boolean value to the current array of the json_writer. Trigger a BUG\n+ * when not in an array.\n+ */\n void jw_array_bool(struct json_writer *jw, int value);\n+\n+/*\n+ * Append a null value to the current array of the json_writer. Trigger a BUG\n+ * when not in an array.\n+ */\n void jw_array_null(struct json_writer *jw);\n+\n+/*\n+ * Append a json_writer as a value to the current array of the\n+ * json_writer. Trigger a BUG when not in an array.\n+ */\n void jw_array_sub_jw(struct json_writer *jw, const struct json_writer *value);\n+\n+/*\n+ * Append the first argc values from the argv array of strings to the current\n+ * array of the json_writer. Trigger a BUG when not in an array.\n+ *\n+ * This function does not provide safety for cases where the array has less than\n+ * argc values.\n+ */\n void jw_array_argc_argv(struct json_writer *jw, int argc, const char **argv);\n+\n+/*\n+ * Append a null-terminated array of strings to the current array of the\n+ * json_writer. Trigger a BUG when not in an array.\n+ */\n void jw_array_argv(struct json_writer *jw, const char **argv);\n \n+/*\n+ * Start an object as a value in the current array of the json_writer. Trigger a\n+ * BUG when not in an array.\n+ */\n void jw_array_inline_begin_object(struct json_writer *jw);\n+\n+/*\n+ * Start an array as a value in the current array. Trigger a BUG when not in an\n+ * array.\n+ */\n void jw_array_inline_begin_array(struct json_writer *jw);\n \n+/*\n+ * Return whether the json_writer is terminated. In other words, if the all the\n+ * objects and arrays are already closed.\n+ */\n int jw_is_terminated(const struct json_writer *jw);\n+\n+/*\n+ * Terminates the current object or array of the json_writer. In other words,\n+ * append a ] if the current array is not closed or } if the current object\n+ * is not closed.\n+ *\n+ * Abort the execution if there's no object or array that can be terminated.\n+ */\n void jw_end(struct json_writer *jw);\n \n #endif /* JSON_WRITER_H */\n-- \n2.39.5 (Apple Git-154)\n\n"},{"id":"518195","messageId":"20250516010159.27042-3-lucasseikioshiro@gmail.com","threadId":"63467","inReplyTo":"20250516010159.27042-1-lucasseikioshiro@gmail.com","subject":"[GSoC PATCH v3 2/2] json-writer: describe the usage of jw_* functions","fromName":"Lucas Seiki Oshiro","fromEmail":"lucasseikioshiro@gmail.com","sentAt":"2025-05-16T01:01:59Z","receivedAt":"2025-05-16T01:03:13Z","isPatch":true,"sender":{"key":"lucasseikioshiro@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701580?v=4"},"body":"Provide an overview of the set of functions used for manipulating\n`json_writer`s, by describing what functions should be used for\neach JSON-related task.\n\nHelped-by: Junio C Hamano \nHelped-by: Patrick Steinhardt \nHelped-by: Karthik Nayak \nSigned-off-by: Lucas Seiki Oshiro \n---\n json-writer.h | 28 ++++++++++++++++++++++++++++\n 1 file changed, 28 insertions(+)\n\ndiff --git a/json-writer.h b/json-writer.h\nindex 0e8e6c3ddc..8f845d4d29 100644\n--- a/json-writer.h\n+++ b/json-writer.h\n@@ -28,6 +28,34 @@\n * object/array) -or- by building them inline in one pass. This is a\n * personal style and/or data shape choice.\n *\n+ * USAGE:\n+ * ======\n+ *\n+ * - Initialize the json_writer with jw_init.\n+ *\n+ * - Open an object as the main data structure with jw_object_begin.\n+ * Append a key-value pair to it using the jw_object_ functions.\n+ * Conclude with jw_end.\n+ *\n+ * - Alternatively, open an array as the main data structure with\n+ * jw_array_begin. Append a value to it using the jw_array_\n+ * functions. Conclude with jw_end.\n+ *\n+ * - Append a new, unterminated array or object to the current\n+ * object using the jw_object_inline_begin_{array, object} functions.\n+ * Similarly, append a new, unterminated array or object to\n+ * the current array using the jw_array_inline_begin_{array, object}\n+ * functions.\n+ *\n+ * - Append other json_writer as a value to the current array or object\n+ * using the jw_{array, object}_sub_jw functions.\n+ *\n+ * - Extend the current array with an null-terminated array of strings\n+ * by using jw_array_argv or with a fixed number of elements of a\n+ * array of string by using jw_array_argc_argv.\n+ *\n+ * - Release the json_writer after using it by calling jw_release.\n+ *\n * See t/helper/test-json-writer.c for various usage examples.\n *\n * LIMITATIONS:\n-- \n2.39.5 (Apple Git-154)\n\n"},{"id":"518219","messageId":"CAOLa=ZSH4CUdAUOT7H4B+2dwgfx22wJxxjt0SqPavAnEsdkHMA@mail.gmail.com","threadId":"63467","inReplyTo":"20250516010159.27042-1-lucasseikioshiro@gmail.com","subject":"Re: [GSoC PATCH v3 0/2] json-writer: describe the jw_* functions","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2025-05-16T08:59:22Z","receivedAt":"2025-05-16T08:59:25Z","isPatch":true,"sender":{"key":"karthik.188@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1786334?v=4"},"body":"Lucas Seiki Oshiro writes:\n\n> Hello, again!\n>\n> In this v3 I did some minor adjustments based on the review of v2\n> (https://lore.kernel.org/git/20250512020935.73140-1-lucasseikioshiro@gmail.com/).\n>\n\nThis version looks good to me, thanks for the update.\n\nI do have some general suggestions (not requirements):\n- It would be nice if these patch versions were inlined with the\n previous ones. Makes it easier to compare versions while reviewing.\n- Perhaps include a range-diff to make it easier to review the changes\n in the new version compared to the last one.\n\nI can totally recommend b4 (https://b4.docs.kernel.org/en/latest/), it\nhelps manage both of the points I mentioned :)\n\n> Lucas Seiki Oshiro (2):\n> json-writer: add docstrings to jw_* functions\n> json-writer: describe the usage of jw_* functions\n>\n> json-writer.c | 4 --\n> json-writer.h | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++\n> 2 files changed, 171 insertions(+), 4 deletions(-)\n>\n> --\n> 2.39.5 (Apple Git-154)\n"},{"id":"518267","messageId":"xmqq7c2gwlqf.fsf@gitster.g","threadId":"63467","inReplyTo":"CAOLa=ZSH4CUdAUOT7H4B+2dwgfx22wJxxjt0SqPavAnEsdkHMA@mail.gmail.com","subject":"Re: [GSoC PATCH v3 0/2] json-writer: describe the jw_* functions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-05-16T16:42:32Z","receivedAt":"2025-05-16T16:42:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Karthik Nayak writes:\n\n> Lucas Seiki Oshiro writes:\n>\n>> Hello, again!\n>>\n>> In this v3 I did some minor adjustments based on the review of v2\n>> (https://lore.kernel.org/git/20250512020935.73140-1-lucasseikioshiro@gmail.com/).\n>>\n>\n> This version looks good to me, thanks for the update.\n\nYup, the result reads very well. Thanks, all.\n\n> I do have some general suggestions (not requirements):\n> - It would be nice if these patch versions were inlined with the\n> previous ones. Makes it easier to compare versions while reviewing.\n\n\"git send-email --in-reply-to=...\" is a good tool to use.\n\n> - Perhaps include a range-diff to make it easier to review the changes\n> in the new version compared to the last one.\n\nHere, \"git format-patch --range-diff=...\" can help when preparing the\npatches to be sent.\n\n> I can totally recommend b4 (https://b4.docs.kernel.org/en/latest/), it\n> helps manage both of the points I mentioned :)\n\n... and more, by helping on the receiving end, too ;-).\n"}]}