[WIP] Add vim.create_command for defining commands that callback Lua directly #11613

norcalli · 2019-12-25T17:35:13Z

Functioning example of vim.create_command(name, callback, force, options) which allows you to define an ex command which is backed by a Lua callback.

callback(arg: string, options: table) is the current signature, where arg is the argument passed to the command directly without any kind of tokenization or further parsing. The options are things like whether bang was specified or a range or whatnot.

options in the original will be things like bang or range, etc.

The only things to bikeshed are the exact design and I have to read more on the existing ucmd interface and all of the options available, because it's quite thick.

I think that passing the eap->arg as-is to the callback isn't a bad idea as compared to supporting options like <f-args> or <q-args> because the expectation should be that achieving those things from Lua should be doable and ergonomic. We already have vim.split and vim.gsplit which makes it possible to tokenize the argument as you please.

TODO:

Validate the command name as being user only
Add support for buffer local commands
Finish definitions of all other options.
Add tests
Add printing representation for the commands which display commands.

bfredl · 2019-12-25T18:15:05Z

src/nvim/ex_docmd.c

-      XFREE_CLEAR(cmd->uc_rep);
-      XFREE_CLEAR(cmd->uc_compl_arg);
+      if (cmd->uc_argt & EX_LUA_CB) {
+        lua_State* L = executor_enter_lua();


can use executor_free_luaref()

bfredl · 2019-12-25T18:18:11Z

src/nvim/ex_docmd.c

+    if (eap->forceit == 1) {
+      lua_pushliteral(L, "bang");
+      lua_pushboolean(L, eap->forceit == 1);
+      lua_rawset(L, -3);


can use lua_setfield() here (it invokes metamethods, but is safe for a freshly created table)

Why not put this logic in lua/executor.c instead of exposing executor_enter_lua ?

lua_do_ucmd(eap);

It depends on how many places I expected to need lua. With bfredl's recommendation for using executor_free_luaref(), I would only need to use executor_enter_lua() once now, which means I could replace it with a single function.

Architecturally, I don't find exposing the ability to do arbitrary Lua elsewhere to be terrible as long as it's used responsibly if it was the choice between that and a bunch of little utility functions.

In this case I think it's fine, but I'm also looking at adding Lua functions for keymappings and autocmds (I know there's an existing PR out there which I'm hoping to pick up). So I'll say for sure after spending more time with that.

But good point, nonetheless.

To me, a "bunch of functions" in lua/executor.c seems like a better tradeoff than managing Lua state all over the project. That keeps lua/executor.c encapsulated.

bfredl · 2019-12-25T18:21:40Z

src/nvim/ex_docmd.c

+      lua_pushboolean(L, eap->forceit == 1);
+      lua_rawset(L, -3);
+    }
+    lua_pcall(L, 2, 0, 0);


I think the `nlua_error" pattern can be used here:

if (lua_pcall(...)) { nlua_error(L, "E5108: Error executing lua: %.*s"); }

justinmk · 2019-12-26T05:16:43Z

src/nvim/ex_docmd.c

@@ -91,6 +91,7 @@ typedef struct ucmd {
  int uc_addr_type;             // The command's address type
  sctx_T uc_script_ctx;         // SCTX where the command was defined
  char_u      *uc_compl_arg;    // completion argument if any
+  LuaRef lua_cb;                // A lua callback


Articles are generally noise, and steal title-case from more important words (though "Lua" should be capitalized usually anyways).

Suggested change

LuaRef lua_cb; // A lua callback

LuaRef lua_cb; // Lua callback

see :help dev-doc

justinmk · 2019-12-26T05:18:23Z

src/nvim/ex_docmd.c

  }
 }

+void define_lua_command(const char *name,


use the module common prefix.

Suggested change

void define_lua_command(const char *name,

void uc_define_lua_command(const char *name,

justinmk · 2019-12-26T05:33:17Z

vim.create_command(name, callback, force, options)

Can we call it vim.new_cmd or vim.def_cmd? "We need a less-ceremonious/enterprisey name than "create", it is starting to appear in more and more places.

I think that passing the eap->arg as-is to the callback isn't a bad idea as compared to supporting options like <f-args> or <q-args> because the expectation should be that achieving those things from Lua should be doable and ergonomic.

Agreed.

We already have vim.split and vim.gsplit which makes it possible to tokenize the argument as you please.

Vimscript :command makes the plugin author choose via <f-args> et al., so we don't really have a choice.

noahfrederick · 2021-06-23T12:47:23Z

vim.create_command(name, callback, force, options)

I would advocate for defaulting force to true and allowing it to be set in options instead:

vim.create_command(name, callback, {force = true})

I don't know about others, by I've never found guarding against overwriting a command by emitting an error to be a useful feature as a user or a plugin author. So what motivates this suggestion is:

Simplifies defining a command by making the argument optional and providing a sensible default.
Usage is self-documenting, unlike a boolean argument.

rr- · 2021-07-05T15:54:35Z

This is good but will this work for Python? @justinmk

gpanders · 2021-12-23T14:02:36Z

Superseded by #16752.

WIP Groundwork for vim.create_command

93092a4

norcalli changed the title ~~WIP Groundwork for vim.create_command~~ [WIP] Add vim.create_command for defining commands that callback Lua directly Dec 25, 2019

Add optional force parameter.

10008c1

norcalli added WIP lua stdlib labels Dec 25, 2019

bfredl reviewed Dec 25, 2019

View reviewed changes

justinmk reviewed Dec 26, 2019

View reviewed changes

justinmk mentioned this pull request Jul 3, 2021

Create event subscription documentation neovim/pynvim#488

Closed

w-cantin mentioned this pull request Sep 12, 2021

How to listen to suscribed events neovim/node-client#181

Closed

gpanders mentioned this pull request Dec 22, 2021

feat(api): implement nvim_{add,del}_user_command #16752

Merged

6 tasks

gpanders closed this Dec 23, 2021

matu3ba mentioned this pull request Dec 29, 2021

lua user commands pr landed, so describe them in guide nanotee/nvim-lua-guide#87

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Add vim.create_command for defining commands that callback Lua directly #11613

[WIP] Add vim.create_command for defining commands that callback Lua directly #11613

norcalli commented Dec 25, 2019 •

edited

Loading

bfredl Dec 25, 2019

bfredl Dec 25, 2019

justinmk Dec 26, 2019 •

edited

Loading

norcalli Dec 26, 2019

justinmk Dec 29, 2019 •

edited

Loading

bfredl Dec 25, 2019

justinmk Dec 26, 2019

justinmk Dec 26, 2019

justinmk commented Dec 26, 2019

noahfrederick commented Jun 23, 2021

rr- commented Jul 5, 2021

gpanders commented Dec 23, 2021

	LuaRef lua_cb; // A lua callback
	LuaRef lua_cb; // Lua callback

	void define_lua_command(const char *name,
	void uc_define_lua_command(const char *name,

[WIP] Add vim.create_command for defining commands that callback Lua directly #11613

[WIP] Add vim.create_command for defining commands that callback Lua directly #11613

Conversation

norcalli commented Dec 25, 2019 • edited Loading

bfredl Dec 25, 2019

Choose a reason for hiding this comment

bfredl Dec 25, 2019

Choose a reason for hiding this comment

justinmk Dec 26, 2019 • edited Loading

Choose a reason for hiding this comment

norcalli Dec 26, 2019

Choose a reason for hiding this comment

justinmk Dec 29, 2019 • edited Loading

Choose a reason for hiding this comment

bfredl Dec 25, 2019

Choose a reason for hiding this comment

justinmk Dec 26, 2019

Choose a reason for hiding this comment

justinmk Dec 26, 2019

Choose a reason for hiding this comment

justinmk commented Dec 26, 2019

noahfrederick commented Jun 23, 2021

rr- commented Jul 5, 2021

gpanders commented Dec 23, 2021

norcalli commented Dec 25, 2019 •

edited

Loading

justinmk Dec 26, 2019 •

edited

Loading

justinmk Dec 29, 2019 •

edited

Loading