fix(vim.mpack): rename pack/unpack => encode/decode #16175

Problem:
1. "unpack" has an unrelated meaning in Lua:
   https://www.lua.org/manual/5.1/manual.html#pdf-unpack
2. We already have msgpackparse()/msgpackdump() and
   json_encode()/json_decode(), so introducing another name for the same
   thing is entropy.

Solution:
- Rename vim.mpack.pack/unpack => vim.mpack.encode/decode

Caveat:
This is incongruent with the `Unpacker` and `Packer` functions.
- It's probably too invasive to rename those.
- They also aren't part of our documented interface.
- This commit is "reversible" in the sense that we can always revert
  it and add `vim.mpack.encode/decode` as _aliases_ to
  `vim.mpack.pack/unpack`, at any time in the future, if we want
  stricter fidelity with upstream libmpack. Meanwhile,
  `vim.mpack.encode/decode` is currently the total _documented_
  interface of `vim.mpack`, so this change serves the purpose of
  consistent naming in the Nvim stdlib.

runtime/doc/lua.txt

@@ -698,15 +698,14 @@ vim.diff({a}, {b}, {opts})                                        *vim.diff()*
 ------------------------------------------------------------------------------
 VIM.MPACK                                                          *lua-mpack*
 
-The *vim.mpack* module provides packing and unpacking of lua objects to
+The *vim.mpack* module provides encoding and decoding of Lua objects to and
-msgpack encoded strings. |vim.NIL| and |vim.empty_dict()| are supported.
+from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|.
 
-vim.mpack.pack({obj})                                   *vim.mpack.pack*
+vim.mpack.encode({obj})                                 *vim.mpack.encode*
-        Packs a lua object {obj} and returns the msgpack representation as
+        Encodes (or "packs") Lua object {obj} as msgpack in a Lua string.
-        a string
 
-vim.mpack.unpack({str})                                 *vim.mpack.unpack*
+vim.mpack.decode({str})                                 *vim.mpack.decode*
-        Unpacks the msgpack encoded {str} and returns a lua object
+        Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object.
 
 ------------------------------------------------------------------------------
 VIM                                                     *lua-builtin*

src/mpack/lmpack.c

@@ -34,7 +34,9 @@
 #include "rpc.h"
 
 #define UNPACKER_META_NAME "mpack.Unpacker"
+#define UNPACK_FN_NAME "decode"
 #define PACKER_META_NAME "mpack.Packer"
+#define PACK_FN_NAME "encode"
 #define SESSION_META_NAME "mpack.Session"
 #define NIL_NAME "mpack.NIL"
 #define EMPTY_DICT_NAME "mpack.empty_dict"
@@ -432,8 +434,8 @@ static int lmpack_unpacker_unpack_str(lua_State *L, Unpacker *unpacker,
 
   if (unpacker->unpacking) {
     return luaL_error(L, "Unpacker instance already working. Use another "
-                         "Unpacker or the module's \"unpack\" function if you "
+                         "Unpacker or mpack." UNPACK_FN_NAME "() if you "
-                         "need to unpack from the ext handler");
+                         "need to " UNPACK_FN_NAME " from the ext handler");
   }
   
   do {
@@ -784,8 +786,8 @@ static int lmpack_packer_pack(lua_State *L)
 
   if (packer->packing) {
     return luaL_error(L, "Packer instance already working. Use another Packer "
-                         "or the module's \"pack\" function if you need to "
+                         "or mpack." PACK_FN_NAME "() if you need to "
-                         "pack from the ext handler");
+                         PACK_FN_NAME " from the ext handler");
   }
 
   do {
@@ -1161,8 +1163,8 @@ static const luaL_reg mpack_functions[] = {
   {"Unpacker", lmpack_unpacker_new},
   {"Packer", lmpack_packer_new},
   {"Session", lmpack_session_new},
-  {"unpack", lmpack_unpack},
+  {UNPACK_FN_NAME, lmpack_unpack},
-  {"pack", lmpack_pack},
+  {PACK_FN_NAME, lmpack_pack},
   {NULL, NULL}
 };
 

test/functional/lua/mpack_spec.lua

@@ -7,16 +7,16 @@ local exec_lua = helpers.exec_lua
 
 describe('lua vim.mpack', function()
   before_each(clear)
-  it('can pack vim.NIL', function()
+  it('encodes vim.NIL', function()
     eq({true, true, true, true}, exec_lua [[
-      local var = vim.mpack.unpack(vim.mpack.pack({33, vim.NIL, 77}))
+      local var = vim.mpack.decode(vim.mpack.encode({33, vim.NIL, 77}))
       return {var[1]==33, var[2]==vim.NIL, var[3]==77, var[4]==nil}
     ]])
   end)
 
-  it('can pack vim.empty_dict()', function()
+  it('encodes vim.empty_dict()', function()
     eq({{{}, "foo", {}}, true, false}, exec_lua [[
-      local var = vim.mpack.unpack(vim.mpack.pack({{}, "foo", vim.empty_dict()}))
+      local var = vim.mpack.decode(vim.mpack.encode({{}, "foo", vim.empty_dict()}))
       return {var, vim.tbl_islist(var[1]), vim.tbl_islist(var[3])}
     ]])
   end)