docs: manpage, keycodes, json

runtime/lua/vim/_meta/json.lua

@@ -10,7 +10,7 @@ vim.json = {}
 --- This module provides encoding and decoding of Lua objects to and
 --- from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
 
---- Decodes (or "unpacks") the JSON-encoded {str} to a Lua object.
+--- Decodes (or "unpacks") stringified JSON to a Lua object.
 ---
 --- - Decodes JSON "null" as |vim.NIL| (controllable by {opts}, see below).
 --- - Decodes empty object as |vim.empty_dict()|.
@@ -33,7 +33,23 @@ vim.json = {}
 ---@return any
 function vim.json.decode(str, opts) end
 
---- Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
+--- Encodes (or "packs") a Lua object to stringified JSON.
+---
+--- Example: use the `indent` flag to implement a basic 'formatexpr' for JSON, so you can use |gq|
+--- with a motion to format JSON in a buffer. (The motion must operate on a valid JSON object.)
+---
+--- ```lua
+--- function _G.fmt_json()
+---   local indent = vim.bo.expandtab and (' '):rep(vim.o.shiftwidth) or '\t'
+---   local lines = vim.api.nvim_buf_get_lines(0, vim.v.lnum - 1, vim.v.lnum + vim.v.count - 1, true)
+---   local o = vim.json.decode(table.concat(lines, '\n'))
+---   local stringified = vim.json.encode(o, { indent = indent })
+---   lines = vim.split(stringified, '\n')
+---   vim.api.nvim_buf_set_lines(0, vim.v.lnum - 1, vim.v.count, true, lines)
+--- end
+--- vim.o.formatexpr = 'v:lua.fmt_json()'
+--- ```
+---
 ---@param obj any
 ---@param opts? table<string,any> Options table with keys:
 ---                                 - escape_slash: (boolean) (default false) Escape slash