Merge pull request #16594 from shadmansaleh/feat/api/lua_keymaps

feat(api): add support for lua function & description in keymap

14 files changed, 242 insertions, 67 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index bacb991c4b..2d5403d4b8 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -835,7 +835,7 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
 /// @param[out]  err   Error details, if any
 /// @returns Array of maparg()-like dictionaries describing mappings.
 ///          The "buffer" key holds the associated buffer handle.
-ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
+ArrayOf(Dictionary) nvim_buf_get_keymap(uint64_t channel_id, Buffer buffer, String mode, Error *err)
   FUNC_API_SINCE(3)
 {
   buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -844,7 +844,7 @@ ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
     return (Array)ARRAY_DICT_INIT;
   }
 
-  return keymap_array(mode, buf);
+  return keymap_array(mode, buf, channel_id == LUA_INTERNAL_CALL);
 }
 
 /// Sets a buffer-local |mapping| for the given mode.
diff --git a/src/nvim/api/keysets.lua b/src/nvim/api/keysets.lua
index e47dec9eb7..97ee885ff6 100644
--- a/src/nvim/api/keysets.lua
+++ b/src/nvim/api/keysets.lua
@@ -29,6 +29,8 @@ return {
     "script";
     "expr";
     "unique";
+    "callback";
+    "desc";
   };
   get_commands = {
     "builtin";
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index 962fce6952..0c7ba1845c 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -594,6 +594,7 @@ Array string_to_array(const String input, bool crlf)
 void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs, String rhs,
                    Dict(keymap) *opts, Error *err)
 {
+  LuaRef lua_funcref = LUA_NOREF;
   bool global = (buffer == -1);
   if (global) {
     buffer = 0;
@@ -604,6 +605,9 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs, String
     return;
   }
 
+  if (opts != NULL && opts->callback.type == kObjectTypeLuaRef) {
+    lua_funcref = api_new_luaref(opts->callback.data.luaref);
+  }
   MapArguments parsed_args = MAP_ARGUMENTS_INIT;
   if (opts) {
 #define KEY_TO_BOOL(name) \
@@ -623,9 +627,13 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs, String
   parsed_args.buffer = !global;
 
   set_maparg_lhs_rhs((char_u *)lhs.data, lhs.size,
-                     (char_u *)rhs.data, rhs.size,
+                     (char_u *)rhs.data, rhs.size, lua_funcref,
                      CPO_TO_CPO_FLAGS, &parsed_args);
-
+  if (opts != NULL && opts->desc.type == kObjectTypeString) {
+    parsed_args.desc = xstrdup(opts->desc.data.string.data);
+  } else {
+    parsed_args.desc = NULL;
+  }
   if (parsed_args.lhs_len > MAXMAPLEN) {
     api_set_error(err, kErrorTypeValidation,  "LHS exceeds maximum map length: %s", lhs.data);
     goto fail_and_free;
@@ -658,7 +666,8 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs, String
   bool is_noremap = parsed_args.noremap;
   assert(!(is_unmap && is_noremap));
 
-  if (!is_unmap && (parsed_args.rhs_len == 0 && !parsed_args.rhs_is_noop)) {
+  if (!is_unmap && lua_funcref == LUA_NOREF
+      && (parsed_args.rhs_len == 0 && !parsed_args.rhs_is_noop)) {
     if (rhs.size == 0) {  // assume that the user wants RHS to be a <Nop>
       parsed_args.rhs_is_noop = true;
     } else {
@@ -668,9 +677,13 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs, String
       api_set_error(err, kErrorTypeValidation, "Parsing of nonempty RHS failed: %s", rhs.data);
       goto fail_and_free;
     }
-  } else if (is_unmap && parsed_args.rhs_len) {
-    api_set_error(err, kErrorTypeValidation,
-                  "Gave nonempty RHS in unmap command: %s", parsed_args.rhs);
+  } else if (is_unmap && (parsed_args.rhs_len || parsed_args.rhs_lua != LUA_NOREF)) {
+    if (parsed_args.rhs_len) {
+      api_set_error(err, kErrorTypeValidation,
+                    "Gave nonempty RHS in unmap command: %s", parsed_args.rhs);
+    } else {
+      api_set_error(err, kErrorTypeValidation, "Gave nonempty RHS for unmap");
+    }
     goto fail_and_free;
   }
 
@@ -700,9 +713,12 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs, String
     goto fail_and_free;
   }  // switch
 
+  parsed_args.rhs_lua = LUA_NOREF;  // don't clear ref on success
 fail_and_free:
+  NLUA_CLEAR_REF(parsed_args.rhs_lua);
   xfree(parsed_args.rhs);
   xfree(parsed_args.orig_rhs);
+  XFREE_CLEAR(parsed_args.desc);
   return;
 }
 
@@ -1052,8 +1068,9 @@ void api_set_error(Error *err, ErrorType errType, const char *format, ...)
 ///
 /// @param  mode  The abbreviation for the mode
 /// @param  buf  The buffer to get the mapping array. NULL for global
+/// @param  from_lua  Whether it is called from internal lua api.
 /// @returns Array of maparg()-like dictionaries describing mappings
-ArrayOf(Dictionary) keymap_array(String mode, buf_T *buf)
+ArrayOf(Dictionary) keymap_array(String mode, buf_T *buf, bool from_lua)
 {
   Array mappings = ARRAY_DICT_INIT;
   dict_T *const dict = tv_dict_alloc();
@@ -1073,8 +1090,19 @@ ArrayOf(Dictionary) keymap_array(String mode, buf_T *buf)
       // Check for correct mode
       if (int_mode & current_maphash->m_mode) {
         mapblock_fill_dict(dict, current_maphash, buffer_value, false);
-        ADD(mappings, vim_to_object((typval_T[]) { { .v_type = VAR_DICT, .vval.v_dict = dict } }));
-
+        Object api_dict = vim_to_object((typval_T[]) { { .v_type = VAR_DICT,
+                                                         .vval.v_dict = dict } });
+        if (from_lua) {
+          Dictionary d = api_dict.data.dictionary;
+          for (size_t j = 0; j < d.size; j++) {
+            if (strequal("callback", d.items[j].key.data)) {
+              d.items[j].value.type = kObjectTypeLuaRef;
+              d.items[j].value.data.luaref = api_new_luaref((LuaRef)d.items[j].value.data.integer);
+              break;
+            }
+          }
+        }
+        ADD(mappings, api_dict);
         tv_dict_clear(dict);
       }
     }
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index dfc606f927..693d2083e6 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1538,10 +1538,10 @@ Dictionary nvim_get_mode(void)
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
 /// @returns Array of maparg()-like dictionaries describing mappings.
 ///          The "buffer" key is always zero.
-ArrayOf(Dictionary) nvim_get_keymap(String mode)
+ArrayOf(Dictionary) nvim_get_keymap(uint64_t channel_id, String mode)
   FUNC_API_SINCE(3)
 {
-  return keymap_array(mode, NULL);
+  return keymap_array(mode, NULL, channel_id == LUA_INTERNAL_CALL);
 }
 
 /// Sets a global |mapping| for the given mode.
@@ -1566,7 +1566,10 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
 /// @param  lhs   Left-hand-side |{lhs}| of the mapping.
 /// @param  rhs   Right-hand-side |{rhs}| of the mapping.
 /// @param  opts  Optional parameters map. Accepts all |:map-arguments|
-///               as keys excluding |<buffer>| but including |noremap|.
+///               as keys excluding |<buffer>| but including |noremap| and "desc".
+///               |desc| can be used to give a description to keymap.
+///               When called from Lua, also accepts a "callback" key that takes
+///               a Lua function to call when the mapping is executed.
 ///               Values are Booleans. Unknown key is an error.
 /// @param[out]   err   Error details, if any.
 void nvim_set_keymap(String mode, String lhs, String rhs, Dict(keymap) *opts, Error *err)
diff --git a/src/nvim/buffer_defs.h b/src/nvim/buffer_defs.h
index 49e527e98b..63a550c017 100644
--- a/src/nvim/buffer_defs.h
+++ b/src/nvim/buffer_defs.h
@@ -352,6 +352,7 @@ struct mapblock {
   char_u *m_keys;          // mapped from, lhs
   char_u *m_str;           // mapped to, rhs
   char_u *m_orig_str;      // rhs as entered by the user
+  LuaRef m_luaref;         // lua function reference as rhs
   int m_keylen;                 // strlen(m_keys)
   int m_mode;                   // valid mode
   int m_noremap;                // if non-zero no re-mapping for m_str
@@ -359,6 +360,7 @@ struct mapblock {
   char m_nowait;                // <nowait> used
   char m_expr;                  // <expr> used, m_str is an expression
   sctx_T m_script_ctx;          // SCTX where map was defined
+  char *m_desc;                 // description of keymap
 };
 
 /// Used for highlighting in the status line.
diff --git a/src/nvim/edit.c b/src/nvim/edit.c
index 3517b3244e..5eef4350b7 100644
--- a/src/nvim/edit.c
+++ b/src/nvim/edit.c
@@ -1076,6 +1076,10 @@ static int insert_handle_key(InsertState *s)
 
   case K_COMMAND:       // some command
     do_cmdline(NULL, getcmdkeycmd, NULL, 0);
+    goto check_pum;
+
+  case K_LUA:
+    map_execute_lua();
 
 check_pum:
     // TODO(bfredl): Not entirely sure this indirection is necessary
diff --git a/src/nvim/eval.c b/src/nvim/eval.c
index 86384bc5b2..6dbdc09c3b 100644
--- a/src/nvim/eval.c
+++ b/src/nvim/eval.c
@@ -7299,12 +7299,19 @@ void mapblock_fill_dict(dict_T *const dict, const mapblock_T *const mp, long buf
     noremap_value = mp->m_noremap == REMAP_SCRIPT ? 2 : !!mp->m_noremap;
   }
 
-  if (compatible) {
-    tv_dict_add_str(dict, S_LEN("rhs"), (const char *)mp->m_orig_str);
+  if (mp->m_luaref != LUA_NOREF) {
+    tv_dict_add_nr(dict, S_LEN("callback"), mp->m_luaref);
   } else {
-    tv_dict_add_allocated_str(dict, S_LEN("rhs"),
-                              str2special_save((const char *)mp->m_str, false,
-                                               true));
+    if (compatible) {
+      tv_dict_add_str(dict, S_LEN("rhs"), (const char *)mp->m_orig_str);
+    } else {
+      tv_dict_add_allocated_str(dict, S_LEN("rhs"),
+                                str2special_save((const char *)mp->m_str, false,
+                                                 true));
+    }
+  }
+  if (mp->m_desc != NULL) {
+    tv_dict_add_allocated_str(dict, S_LEN("desc"), xstrdup(mp->m_desc));
   }
   tv_dict_add_allocated_str(dict, S_LEN("lhs"), lhs);
   tv_dict_add_nr(dict, S_LEN("noremap"), noremap_value);
diff --git a/src/nvim/eval/funcs.c b/src/nvim/eval/funcs.c
index 32026282cf..4cccecb23a 100644
--- a/src/nvim/eval/funcs.c
+++ b/src/nvim/eval/funcs.c
@@ -5980,6 +5980,7 @@ static void get_maparg(typval_T *argvars, typval_T *rettv, int exact)
 {
   char_u *keys_buf = NULL;
   char_u *rhs;
+  LuaRef rhs_lua;
   int mode;
   int abbr = FALSE;
   int get_dict = FALSE;
@@ -6016,7 +6017,7 @@ static void get_maparg(typval_T *argvars, typval_T *rettv, int exact)
 
   keys = replace_termcodes(keys, STRLEN(keys), &keys_buf, true, true, true,
                            CPO_TO_CPO_FLAGS);
-  rhs = check_map(keys, mode, exact, false, abbr, &mp, &buffer_local);
+  rhs = check_map(keys, mode, exact, false, abbr, &mp, &buffer_local, &rhs_lua);
   xfree(keys_buf);
 
   if (!get_dict) {
@@ -6027,10 +6028,15 @@ static void get_maparg(typval_T *argvars, typval_T *rettv, int exact)
       } else {
         rettv->vval.v_string = (char_u *)str2special_save((char *)rhs, false, false);
       }
+    } else if (rhs_lua != LUA_NOREF) {
+      size_t msglen = 100;
+      char *msg = (char *)xmalloc(msglen);
+      snprintf(msg, msglen, "<Lua function %d>", mp->m_luaref);
+      rettv->vval.v_string = (char_u *)msg;
     }
   } else {
     tv_dict_alloc_ret(rettv);
-    if (rhs != NULL) {
+    if (mp != NULL && (rhs != NULL || rhs_lua != LUA_NOREF)) {
       // Return a dictionary.
       mapblock_fill_dict(rettv->vval.v_dict, mp, buffer_local, true);
     }
diff --git a/src/nvim/ex_getln.c b/src/nvim/ex_getln.c
index 67fd5a4efc..78b8e43e65 100644
--- a/src/nvim/ex_getln.c
+++ b/src/nvim/ex_getln.c
@@ -1024,11 +1024,13 @@ static int command_line_execute(VimState *state, int key)
   CommandLineState *s = (CommandLineState *)state;
   s->c = key;
 
-  if (s->c == K_EVENT || s->c == K_COMMAND) {
+  if (s->c == K_EVENT || s->c == K_COMMAND || s->c == K_LUA) {
     if (s->c == K_EVENT) {
       state_handle_k_event();
-    } else {
+    } else if (s->c == K_COMMAND) {
       do_cmdline(NULL, getcmdkeycmd, NULL, DOCMD_NOWAIT);
+    } else {
+      map_execute_lua();
     }
 
     if (!cmdline_was_last_drawn) {
diff --git a/src/nvim/getchar.c b/src/nvim/getchar.c
index 424bf758e2..5565e17597 100644
--- a/src/nvim/getchar.c
+++ b/src/nvim/getchar.c
@@ -15,6 +15,7 @@
 #include <stdbool.h>
 #include <string.h>
 
+#include "nvim/api/private/helpers.h"
 #include "nvim/ascii.h"
 #include "nvim/assert.h"
 #include "nvim/buffer_defs.h"
@@ -1902,7 +1903,7 @@ static int handle_mapping(int *keylenp, bool *timedout, int *mapdepth)
 
   // complete match
   if (keylen >= 0 && keylen <= typebuf.tb_len) {
-    char_u *map_str;
+    char_u *map_str = NULL;
     int save_m_expr;
     int save_m_noremap;
     int save_m_silent;
@@ -1947,6 +1948,7 @@ static int handle_mapping(int *keylenp, bool *timedout, int *mapdepth)
     save_m_silent = mp->m_silent;
     char_u *save_m_keys = NULL;  // only saved when needed
     char_u *save_m_str = NULL;  // only saved when needed
+    LuaRef save_m_luaref = mp->m_luaref;
 
     // Handle ":map <expr>": evaluate the {rhs} as an
     // expression.  Also save and restore the command line
@@ -1959,8 +1961,10 @@ static int handle_mapping(int *keylenp, bool *timedout, int *mapdepth)
       may_garbage_collect = false;
 
       save_m_keys = vim_strsave(mp->m_keys);
-      save_m_str = vim_strsave(mp->m_str);
-      map_str = eval_map_expr(save_m_str, NUL);
+      if (save_m_luaref == LUA_NOREF) {
+        save_m_str = vim_strsave(mp->m_str);
+      }
+      map_str = eval_map_expr(mp, NUL);
       vgetc_busy = save_vgetc_busy;
       may_garbage_collect = save_may_garbage_collect;
     } else {
@@ -2618,11 +2622,13 @@ int fix_input_buffer(char_u *buf, int len)
 /// @param[in] orig_lhs   Original mapping LHS, with characters to replace.
 /// @param[in] orig_lhs_len   `strlen` of orig_lhs.
 /// @param[in] orig_rhs   Original mapping RHS, with characters to replace.
+/// @param[in] rhs_lua   Lua reference for Lua maps.
 /// @param[in] orig_rhs_len   `strlen` of orig_rhs.
 /// @param[in] cpo_flags  See param docs for @ref replace_termcodes.
 /// @param[out] mapargs   MapArguments struct holding the replaced strings.
-void set_maparg_lhs_rhs(const char_u *orig_lhs, const size_t orig_lhs_len, const char_u *orig_rhs,
-                        const size_t orig_rhs_len, int cpo_flags, MapArguments *mapargs)
+void set_maparg_lhs_rhs(const char_u *orig_lhs, const size_t orig_lhs_len,
+                        const char_u *orig_rhs, const size_t orig_rhs_len,
+                        LuaRef rhs_lua, int cpo_flags, MapArguments *mapargs)
 {
   char_u *lhs_buf = NULL;
   char_u *rhs_buf = NULL;
@@ -2638,22 +2644,34 @@ void set_maparg_lhs_rhs(const char_u *orig_lhs, const size_t orig_lhs_len, const
                                        true, true, true, cpo_flags);
   mapargs->lhs_len = STRLEN(replaced);
   STRLCPY(mapargs->lhs, replaced, sizeof(mapargs->lhs));
+  mapargs->rhs_lua = rhs_lua;
 
-  mapargs->orig_rhs_len = orig_rhs_len;
-  mapargs->orig_rhs = xcalloc(mapargs->orig_rhs_len + 1, sizeof(char_u));
-  STRLCPY(mapargs->orig_rhs, orig_rhs, mapargs->orig_rhs_len + 1);
+  if (rhs_lua == LUA_NOREF) {
+    mapargs->orig_rhs_len = orig_rhs_len;
+    mapargs->orig_rhs = xcalloc(mapargs->orig_rhs_len + 1, sizeof(char_u));
+    STRLCPY(mapargs->orig_rhs, orig_rhs, mapargs->orig_rhs_len + 1);
 
-  if (STRICMP(orig_rhs, "<nop>") == 0) {  // "<Nop>" means nothing
-    mapargs->rhs = xcalloc(1, sizeof(char_u));  // single null-char
-    mapargs->rhs_len = 0;
-    mapargs->rhs_is_noop = true;
+    if (STRICMP(orig_rhs, "<nop>") == 0) {  // "<Nop>" means nothing
+      mapargs->rhs = xcalloc(1, sizeof(char_u));  // single null-char
+      mapargs->rhs_len = 0;
+      mapargs->rhs_is_noop = true;
+    } else {
+      replaced = replace_termcodes(orig_rhs, orig_rhs_len, &rhs_buf,
+                                   false, true, true, cpo_flags);
+      mapargs->rhs_len = STRLEN(replaced);
+      mapargs->rhs_is_noop = false;
+      mapargs->rhs = xcalloc(mapargs->rhs_len + 1, sizeof(char_u));
+      STRLCPY(mapargs->rhs, replaced, mapargs->rhs_len + 1);
+    }
   } else {
-    replaced = replace_termcodes(orig_rhs, orig_rhs_len, &rhs_buf,
-                                 false, true, true, cpo_flags);
-    mapargs->rhs_len = STRLEN(replaced);
-    mapargs->rhs_is_noop = false;
-    mapargs->rhs = xcalloc(mapargs->rhs_len + 1, sizeof(char_u));
-    STRLCPY(mapargs->rhs, replaced, mapargs->rhs_len + 1);
+    char tmp_buf[64];
+    // stores <lua>ref_no<cr> in map_str
+    mapargs->orig_rhs_len = (size_t)vim_snprintf(S_LEN(tmp_buf), "<LUA>%d<CR>", rhs_lua);
+    mapargs->orig_rhs = vim_strsave((char_u *)tmp_buf);
+    mapargs->rhs_len = (size_t)vim_snprintf(S_LEN(tmp_buf), "%c%c%c%d\r", K_SPECIAL,
+                                            (char_u)KEY2TERMCAP0(K_LUA), KEY2TERMCAP1(K_LUA),
+                                            rhs_lua);
+    mapargs->rhs = vim_strsave((char_u *)tmp_buf);
   }
 
   xfree(lhs_buf);
@@ -2765,7 +2783,7 @@ int str_to_mapargs(const char_u *strargs, bool is_unmap, MapArguments *mapargs)
 
   size_t orig_rhs_len = STRLEN(rhs_start);
   set_maparg_lhs_rhs(lhs_to_replace, orig_lhs_len,
-                     rhs_start, orig_rhs_len,
+                     rhs_start, orig_rhs_len, LUA_NOREF,
                      CPO_TO_CPO_FLAGS, &parsed_args);
 
   xfree(lhs_to_replace);
@@ -2827,7 +2845,7 @@ int buf_do_map(int maptype, MapArguments *args, int mode, bool is_abbrev, buf_T
   validate_maphash();
 
   bool has_lhs = (args->lhs[0] != NUL);
-  bool has_rhs = (args->rhs[0] != NUL) || args->rhs_is_noop;
+  bool has_rhs = args->rhs_lua != LUA_NOREF || (args->rhs[0] != NUL) || args->rhs_is_noop;
 
   // check for :unmap without argument
   if (maptype == 1 && !has_lhs) {
@@ -3017,10 +3035,14 @@ int buf_do_map(int maptype, MapArguments *args, int mode, bool is_abbrev, buf_T
             } else {  // new rhs for existing entry
               mp->m_mode &= ~mode;  // remove mode bits
               if (mp->m_mode == 0 && !did_it) {  // reuse entry
-                xfree(mp->m_str);
+                XFREE_CLEAR(mp->m_str);
+                XFREE_CLEAR(mp->m_orig_str);
+                XFREE_CLEAR(mp->m_desc);
+                NLUA_CLEAR_REF(mp->m_luaref);
+
                 mp->m_str = vim_strsave(rhs);
-                xfree(mp->m_orig_str);
                 mp->m_orig_str = vim_strsave(orig_rhs);
+                mp->m_luaref = args->rhs_lua;
                 mp->m_noremap = noremap;
                 mp->m_nowait = args->nowait;
                 mp->m_silent = args->silent;
@@ -3028,6 +3050,9 @@ int buf_do_map(int maptype, MapArguments *args, int mode, bool is_abbrev, buf_T
                 mp->m_expr = args->expr;
                 mp->m_script_ctx = current_sctx;
                 mp->m_script_ctx.sc_lnum += sourcing_lnum;
+                if (args->desc != NULL) {
+                  mp->m_desc = xstrdup(args->desc);
+                }
                 did_it = true;
               }
             }
@@ -3096,6 +3121,7 @@ int buf_do_map(int maptype, MapArguments *args, int mode, bool is_abbrev, buf_T
   mp->m_keys = vim_strsave(lhs);
   mp->m_str = vim_strsave(rhs);
   mp->m_orig_str = vim_strsave(orig_rhs);
+  mp->m_luaref = args->rhs_lua;
   mp->m_keylen = (int)STRLEN(mp->m_keys);
   mp->m_noremap = noremap;
   mp->m_nowait = args->nowait;
@@ -3104,6 +3130,10 @@ int buf_do_map(int maptype, MapArguments *args, int mode, bool is_abbrev, buf_T
   mp->m_expr = args->expr;
   mp->m_script_ctx = current_sctx;
   mp->m_script_ctx.sc_lnum += sourcing_lnum;
+  mp->m_desc = NULL;
+  if (args->desc != NULL) {
+    mp->m_desc = xstrdup(args->desc);
+  }
 
   // add the new entry in front of the abbrlist or maphash[] list
   if (is_abbrev) {
@@ -3200,8 +3230,10 @@ static void mapblock_free(mapblock_T **mpp)
 
   mp = *mpp;
   xfree(mp->m_keys);
-  xfree(mp->m_str);
-  xfree(mp->m_orig_str);
+  NLUA_CLEAR_REF(mp->m_luaref);
+  XFREE_CLEAR(mp->m_str);
+  XFREE_CLEAR(mp->m_orig_str);
+  XFREE_CLEAR(mp->m_desc);
   *mpp = mp->m_next;
   xfree(mp);
 }
@@ -3392,7 +3424,8 @@ static void showmap(mapblock_T *mp, bool local)
 {
   size_t len = 1;
 
-  if (message_filtered(mp->m_keys) && message_filtered(mp->m_str)) {
+  if (message_filtered(mp->m_keys)
+      && mp->m_str != NULL && message_filtered(mp->m_str)) {
     return;
   }
 
@@ -3437,7 +3470,11 @@ static void showmap(mapblock_T *mp, bool local)
 
   /* Use FALSE below if we only want things like <Up> to show up as such on
    * the rhs, and not M-x etc, TRUE gets both -- webb */
-  if (*mp->m_str == NUL) {
+  if (mp->m_luaref != LUA_NOREF) {
+    char msg[100];
+    snprintf(msg, sizeof(msg), "<Lua function %d>", mp->m_luaref);
+    msg_puts_attr(msg, HL_ATTR(HLF_8));
+  } else if (mp->m_str == NULL) {
     msg_puts_attr("<Nop>", HL_ATTR(HLF_8));
   } else {
     // Remove escaping of CSI, because "m_str" is in a format to be used
@@ -3447,6 +3484,11 @@ static void showmap(mapblock_T *mp, bool local)
     msg_outtrans_special(s, false, 0);
     xfree(s);
   }
+
+  if (mp->m_desc != NULL) {
+    msg_puts("\n                 ");  // Shift line to same level as rhs.
+    msg_puts(mp->m_desc);
+  }
   if (p_verbose > 0) {
     last_set_msg(mp->m_script_ctx);
   }
@@ -3533,7 +3575,7 @@ int map_to_exists_mode(const char *const rhs, const int mode, const bool abbr)
       }
       for (; mp; mp = mp->m_next) {
         if ((mp->m_mode & mode)
-            && strstr((char *)mp->m_str, rhs) != NULL) {
+            && mp->m_str != NULL && strstr((char *)mp->m_str, rhs) != NULL) {
           return true;
         }
       }
@@ -3879,7 +3921,7 @@ bool check_abbr(int c, char_u *ptr, int col, int mincol)
         (void)ins_typebuf(tb, 1, 0, true, mp->m_silent);
       }
       if (mp->m_expr) {
-        s = eval_map_expr(mp->m_str, c);
+        s = eval_map_expr(mp, c);
       } else {
         s = mp->m_str;
       }
@@ -3909,11 +3951,11 @@ bool check_abbr(int c, char_u *ptr, int col, int mincol)
 /// special characters.
 ///
 /// @param c  NUL or typed character for abbreviation
-static char_u *eval_map_expr(char_u *str, int c)
+static char_u *eval_map_expr(mapblock_T  *mp, int c)
 {
   char_u *res;
-  char_u *p;
-  char_u *expr;
+  char_u *p = NULL;
+  char_u *expr = NULL;
   char_u *save_cmd;
   pos_T save_cursor;
   int save_msg_col;
@@ -3921,8 +3963,10 @@ static char_u *eval_map_expr(char_u *str, int c)
 
   /* Remove escaping of CSI, because "str" is in a format to be used as
    * typeahead. */
-  expr = vim_strsave(str);
-  vim_unescape_csi(expr);
+  if (mp->m_luaref == LUA_NOREF) {
+    expr = vim_strsave(mp->m_str);
+    vim_unescape_csi(expr);
+  }
 
   save_cmd = save_cmdline_alloc();
 
@@ -3934,7 +3978,22 @@ static char_u *eval_map_expr(char_u *str, int c)
   save_cursor = curwin->w_cursor;
   save_msg_col = msg_col;
   save_msg_row = msg_row;
-  p = eval_to_string(expr, NULL, false);
+  if (mp->m_luaref != LUA_NOREF) {
+    Error err = ERROR_INIT;
+    Array args = ARRAY_DICT_INIT;
+    Object ret = nlua_call_ref(mp->m_luaref, NULL, args, true, &err);
+    if (ret.type == kObjectTypeString) {
+      p = (char_u *)xstrndup(ret.data.string.data, ret.data.string.size);
+    }
+    api_free_object(ret);
+    if (err.type != kErrorTypeNone) {
+      semsg_multiline("E5108: %s", err.msg);
+      api_clear_error(&err);
+    }
+  } else {
+    p = eval_to_string(expr, NULL, false);
+    xfree(expr);
+  }
   textlock--;
   ex_normal_lock--;
   curwin->w_cursor = save_cursor;
@@ -3942,7 +4001,6 @@ static char_u *eval_map_expr(char_u *str, int c)
   msg_row = save_msg_row;
 
   restore_cmdline_alloc(save_cmd);
-  xfree(expr);
 
   if (p == NULL) {
     return NULL;
@@ -4049,8 +4107,11 @@ int makemap(FILE *fd, buf_T *buf)
           continue;
         }
 
-        // skip mappings that contain a <SNR> (script-local thing),
+        // skip lua mappings and mappings that contain a <SNR> (script-local thing),
         // they probably don't work when loaded again
+        if (mp->m_luaref != LUA_NOREF) {
+          continue;
+        }
         for (p = mp->m_str; *p != NUL; p++) {
           if (p[0] == K_SPECIAL && p[1] == KS_EXTRA
               && p[2] == (int)KE_SNR) {
@@ -4331,10 +4392,11 @@ int put_escstr(FILE *fd, char_u *strstart, int what)
 /// @param mp_ptr  return: pointer to mapblock or NULL
 /// @param local_ptr  return: buffer-local mapping or NULL
 char_u *check_map(char_u *keys, int mode, int exact, int ign_mod, int abbr, mapblock_T **mp_ptr,
-                  int *local_ptr)
+                  int *local_ptr, int *rhs_lua)
 {
   int len, minlen;
   mapblock_T *mp;
+  *rhs_lua = LUA_NOREF;
 
   validate_maphash();
 
@@ -4375,7 +4437,8 @@ char_u *check_map(char_u *keys, int mode, int exact, int ign_mod, int abbr, mapb
             if (local_ptr != NULL) {
               *local_ptr = local;
             }
-            return mp->m_str;
+            *rhs_lua = mp->m_luaref;
+            return mp->m_luaref == LUA_NOREF ? mp->m_str : NULL;
           }
         }
       }
@@ -4560,3 +4623,47 @@ char_u *getcmdkeycmd(int promptc, void *cookie, int indent, bool do_concat)
 
   return (char_u *)line_ga.ga_data;
 }
+
+bool map_execute_lua(void)
+{
+  garray_T line_ga;
+  int c1 = -1;
+  bool aborted = false;
+
+  ga_init(&line_ga, 1, 32);
+
+  no_mapping++;
+
+  got_int = false;
+  while (c1 != NUL && !aborted) {
+    ga_grow(&line_ga, 32);
+    // Get one character at a time.
+    c1 = vgetorpeek(true);
+    if (got_int) {
+      aborted = true;
+    } else if (c1 == '\r' || c1 == '\n') {
+      c1 = NUL;  // end the line
+    } else {
+      ga_append(&line_ga, (char)c1);
+    }
+  }
+
+  no_mapping--;
+
+  if (aborted) {
+    ga_clear(&line_ga);
+    return false;
+  }
+
+  LuaRef ref = (LuaRef)atoi(line_ga.ga_data);
+  Error err = ERROR_INIT;
+  Array args = ARRAY_DICT_INIT;
+  nlua_call_ref(ref, NULL, args, false, &err);
+  if (err.type != kErrorTypeNone) {
+    semsg_multiline("E5108: %s", err.msg);
+    api_clear_error(&err);
+  }
+
+  ga_clear(&line_ga);
+  return true;
+}
diff --git a/src/nvim/getchar.h b/src/nvim/getchar.h
index 5950611d3f..be10e150e5 100644
--- a/src/nvim/getchar.h
+++ b/src/nvim/getchar.h
@@ -50,14 +50,16 @@ struct map_arguments {
 
   char_u *rhs;  /// The {rhs} of the mapping.
   size_t rhs_len;
+  LuaRef rhs_lua;  /// lua function as rhs
   bool rhs_is_noop;  /// True when the {orig_rhs} is <nop>.
 
   char_u *orig_rhs;  /// The original text of the {rhs}.
   size_t orig_rhs_len;
+  char *desc;  /// map escription
 };
 typedef struct map_arguments MapArguments;
 #define MAP_ARGUMENTS_INIT { false, false, false, false, false, false, false, \
-                             { 0 }, 0, NULL, 0, false, NULL, 0 }
+                             { 0 }, 0, NULL, 0, LUA_NOREF, false, NULL, 0, NULL }
 
 #define KEYLEN_PART_KEY -1  // keylen value for incomplete key-code
 #define KEYLEN_PART_MAP -2  // keylen value for incomplete mapping
diff --git a/src/nvim/keymap.h b/src/nvim/keymap.h
index 5ff5a38614..5a74d1dc00 100644
--- a/src/nvim/keymap.h
+++ b/src/nvim/keymap.h
@@ -245,6 +245,7 @@ enum key_extra {
   KE_MOUSEMOVE = 100,        // mouse moved with no button down
   // , KE_CANCEL = 101        // return from vgetc
   KE_EVENT = 102,           // event
+  KE_LUA = 103,  // lua special key
   KE_COMMAND = 104,  // <Cmd> special key
 };
 
@@ -443,6 +444,7 @@ enum key_extra {
 
 #define K_EVENT         TERMCAP2KEY(KS_EXTRA, KE_EVENT)
 #define K_COMMAND       TERMCAP2KEY(KS_EXTRA, KE_COMMAND)
+#define K_LUA           TERMCAP2KEY(KS_EXTRA, KE_LUA)
 
 // Bits for modifier mask
 // 0x01 cannot be used, because the modifier must be 0x02 or higher
diff --git a/src/nvim/normal.c b/src/nvim/normal.c
index 3246596f16..60bf393085 100644
--- a/src/nvim/normal.c
+++ b/src/nvim/normal.c
@@ -334,6 +334,7 @@ static const struct nv_cmd {
   { K_SELECT,  nv_select,      0,                      0 },
   { K_EVENT,   nv_event,       NV_KEEPREG,             0 },
   { K_COMMAND, nv_colon,       0,                      0 },
+  { K_LUA, nv_colon,           0,                      0 },
 };
 
 // Number of commands in nv_cmds[].
@@ -4043,21 +4044,22 @@ static void nv_regreplay(cmdarg_T *cap)
   }
 }
 
-/// Handle a ":" command and <Cmd>.
+/// Handle a ":" command and <Cmd> or Lua keymaps.
 static void nv_colon(cmdarg_T *cap)
 {
   int old_p_im;
   bool cmd_result;
   bool is_cmdkey = cap->cmdchar == K_COMMAND;
+  bool is_lua = cap->cmdchar == K_LUA;
 
-  if (VIsual_active && !is_cmdkey) {
+  if (VIsual_active && !is_cmdkey && !is_lua) {
     nv_operator(cap);
   } else {
     if (cap->oap->op_type != OP_NOP) {
       // Using ":" as a movement is charwise exclusive.
       cap->oap->motion_type = kMTCharWise;
       cap->oap->inclusive = false;
-    } else if (cap->count0 && !is_cmdkey) {
+    } else if (cap->count0 && !is_cmdkey && !is_lua) {
       // translate "count:" into ":.,.+(count - 1)"
       stuffcharReadbuff('.');
       if (cap->count0 > 1) {
@@ -4073,9 +4075,13 @@ static void nv_colon(cmdarg_T *cap)
 
     old_p_im = p_im;
 
+    if (is_lua) {
+      cmd_result = map_execute_lua();
+    } else {
     // get a command line and execute it
-    cmd_result = do_cmdline(NULL, is_cmdkey ? getcmdkeycmd : getexline, NULL,
-                            cap->oap->op_type != OP_NOP ? DOCMD_KEEPLINE : 0);
+      cmd_result = do_cmdline(NULL, is_cmdkey ? getcmdkeycmd : getexline, NULL,
+                              cap->oap->op_type != OP_NOP ? DOCMD_KEEPLINE : 0);
+    }
 
     // If 'insertmode' changed, enter or exit Insert mode
     if (p_im != old_p_im) {
diff --git a/src/nvim/terminal.c b/src/nvim/terminal.c
index a7b52d8238..70a5c7aa08 100644
--- a/src/nvim/terminal.c
+++ b/src/nvim/terminal.c
@@ -528,6 +528,10 @@ static int terminal_execute(VimState *state, int key)
     do_cmdline(NULL, getcmdkeycmd, NULL, 0);
     break;
 
+  case K_LUA:
+    map_execute_lua();
+    break;
+
   case Ctrl_N:
     if (s->got_bsl) {
       return 0;