Merge remote-tracking branch upstream/c-coroutine

Summary of commits:
- rename json_parse to json_decode, add check for comments
- updates, document, how to/usage for json functions

docs/examples/co_json.c

@@ -5,7 +5,9 @@ int co_main(int argc, char **argv) {
                                   kv("name", "John Smith"),
                                   kv("age", 25),
                                   kv("address.city", "Cupertino"),
-                                  kv("contact.emails", json_parse(json_for("ss", "email@example.com", "email2@example.com"))));
+                                  kv("contact.emails", json_decode(
+                                      json_for("ss", "email@example.com", "email2@example.com"), false)
+                                  ));
 
     if (is_json(encoded))
         puts(json_serialize(encoded, true));

include/coroutine.h

@@ -847,12 +847,55 @@ C_API u_string base64_decode(u_string_t src);
 
 C_API int co_array_init(co_array_t *);
 
-C_API bool is_json(json_t *schema);
-C_API string json_serialize(json_t *json, bool is_pretty);
-C_API json_t *json_parse(string_t text);
-C_API json_t *json_read(string_t filename);
+/* Check if validated by json type */
+C_API bool is_json(json_t *);
+
+/**
+* @param value Serialization of value to string.
+* @param is_pretty Pretty serialization, if set `true`.
+*/
+C_API string json_serialize(json_t *, bool is_pretty);
+
+/**
+* @param text Parses first JSON value in a text, returns NULL in case of error.
+* @param is_commented Ignores comments (/ * * / and //), if set `true`.
+*/
+C_API json_t *json_decode(string_t, bool is_commented);
+
+C_API json_t *json_read(string_t filename, bool is_commented);
 C_API int json_write(string_t filename, string_t text);
+
+/**
+* Creates json value `object` using a format like `printf` for each value to key.
+*
+* @param desc format string:
+* * '`.`' indicate next format character will use dot function to record value for key name with dot,
+* * '`a`' begin array encoding, every item `value` will be appended, until '`e`' is place in format desc,
+* * '`e`' end array encoding,
+* * '`n`' record `null` value for key, *DO NOT PLACE `NULL` IN ARGUMENTS*,
+* * '`f`' record `float/double` number for key,
+* * '`d`' record `signed` number for key,
+* * '`i`' record `unsigned` number for key,
+* * '`b`' record `boolean` value for key,
+* * '`s`' record `string` value for key,
+* * '`v`' record `JSON_Value` for key,
+* @param arguments use `kv(key,value)` for pairs, *DO NOT PROVIDE FOR NULL, ONLY KEY*
+*/
 C_API json_t *json_encode(string_t desc, ...);
+
+/**
+* Creates json value string `array` using a format like `printf` for each value to index.
+*
+* @param desc format string:
+* * '`n`' record `null` value for index, *DO NOT PLACE `NULL` IN ARGUMENTS*,
+* * '`f`' record `float/double` number for index,
+* * '`d`' record `signed` number for index,
+* * '`i`' record `unsigned` number for index,
+* * '`b`' record `boolean` value for index,
+* * '`s`' record `string` value for index,
+* * '`v`' record `JSON_Value` for index,
+* @param arguments indexed by `desc` format order, *DO NOT PROVIDE FOR NULL*
+*/
 C_API string json_for(string_t desc, ...);
 
 /* Creates an unbuffered channel, similar to golang channels. */

src/json.c

@@ -22,16 +22,19 @@ ZE_FORCE_INLINE int json_write(string_t filename, string_t text) {
     return fs_write_file(filename, text);
 }
 
-ZE_FORCE_INLINE json_t *json_parse(string_t text) {
-    return json_parse_string(text);
+ZE_FORCE_INLINE json_t *json_decode(string_t text, bool is_commented) {
+    if (is_commented)
+        return json_parse_string_with_comments(text);
+    else
+        return json_parse_string(text);
 }
 
-json_t *json_read(string_t filename) {
+json_t *json_read(string_t filename, bool is_commented) {
     string file_contents = fs_readfile(filename);
     if (is_empty(file_contents))
         return NULL;
 
-    return json_parse(file_contents);
+    return json_decode(file_contents, is_commented);
 }
 
 json_t *json_encode(string_t desc, ...) {
@@ -44,7 +47,7 @@ json_t *json_encode(string_t desc, ...) {
     string key, value_char;
     int value_bool;
     JSON_Status status = JSONSuccess;
-    void_t value_any = NULL;
+    json_t *value_any = NULL;
     JSON_Array *value_array = NULL;
     double value_float = 0;
     int64_t value_int = 0;
@@ -53,6 +56,9 @@ json_t *json_encode(string_t desc, ...) {
 
     va_start(argp, desc);
     for (int i = 0; i < count; i++) {
+        if (status == JSONFailure)
+            return NULL;
+
         switch (*desc++) {
             case '.':
                 is_dot = true;
@@ -152,7 +158,7 @@ json_t *json_encode(string_t desc, ...) {
                 if (!is_array)
                     key = va_arg(argp, string);
 
-                value_any = va_arg(argp, void_t);
+                value_any = va_arg(argp, json_t *);
                 if (is_array)
                     status = json_array_append_value(value_array, value_any);
                 else if (is_dot)
@@ -181,14 +187,17 @@ string json_for(string_t desc, ...) {
     va_list argp;
     string value_char;
     int value_bool;
-    void_t value_any = NULL;
+    json_t *value_any = NULL;
     double value_float = 0;
     int64_t value_int = 0;
     size_t value_max = 0;
     bool is_double = false, is_int = false, is_max = false;
 
     va_start(argp, desc);
     for (int i = 0; i < count; i++) {
+        if (status == JSONFailure)
+            return NULL;
+
         switch (*desc++) {
             case 'n':
                 status = json_array_append_null(value_array);
@@ -225,7 +234,7 @@ string json_for(string_t desc, ...) {
                 status = json_array_append_string(value_array, value_char);
                 break;
             case 'v':
-                value_any = va_arg(argp, void_t);
+                value_any = va_arg(argp, json_t *);
                 status = json_array_append_value(value_array, value_any);
                 break;
             default: