feature: add option for pretty encoding

skewb1k · skewb1k · commit 912817c0a3c4 · 2025-08-25T22:12:22.000+03:00
diff --git a/README.md b/README.md
@@ -16,6 +16,7 @@ Table of Contents
     * [encode_number_precision](#encode_number_precision)
     * [encode_escape_forward_slash](#encode_escape_forward_slash)
     * [encode_skip_unsupported_value_types](#encode_skip_unsupported_value_types)
+    * [encode_pretty](#encode_pretty)
     * [decode_array_with_array_mt](#decode_array_with_array_mt)
 
 Description
@@ -201,6 +202,41 @@ This will generate:
 
 [Back to TOC](#table-of-contents)
 
+encode_pretty
+----------------------------
+**syntax:** `cjson.encode_pretty(enabled, indent, item_separator, key_separator)`
+
+If enabled, JSON values encoded by `cjson.encode()` will be formatted in a human-readable way, using indentation and separators.
+The strings for indent and separators must contain only spaces, tabs, line feeds (LF), or carriage returns (CR).
+
+- enabled: (boolean|string|nil, default: false)
+    Enables or disables pretty-formatting. Accepts `true`/`false` or `"on"`/`"off"`.
+
+- indent: (string|integer|nil, default: 2) Controls the indentation for nested levels.
+  - If an integer, that many spaces are used per level.
+  - If a string, the string itself is repeated for each level.
+
+- item_separator: (string|nil, default: "\n") Separator inserted between array elements and object members.
+
+- key_separator: (string|nil, default: " ") Separator inserted after the colon between an object key and its value.
+
+Example:
+
+```lua
+local cjson = require "cjson"
+
+cjson.encode_pretty(true)
+print(cjson.encode({ a = 1, b = { c = 2 } }))
+-- {
+--   "a": 1,
+--   "b": {
+--     "c": 2
+--   }
+-- }
+```
+
+[Back to TOC](#table-of-contents)
+
 decode_array_with_array_mt
 --------------------------
 **syntax:** `cjson.decode_array_with_array_mt(enabled)`
diff --git a/lua_cjson.c b/lua_cjson.c
@@ -91,6 +91,10 @@
 #define DEFAULT_DECODE_ARRAY_WITH_ARRAY_MT 0
 #define DEFAULT_ENCODE_ESCAPE_FORWARD_SLASH 1
 #define DEFAULT_ENCODE_SKIP_UNSUPPORTED_VALUE_TYPES 0
+#define DEFAULT_ENCODE_PRETTY_ENABLED 0
+#define DEFAULT_ENCODE_PRETTY_INDENT "  "
+#define DEFAULT_ENCODE_PRETTY_ITEM_SEPARATOR "\n"
+#define DEFAULT_ENCODE_PRETTY_KEY_SEPARATOR " "
 
 #ifdef DISABLE_INVALID_NUMBERS
 #undef DEFAULT_DECODE_INVALID_NUMBERS
@@ -172,6 +176,10 @@ typedef struct {
     int encode_keep_buffer;
     int encode_empty_table_as_object;
     int encode_escape_forward_slash;
+    int encode_pretty_enabled;
+    const char *encode_pretty_indent;
+    const char *encode_pretty_item_separator;
+    const char *encode_pretty_key_separator;
 
     int decode_invalid_numbers;
     int decode_max_depth;
@@ -310,6 +318,18 @@ static int json_enum_option(lua_State *l, int optindex, int *setting,
     return 1;
 }
 
+/* Process string option for a configuration function */
+static int json_string_option(lua_State *l, int optindex, const char **setting)
+{
+    if (!lua_isnil(l, optindex)) {
+        const char *value = luaL_checkstring(l, optindex);
+        *setting = value;
+    }
+
+    lua_pushstring(l, *setting ? *setting : "");
+    return 1;
+}
+
 /* Configures handling of extremely sparse arrays:
  * convert: Convert extremely sparse arrays into objects? Otherwise error.
  * ratio: 0: always allow sparse; 1: never allow sparse; >1: use ratio
@@ -400,6 +420,73 @@ static int json_cfg_encode_keep_buffer(lua_State *l)
     return 1;
 }
 
+/* Returns nonzero if the string consists only of allowed whitespace characters */
+static int is_allowed_ws(const char *s) {
+    if (!s) return 0;
+    for (const unsigned char *p = (const unsigned char *)s; *p; p++) {
+        switch (*p) {
+            case 0x20: /* space */
+            case 0x09: /* tab */
+            case 0x0A: /* newline */
+            case 0x0D: /* carriage return */
+                break;
+            default:
+                return 0;
+        }
+    }
+    return 1;
+}
+
+/* Configure pretty encoding */
+static int json_cfg_encode_pretty(lua_State *l)
+{
+    json_config_t *cfg = json_arg_init(l, 4);
+
+    json_enum_option(l, 1, &cfg->encode_pretty_enabled, NULL, 1);
+
+    /* Process "indent" option, it can be either a string or a non-negative integer. */
+    int optindex = 2;
+    if (!lua_isnil(l, optindex)) {
+        if (lua_isnumber(l, optindex)) {
+            lua_Integer n = luaL_checkinteger(l, optindex);
+            luaL_argcheck(l, n >= 0, optindex, "indent must be non-negative");
+
+            luaL_argcheck(l, (unsigned long long)n <= SIZE_MAX, optindex, "indent is too large");
+            size_t indentLen = (size_t)n;
+
+            strbuf_t b;
+            strbuf_init(&b, indentLen);
+            for (size_t i = 0; i < indentLen; i++)
+                strbuf_append_char_unsafe(&b, ' ');
+
+            cfg->encode_pretty_indent = strbuf_free_to_string(&b, &indentLen);
+        } else if (lua_isstring(l, optindex)) {
+            const char *indent = luaL_checkstring(l, optindex);
+            if (!is_allowed_ws(indent))
+                luaL_argerror(l, optindex, "indent may only contain space, tab, LF, or CR");
+            cfg->encode_pretty_indent = indent;
+        } else {
+            luaL_argerror(l, optindex, "string or number expected");
+        }
+    }
+    lua_pushstring(l, cfg->encode_pretty_indent ? cfg->encode_pretty_indent : "");
+
+
+    const char *item_separator = cfg->encode_pretty_item_separator;
+    json_string_option(l, 3, &item_separator);
+    if (!is_allowed_ws(item_separator))
+        luaL_argerror(l, optindex, "item_separator may only contain space, tab, LF, or CR");
+    cfg->encode_pretty_item_separator = item_separator;
+
+    const char *key_separator = cfg->encode_pretty_key_separator;
+    json_string_option(l, 4, &key_separator);
+    if (!is_allowed_ws(key_separator))
+        luaL_argerror(l, optindex, "key_separator may only contain space, tab, LF, or CR");
+    cfg->encode_pretty_key_separator = key_separator;
+
+    return 4;
+}
+
 #if defined(DISABLE_INVALID_NUMBERS) && !defined(USE_INTERNAL_FPCONV)
 void json_verify_invalid_number_setting(lua_State *l, int *setting)
 {
@@ -491,6 +578,10 @@ static void json_create_config(lua_State *l)
     cfg->decode_array_with_array_mt = DEFAULT_DECODE_ARRAY_WITH_ARRAY_MT;
     cfg->encode_escape_forward_slash = DEFAULT_ENCODE_ESCAPE_FORWARD_SLASH;
     cfg->encode_skip_unsupported_value_types = DEFAULT_ENCODE_SKIP_UNSUPPORTED_VALUE_TYPES;
+    cfg->encode_pretty_enabled = DEFAULT_ENCODE_PRETTY_ENABLED;
+    cfg->encode_pretty_indent = DEFAULT_ENCODE_PRETTY_INDENT;
+    cfg->encode_pretty_item_separator = DEFAULT_ENCODE_PRETTY_ITEM_SEPARATOR;
+    cfg->encode_pretty_key_separator = DEFAULT_ENCODE_PRETTY_KEY_SEPARATOR;
 
 #if DEFAULT_ENCODE_KEEP_BUFFER > 0
     strbuf_init(&cfg->encode_buf, 0);
@@ -660,6 +751,13 @@ static void json_check_encode_depth(lua_State *l, json_config_t *cfg,
 static int json_append_data(lua_State *l, json_config_t *cfg,
                              int current_depth, strbuf_t *json);
 
+static void json_append_item_separator_and_indent(strbuf_t *json, json_config_t *cfg, int depth)
+{
+    strbuf_append_string(json, cfg->encode_pretty_item_separator);
+    for (int i = 0; i < depth; i++)
+        strbuf_append_string(json, cfg->encode_pretty_indent);
+}
+
 /* json_append_array args:
  * - lua_State
  * - JSON strbuf
@@ -668,15 +766,21 @@ static void json_append_array(lua_State *l, json_config_t *cfg, int current_dept
                               strbuf_t *json, int array_length, int raw)
 {
     int comma, i, json_pos, err;
+    int has_items = 0;
 
     strbuf_append_char(json, '[');
 
     comma = 0;
     for (i = 1; i <= array_length; i++) {
+        has_items = 1;
+
         json_pos = strbuf_length(json);
         if (comma++ > 0)
             strbuf_append_char(json, ',');
 
+        if (cfg->encode_pretty_enabled)
+            json_append_item_separator_and_indent(json, cfg, current_depth);
+
         if (raw) {
             lua_rawgeti(l, -1, i);
         } else {
@@ -698,6 +802,9 @@ static void json_append_array(lua_State *l, json_config_t *cfg, int current_dept
         lua_pop(l, 1);
     }
 
+    if (has_items && cfg->encode_pretty_enabled)
+        json_append_item_separator_and_indent(json, cfg, current_depth-1);
+
     strbuf_append_char(json, ']');
 }
 
@@ -752,6 +859,7 @@ static void json_append_object(lua_State *l, json_config_t *cfg,
                                int current_depth, strbuf_t *json)
 {
     int comma, keytype, json_pos, err;
+    int has_items = 0;
 
     /* Object */
     strbuf_append_char(json, '{');
@@ -760,10 +868,15 @@ static void json_append_object(lua_State *l, json_config_t *cfg,
     /* table, startkey */
     comma = 0;
     while (lua_next(l, -2) != 0) {
+        has_items = 1;
+
         json_pos = strbuf_length(json);
         if (comma++ > 0)
             strbuf_append_char(json, ',');
 
+        if (cfg->encode_pretty_enabled)
+            json_append_item_separator_and_indent(json, cfg, current_depth);
+
         /* table, key, value */
         keytype = lua_type(l, -2);
         if (keytype == LUA_TNUMBER) {
@@ -778,6 +891,8 @@ static void json_append_object(lua_State *l, json_config_t *cfg,
                                   "table key must be a number or string");
             /* never returns */
         }
+        if (cfg->encode_pretty_enabled)
+            strbuf_append_string(json, cfg->encode_pretty_key_separator);
 
         /* table, key, value */
         err = json_append_data(l, cfg, current_depth, json);
@@ -792,6 +907,9 @@ static void json_append_object(lua_State *l, json_config_t *cfg,
         /* table, key */
     }
 
+    if (has_items && cfg->encode_pretty_enabled)
+        json_append_item_separator_and_indent(json, cfg, current_depth-1);
+
     strbuf_append_char(json, '}');
 }
 
@@ -1571,6 +1689,7 @@ static int lua_cjson_new(lua_State *l)
         { "decode_invalid_numbers", json_cfg_decode_invalid_numbers },
         { "encode_escape_forward_slash", json_cfg_encode_escape_forward_slash },
         { "encode_skip_unsupported_value_types", json_cfg_encode_skip_unsupported_value_types },
+        { "encode_pretty", json_cfg_encode_pretty },
         { "new", lua_cjson_new },
         { NULL, NULL }
     };
diff --git a/tests/test.lua b/tests/test.lua
@@ -333,6 +333,58 @@ local cjson_tests = {
       json.decode, { [["\uDB00\uD"]] },
       false, { "Expected value but found invalid unicode escape code at character 2" } },
 
+    -- Test pretty encoding
+    { "Set encode_pretty(true)",
+      json.encode_pretty, { true }, true, { true, "  ", "\n", " " } },
+    { "Encode simple object",
+      json.encode, { { a = "a", b = "b" } },
+      true, {
+          util.one_of {
+              '{\n  "a": "a",\n  "b": "b"\n}',
+              '{\n  "b": "b",\n  "a": "a"\n}',
+          }
+      } },
+    { "Encode empty object",
+      json.encode, { { } }, true, { '{}' } },
+    { "Encode nested object",
+      json.encode, { { a = { b = 1 } } },
+      true, { '{\n  "a": {\n    "b": 1\n  }\n}' } },
+    { "Encode simple array",
+      json.encode, { { 1, 2, 3 } },
+      true, { '[\n  1,\n  2,\n  3\n]' } },
+    { "Encode empty array",
+      json.encode, { json.empty_array }, true, { '[]' } },
+    { "Encode nested arrays",
+      json.encode, { { { 1, 2 }, { 3, 4 } } },
+      true, { '[\n  [\n    1,\n    2\n  ],\n  [\n    3,\n    4\n  ]\n]' } },
+    { "Encode array of objects",
+      json.encode, { { { a = "a" }, { b = "b" } } },
+      true, { '[\n  {\n    "a": "a"\n  },\n  {\n    "b": "b"\n  }\n]' } },
+      -- Custom options
+    { 'Set encode_pretty(true, "\t", "\r\n", "")',
+      json.encode_pretty, { true, "\t", "\r\n", "" }, true, { true, "\t", "\r\n", "" } },
+    { "Encode array of objects with custom options",
+      json.encode, { { { a = "a" }, { b = "b" } } },
+      true, { '[\r\n\t{\r\n\t\t"a":"a"\r\n\t},\r\n\t{\r\n\t\t"b":"b"\r\n\t}\r\n]' } },
+      -- Integer indent
+    { 'Set encode_pretty(true, 4, "\r\n", "")',
+      json.encode_pretty, { true, 4, "\r\n", "" }, true, { true, "    ", "\r\n", "" } },
+    { "Encode array of objects with custom options",
+      json.encode, { { { a = "a" }, { b = "b" } } },
+      true, { '[\r\n    {\r\n        "a":"a"\r\n    },\r\n    {\r\n        "b":"b"\r\n    }\r\n]' } },
+      -- Invalid options
+    { 'Set encode_pretty(true, 4, "c", "")',
+      json.encode_pretty, { true, 4, "c", "" }, false,
+      {
+          util.one_of {
+              "bad argument #2 to '?' (item_separator may only contain space, tab, LF, or CR)",
+              "bad argument #2 to 'cjson.encode_pretty' (item_separator may only contain space, tab, LF, or CR)"
+          }
+      }
+    },
+    { "Set encode_pretty(false)",
+      json.encode_pretty, { false }, true, { false, "    ", "\r\n", "" } },
+
     -- Test locale support
     --
     -- The standard Lua interpreter is ANSI C online doesn't support locales
