feat(json): add pretty option for vim.json.encode()

Problem:
There is no straightforward way to pretty-print objects as JSON.
The existing `vim.inspect` outputs LON.

Solution:
Introduce `pretty` option for `vim.json.encode()`, which enables
pretty-formatting when table provided or `true`. Supports the following keys:

- indent: (integer|string) (default 2) Controls how nested levels are indented.
  - If a integer: indents that many spaces per nesting level.
  - If a string: that string is used for the indentation.
- item_separator: (string) (default "\n") Separator inserted between array elements and object members.
- key_separator: (string) (default " ") Separator inserted after the colon between an object key and its value.

Adapts PR to upstream: openresty/lua-cjson#114.

Author: skewb1k

runtime/doc/lua.txt

@@ -3375,6 +3375,24 @@ vim.json.encode({obj}, {opts})                             *vim.json.encode()*
       • {opts}  (`table<string,any>?`) Options table with keys:
                 • escape_slash: (boolean) (default false) Escape slash
                   characters "/" in string values.
+                • pretty: (table|boolean) (default false) Enables
+                  pretty-formatting when provided or `true`. Supports the
+                  following keys:
+                  • indent: (integer|string) (default 2) Controls how nested
+                    levels are indented.
+                    • If a integer: indents that many spaces per nesting
+                      level.
+                    • If a string: that string is used for the indentation.
+                      Must contain only spaces, tabs, line feeds (LF), or
+                      carriage returns (CR).
+                  • item_separator: (string) (default "\n") Separator inserted
+                    between array elements and object members. Must contain
+                    only spaces, tabs, line feeds (LF), or carriage returns
+                    (CR).
+                  • key_separator: (string) (default " ") Separator inserted
+                    after the colon between an object key and its value. Must
+                    contain only spaces, tabs, line feeds (LF), or carriage
+                    returns (CR).
 
     Return: ~
         (`string`)

runtime/doc/news.txt

@@ -247,6 +247,7 @@ LUA
 • |vim.list.unique()| to deduplicate lists.
 • |vim.list.bisect()| for binary search.
 • Experimental `vim.pos` and `vim.range` for Position/Range abstraction.
+• |vim.json.encode()| has an option for pretty-formatting.
 
 OPTIONS
 

runtime/lua/vim/_meta/json.lua

@@ -38,5 +38,11 @@ function vim.json.decode(str, opts) end
 ---@param opts? table<string,any> Options table with keys:
 ---                                 - escape_slash: (boolean) (default false) Escape slash
 ---                                   characters "/" in string values.
+---                                 - pretty: (table|boolean) (default false) Enables pretty-formatting when provided or `true`. Supports the following keys:
+---                                   - indent: (integer|string) (default 2) Controls how nested levels are indented.
+---                                     - If a integer: indents that many spaces per nesting level.
+---                                     - If a string: that string is used for the indentation. Must contain only spaces, tabs, line feeds (LF), or carriage returns (CR).
+---                                   - item_separator: (string) (default "\n") Separator inserted between array elements and object members. Must contain only spaces, tabs, line feeds (LF), or carriage returns (CR).
+---                                   - key_separator: (string) (default " ") Separator inserted after the colon between an object key and its value. Must contain only spaces, tabs, line feeds (LF), or carriage returns (CR).
 ---@return string
 function vim.json.encode(obj, opts) end

src/cjson/lua_cjson.c

