feat(ui): add vim.ui.input and use in lsp rename

[seblj]

After vim.ui.select got merged, I got an idea that I wanted to do something similar to input(). This is because I want to customize how the input is used in for example renaming with lsp, without overriding the entire rename function. This proposes a solution to this with a function vim.ui.input, which I also changed to be used inside rename for lsp.

[tjdevries]

LGTM, but would like a few other people to take a look please

[muniter]

Test failing related to test/functional/plugin/lsp_spec.lua

To run the test locally:

TEST_FILE=test/functional/plugin/lsp_spec.lua make functionaltest

More info:

• https://github.com/neovim/neovim/blob/master/test/README.md
• https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md

[seblj]

@muniter I thiiiink I fixed it now

[mjlbach]

I'm in favor of separating overriding the logic (handlers) and the UX (vim.ui.X) as a general paradigm, but tagging Justin as he has some good commentary on vim.ui.select, and this is an API level decision.

[justinmk]

This is because I want to customize how the input is used in for example renaming with lsp, without overriding the entire rename function.

This is the only motivation for this that I can see. Because otherwise, the PR adds more code but gains nothing.

Is the idea that on_confirm would potentially be asynchronous?

We should not rush to add vim.ui.* things just because vim.lsp doesn't have a way to override things...

I cannot emphasize this enough: If you add an API, explain the following

1. What precedents did you draw from? How does your solution compare to them?
2. Does your new API allow future expansion? How? Or why not?
3. Is the new API similar to existing APIs? Do we need to deprecate the old ones?
4. Did you cross-reference related concepts in your API docs?

[justinmk]

so vim.fn.input can already be overridden.

Then what is the point of vim.ui.input ?

[zeertzjq]

Is vim.fn.{func} being overridable a documented behavior? The documentation of vim.fn says:

vim.fn.{func}({...})					*vim.fn*
        Invokes |vim-function| or |user-function| {func} with arguments {...}.

if vim.fn.{func} is overridden, it no longer invokes the Vim function, which goes against the documentation.

[justinmk]

But that is not fundamentally different than vim.ui.* . It's all just Lua functions.

If our story for having pluggable/extensible UI widgets is to override Lua functions... then we don't need vim.ui.* just for that.

If vim.ui.* is to exist it needs to solve real problems. Not tiny or vague problems.

[seblj]

Is the idea that on_confirm would potentially be asynchronous?

No I don't think so. I used it in lsp rename, and I don't know how an async request for that would potentially be. I would maybe have the same concerns as there is for formatting asynchronous on save. What if the user manage to save before the response from renaming comes back? I am no expert here, so this is just my initial concern.

1. What precedents did you draw from? How does your solution compare to them?

So I based my solution to this on @mfussenegger and vim.ui.select. I think this fits with the style of vim.ui.select of being a wrapper around both ui-functions.

2. Does your new API allow future expansion? How? Or why not?

I don't really know what should be further expanded with vim.ui.input? To me, it looks like it supports everything input supports, while also being easily overridable.

3. Is the new API similar to existing APIs? Do we need to deprecate the old ones?
4. Did you cross-reference related concepts in your API docs?

Not to my knowledge. It is more of a wrapper around input(), but with the expansion on taking a callback. I also searched the API docs and couldn't find anything similar.

so vim.fn.input can already be overridden.

Then what is the point of vim.ui.input ?

So the point of vim.ui.input is that it's not possible to override input to create a popup and return the input from the user from that popup (at least I don't know how this would work, so I could maybe be wrong). So therefore, vim.ui.input takes a callback which can be called when the user has confirmed the input in the popup.

[shadmansaleh]

@justinmk in my opinion what vim.ui.* does instead of vim.fn.* is it signals plugins authors to use use that common interface instead of baking their own . For example vim.fn.* is recognised as an interface to vimL function . vimL input() prompts user for input . If I'm writting a plugin I don't expect vim.fn.input to be different then input function in vimL at all even if it's overridable from lua . So if I just want to avoid viml ( many currently do though I'm not yet sure why :P) or just want to provide a facier input then what inpit function does I'm going to implement a ui myself instead of using vim.fn.input . That means any override vim.fn.input won't be applicable to that plugin . With vim.ui.input exsisting however I'll stick to vim.ui.input and let users decide what kind of ui they want . This allows separate plugins to rise that customize the ui over vim.ui like how nvim-notify provides ui over vim.notify

So basically having official vim.ui.* functions unifies the ui by encouraging plugins not to create ui elements themselves.

[justinmk]

@justinmk in my opinion what vim.ui.* does instead of vim.fn.* is it signals plugins authors to use use that common interface instead of baking their own

That can be done in 1 line:

vim.ui.input = vim.fn.input

but this PR adds 100 lines of code, yet amounts to mostly just an alias.

Is the idea that on_confirm would potentially be asynchronous?

No I don't think so. I used it in lsp rename, and I don't know how an async request for that would potentially be.

Then why is the interface a callback instead of just returning a value?

1. What precedents did you draw from? How does your solution compare to them?

So I based my solution to this on @mfussenegger and vim.ui.select. I think this fits with the style of vim.ui.select of being a wrapper around both ui-functions.

That's not a precedent, that is just a function in the same module. Precedents are from other platforms (vscode, .NET, HTML, whatever), as well as old/legacy Vim concepts.

[seblj]

Then why is the interface a callback instead of just returning a value?

It's not returning a value because I won't be able to override it how I would like then.
I would like to be able to override to create a popup like this for input.

Then I would create a buffer mapping on <CR> to execute the callback function with the text inputted in the popup. If vim.ui.input returns a value, I don't know if it would be possible to capture the text from the popup and return that.

[MunifTanjim]

Will there be a way of doing something as input value changes? e.g. highlight some text on a buffer as input value changes, or filter a list based on the input value as it changes and display it.

[seblj]

I don't think I quite understand. Could you provide an example of what you want to do?

Btw, I see that I wrote Called once the user enters the input, and see now that it can be misleading. Will change this to Called once the user confirms the input

[MunifTanjim]

Could you provide an example of what you want to do?

Take this for an example, say you want to build this UI using vim.ui.input

Here whenever the input value changes, the UI is updated. on_confirm won't help here. You'll need on_change or something.

So my question was, do you think this is something that vim.ui.input should support?

[zeertzjq]

I think this isn't possible when using the vim.fn.input().

[seblj]

Yeah as @zeertzjq is saying, this is not possible with vim.fn.input. I would be open to hear others opinion, but I don't know if I think this is something vim.ui.input should do. Personally I am leaning towards no for now.

[MunifTanjim]

this is not possible with vim.fn.input

I know. But since the idea of vim.ui.* is that others can override these for fancier implementation, is input(opts, on_confirm) the best signature? If somebody wants to implement on_change they'll either have to put on_change inside opts or add another parameter after on_confirm.

Did you think about keeping on_confirm inside opts?

Also, a minor nit-pick - if you decide to put on_confirm inside opts, I think on_submit would be a better name.

[seblj]

I do see your point, and input could also be the name of something that could filter out while typing. This however, is supposed to be a ui wrapper around vimscripts input, and therefore I don't think it makes sense to include it here. I do however want to hear others opinion on this as well, especially since this is my first PR to neovim.

For the including of on_confirm I also don't think it makes sense to include it in opts, since the opts is supposed to be the same as in input. It would also go agains the signature from vim.ui.select. I am however open to changing the name to on_submit if people are in favor of that

[tjdevries]

Here whenever the input value changes, the UI is updated. on_confirm won't help here. You'll need on_change or something.

So my question was, do you think this is something that vim.ui.input should support?

You do not need on_change. That is completely up to whoever implements vim.ui.input. Telescope would not need to have some extra hooks. It must just fulfill the responsibility of calling the callback when the prompt is entered.

[tjdevries]

I'll respond to a few of @justinmk comments.

Is the idea that on_confirm would potentially be asynchronous?

It's not actually that on_confirm needs to be asynchronous, but that the user may want to execute arbitrary code while the user is typing a response (and potentially before accepting and after completiong). When you call vim.fn.input() it must return a value, instead of calling a callback with the value. Since it must return a value, the control flow of the program cannot be changed

local x = vim.fn.input('please type something: ')
-- it'd be cool if I could run code showing a preview, doing other things, etc, but the lua state is here.
print(x)

As opposed to:

vim.ui.input('please type something', function(result) print(x) end)
-- vim.ui.input could be something that displays new text when typing into a buffer, showing hints, etc.

They are not equivalent in their usage for plugin authors. This would allow someone to use telescope to provide hints / previews / etc. while typing.

In response to the other question:

What precedents did you draw from? How does your solution compare to them?

The idea when I talked w/ @seblj about this was to stick closely to the ideas of vim.fn.input() so that we don't create unnecessary cognitive load between different input() style methods. The original viml function returns a value, while vim.ui.input calls a callback (which appeared to be the style we are going for in vim.ui, and which I prefer, since this allows for much greater flexibility).

Does your new API allow future expansion? How? Or why not?

I think so. It also allows for GUIs to implement a "prompt" style input dialog, which could even be a separate OS window, etc.

Is the new API similar to existing APIs? Do we need to deprecate the old ones?

Similar to vim.fn.input but I see no reason to deprecate vim.fn.input

Did you cross-reference related concepts in your API docs?

I'm not sure what you mean by this one.

---

As a side note, I think prompting the user for some text is a core enough workflow that it is worth (at least considering) to be added to vim.ui. Just like selection is very common, I think asking the user for some text is also very common. I am open to this not being the right way to do it thought 😄

[justinmk]

@tjdevries Thanks that makes sense.

I think this could be just a mode of vim.ui.select(). vscode has both "input" and "quickpick" (menu/select). I don't see any API differences that require multiple functions. But maybe the behavior is too different.

a

[seblj]

I think this could be just a mode of vim.ui.select().

I don't think I understand what you mean by that. I think the two functions are too different to be the same. I also don't know about the naming of the function then. I would maybe think vim.ui.select() would be somewhat confusing to be used as both a ui for selecting between items, and also taking an input text from a user

[zeertzjq]

I think this could be just a mode of vim.ui.select().

I don't think I understand what you mean by that. I think the two functions are too different to be the same. I also don't know about the naming of the function then. I would maybe think vim.ui.select() would be somewhat confusing to be used as both a ui for selecting between items, and also taking an input text from a user

And it may make overriding harder.

Wanted to comment instead of approving

[nghialm269]

Should we also add opts.kind like we did in vim.ui.select (#15838)? I would like the input to show at the cursor location for rename, but behave like vim.fn.input in other cases.

(tbh I don't like the idea of opts.kind at all, but I also cannot think of anything better)

[seblj]

I can see this being useful so I'll add this. If not anyone is disagreeing and thinking we shouldn't do it?

[seblj]

I added kind rename and modified docs to say that it can be specified. Please let me know if I should remove or keep it. I think it can be useful if people only want to override for certain input situations

[tjdevries]

I'd say let's hold off on kind for now -- we do not need to expose more than absolutely necessary for now.

Otherwise I think it looks good (I like nil for aborted input)

[seblj]

I'd say let's hold off on kind for now -- we do not need to expose more than absolutely necessary for now.

Okay, I'll remove it then!

EDIT: I just reset one commit back to remove the kind option