@@ -87,6 +87,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
@@ -168,6 +172,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;
@@ -177,6 +185,10 @@ typedef struct {
 
 typedef struct {
     const char **char2escape[256];
+    int pretty_enabled;
+    const char *pretty_indent;
+    const char *pretty_item_separator;
+    const char *pretty_key_separator;
 } json_encode_options_t;
 
 typedef struct {
@@ -330,6 +342,20 @@ static int json_enum_option(lua_State *l, int optindex, int *setting,
 }
 */
 
+/* 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
@@ -436,6 +462,75 @@ static int json_cfg_encode_keep_buffer(lua_State *l)
 }
 */
 
+/* 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)
 {
@@ -533,6 +628,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);
@@ -704,6 +803,13 @@ static void json_check_encode_depth(lua_State *l, json_config_t *cfg,
 static int json_append_data(lua_State *l, json_encode_t *cfg,
                              int current_depth);
 
+static void json_append_item_separator_and_indent(strbuf_t *json, json_encode_t *ctx, int depth)
+{
+    strbuf_append_string(json, ctx->options->pretty_item_separator);
+    for (int i = 0; i < depth; i++)
+        strbuf_append_string(json, ctx->options->pretty_indent);
+}
+
 /* json_append_array args:
  * - lua_State
  * - JSON strbuf
@@ -712,15 +818,22 @@ static void json_append_array(lua_State *l, json_encode_t *ctx, int current_dept
                               int array_length, int raw)
 {
     int comma, i, json_pos, err;
+    int has_items = 0;
     strbuf_t *json = ctx->json;
 
     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 (ctx->options->pretty_enabled)
+            json_append_item_separator_and_indent(json, ctx, current_depth);
+
         if (raw) {
             lua_rawgeti(l, -1, i);
         } else {
@@ -742,6 +855,9 @@ static void json_append_array(lua_State *l, json_encode_t *ctx, int current_dept
         lua_pop(l, 1);
     }
 
+    if (has_items && ctx->options->pretty_enabled)
+        json_append_item_separator_and_indent(json, ctx, current_depth-1);
+
     strbuf_append_char(json, ']');
 }
 
@@ -798,6 +914,7 @@ static void json_append_object(lua_State *l, json_encode_t *ctx,
                                int current_depth)
 {
     int comma, keytype, json_pos, err;
+    int has_items = 0;
     strbuf_t *json = ctx->json;
 
     /* Object */
@@ -807,12 +924,17 @@ static void json_append_object(lua_State *l, json_encode_t *ctx,
     /* 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, ',');
         else
             comma = 1;
 
+        if (ctx->options->pretty_enabled)
+            json_append_item_separator_and_indent(json, ctx, current_depth);
+
         /* table, key, value */
         keytype = lua_type(l, -2);
         if (keytype == LUA_TNUMBER) {
@@ -827,6 +949,8 @@ static void json_append_object(lua_State *l, json_encode_t *ctx,
                                   "table key must be a number or string");
             /* never returns */
         }
+        if (ctx->options->pretty_enabled)
+            strbuf_append_string(json, ctx->options->pretty_key_separator);
 
         /* table, key, value */
         err = json_append_data(l, ctx, current_depth);
@@ -841,6 +965,9 @@ static void json_append_object(lua_State *l, json_encode_t *ctx,
         /* table, key */
     }
 
+    if (has_items && ctx->options->pretty_enabled)
+        json_append_item_separator_and_indent(json, ctx, current_depth-1);
+
     strbuf_append_char(json, '}');
 }
 
@@ -966,7 +1093,13 @@ static int json_append_data(lua_State *l, json_encode_t *ctx,
 static int json_encode(lua_State *l)
 {
     json_config_t *cfg = json_fetch_config(l);
-    json_encode_options_t options = { .char2escape = { char2escape } };
+    json_encode_options_t options = {
+        .char2escape = { char2escape },
+        .pretty_enabled = DEFAULT_ENCODE_PRETTY_ENABLED,
+        .pretty_indent = DEFAULT_ENCODE_PRETTY_INDENT,
+        .pretty_item_separator = DEFAULT_ENCODE_PRETTY_ITEM_SEPARATOR,
+        .pretty_key_separator = DEFAULT_ENCODE_PRETTY_KEY_SEPARATOR,
+    };
     json_encode_t ctx = { .options = &options, .cfg = cfg };
     strbuf_t local_encode_buf;
     strbuf_t *encode_buf;
@@ -979,26 +1112,69 @@ static int json_encode(lua_State *l)
         break;
     case 2:
         luaL_checktype(l, 2, LUA_TTABLE);
-        lua_getfield(l, 2, "escape_slash");
 
-        /* We only handle the escape_slash option for now */
-        if (lua_isnil(l, -1)) {
-            lua_pop(l, 2);
-            break;
+        lua_getfield(l, 2, "escape_slash");
+        if (!lua_isnil(l, -1)) {
+            luaL_checktype(l, -1, LUA_TBOOLEAN);
+
+            int escape_slash = lua_toboolean(l, -1);
+            if (escape_slash) {
+                /* This can be optimised by adding a new hard-coded escape table for this case,
+                 * but this path will rarely if ever be used, so let's just memcpy. */
+                memcpy(customChar2escape, char2escape, sizeof(char2escape));
+                customChar2escape['/'] = "\\/";
+                *ctx.options->char2escape = customChar2escape;
+            }
         }
+        lua_pop(l, 1);
 
-        luaL_checktype(l, -1, LUA_TBOOLEAN);
+        lua_getfield(l, 2, "pretty");
+        if (!lua_isnil(l, -1)) {
+            if (lua_isboolean(l, -1)) {
+                options.pretty_enabled = lua_toboolean(l, -1);
+            } else {
+                luaL_checktype(l, -1, LUA_TTABLE);
+                /* enable pretty-formatting if table provided */
+                options.pretty_enabled = 1;
+
+                lua_getfield(l, -1, "indent");
+                if (lua_isnumber(l, -1)) {
+                    lua_Integer n = luaL_checkinteger(l, -1);
+                    luaL_argcheck(l, n >= 0, 2, "indent must be non-negative");
+
+                    luaL_argcheck(l, (unsigned long long)n <= SIZE_MAX, 2, "indent too large");
+                    size_t indent_len = (size_t)n;
+
+                    strbuf_t b;
+                    strbuf_init(&b, indent_len);
+                    for (size_t i = 0; i < indent_len; i++)
+                        strbuf_append_char_unsafe(&b, ' ');
+
+                    options.pretty_indent = strbuf_free_to_string(&b, &indent_len);
+                } else if (lua_isstring(l, -1)) {
+                  options.pretty_indent = lua_tostring(l, -1);
+                  if (!is_allowed_ws(options.pretty_indent))
+                      luaL_error(l, "indent may only contain space, tab, LF, or CR");
+                }
+                lua_pop(l, 1);
 
-        int escape_slash = lua_toboolean(l, -1);
+                lua_getfield(l, -1, "item_separator");
+                if (lua_isstring(l, -1)) {
+                    options.pretty_item_separator = lua_tostring(l, -1);
+                    if (!is_allowed_ws(options.pretty_item_separator))
+                        luaL_error(l, "item_separator may only contain space, tab, LF, or CR");
+                }
+                lua_pop(l, 1);
 
-        if (escape_slash) {
-            /* This can be optimised by adding a new hard-coded escape table for this case,
-             * but this path will rarely if ever be used, so let's just memcpy.*/ 
-            memcpy(customChar2escape, char2escape, sizeof(char2escape));
-            customChar2escape['/'] = "\\/";
-            *ctx.options->char2escape = customChar2escape;
+                lua_getfield(l, -1, "key_separator");
+                if (lua_isstring(l, -1)) {
+                  options.pretty_key_separator = lua_tostring(l, -1);
+                  if (!is_allowed_ws(options.pretty_key_separator))
+                      luaL_error(l, "key_separator may only contain space, tab, LF, or CR");
+                }
+                lua_pop(l, 1);
+            }
         }
-
         lua_pop(l, 2);
         break;
     default:
@@ -1710,6 +1886,7 @@ 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 }