[vim/vim] Vim9: provide a mechanism to create aliases to builtin functions (#7658)

[lacygoill]

Is your feature request about something that is currently impossible or hard to do? Please describe the problem.

It is difficult to get used to some builtin function names, because of their inconsistency.

For example, many function related to Vim windows start with the prefix win or win_; type :h win*( on the command-line then press <C-D>, and you'll get this list:

winnr()           winwidth()        winlayout()       winrestcmd()      gettabwinvar()    getcmdwintype()

wincol()          win_getid()       win_gotoid()      win_execute()     settabwinvar()    windowsversion()

winline()         getwinpos()       win_id2win()      win_findbuf()     tabpagewinnr()

bufwinid()        getwinvar()       getwininfo()      win_gettype()     win_id2tabwin()

bufwinnr()        setwinvar()       getwinposx()      winrestview()     win_screenpos()

winbufnr()        winheight()       getwinposy()      winsaveview()     win_splitmove()

Notice that some of them don't start with win:

• getcmdwintype()
• gettabwinvar()
• getwininfo()
• getwinpos()
• getwinposx()
• getwinposy()
• getwinvar()
• setwinvar()

I left out bufwinid() and bufwinnr() because those make sense.

I also left out tabpagewinnr() and settabwinvar() because I'm not sure whether it would make sense to rename them; and if it is, I'm not sure how to rename them. For the same reasons, I left out function names which start with win without an underscore afterward.

Anyway, it might be useful to rename the previous list of functions like this:

• win_getcmdtype()
• win_gettabvar()
• win_getinfo()
• win_getpos()
• win_getposx()
• win_getposy()
• win_getvar()
• win_setvar()

Describe the solution you'd like

A new Ex command – as a temporary suggestion :defalias – which would work in a similar way as in emacs.

We could use it like this:

:defalias getwininfo win_getinfo

From now on, whenever we write win_getinfo(), Vim knows that it should – in fact – call getwininfo().

Describe alternatives you've considered

Write a wrapper function around getwininfo(), name it Win_getinfo(), make it exportable in a script, and import it whenever I need to call getwininfo().

This presents a few drawbacks though. First, I would need to import the function in every script where I need to call it; it doesn't seem to scale well when a script needs to invoke dozens of builtin functions whose names are inconsistent; and it would create a lot of noise. I mean look at this:

import {Win_getcmdtype, Win_gettabvar, Win_getinfo, Win_getpos, Win_getposx, Win_getposy, Win_getvar, Win_setvar}

Or this:

import Win_getcmdtype

import Win_gettabvar

import Win_getinfo

import Win_getpos

import Win_getposx

import Win_getposy

import Win_getvar

import Win_setvar

And this is for only 8 functions. Imagine the same imports for several dozens of functions with inconsistent names.

Second, the wrapper functions need to be capitalized, which is not exactly the desired result. It would be nice if the "fix" was transparent. That is, the new function names should look exactly like builtin function names.
Although, that might be fixed by this todo item:

https://github.com/vim/vim/blob/16a6f91ccb42ebde639a4185322b07719d345e86/runtime/doc/todo.txt#L78-L80

Third, I'm not sure it would always work as expected. What if the function needs to refer to a script-local or function-local variable? Since – in the end – the builtin function runs in a different context/script, it might not be able to always work properly, unless we pass the problematic variable as an argument, which changes the syntax of the alias function, and makes the "fix" less transparent.

Additional context

The fact that the most important property has not always been put first in a function name is a known issue, which causes some related functions to be scattered. See this comment for example:

In the past we have not put the most important property first, which
causes related methods to be scattered. So getmatches() sorts far
away from other match functions. matchesget() might have been better,
although it doesn't sounds so good.

Maybe aliases could address this issue.

---

One could argue that it would create an inconsistent ecosystem: everyone would rename their functions however they want, and reading code would be more difficult.

Still, I thought it was worth suggesting the idea. Maybe the community would come up with some sensible aliases, which would then be merged in the Vim repository as an optional package. Something similar to vim-sensible which tries to provide good default option settings.

I guess it would make the code slower, because every time a function name is not found, Vim would need to look up whether it's an alias. But that should not be too much of an issue in Vim9 script, right? I mean, in Vim9 script the code is compiled, so the cost of looking up whether an unknown function name is an error or an alias would only be paid once, at compile time.

---

If it is implemented, it would be nice for the documentation to keep working. That is, pressing K on win_getinfo() in a Vim9 script should still bring up the help topic :h getwininfo(), and not raise an error.

---

I also wanted to suggest something for the arguments of a function which – over time – can make the syntax of a function look weird and too difficult to remember (e.g. setqflist()), but:

• it would make the current report too confusing
• I'm not sure the current enhancement is technically possible
• I'm not sure the current enhancement receives enough interest

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or unsubscribe.

[lacygoill]

If aliases is a too powerful mechanism which could have a too broad impact, maybe we could at least consider the possibility of providing builtin aliases to some functions.

For example, buffer_exists() is still valid but it's documented as obsolete. The help says we should prefer bufexists(). Maybe we could do the same for functions like getwininfo(), and recommend using win_getinfo().

Before:

getwininfo([{winid}])					*getwininfo()*
...

After:

win_getinfo([{winid}])					*win_getinfo()*
...
Obsolete name: getwininfo().		*getwininfo()*

[lacygoill]

Yes, I'm closing because it looks like aliases would create more issues than they solve. Instead, I'll review all the function names, try to come up with more consistent names whenever possible, and open a new issue asking whether these new names could be provided as builtin replacements to the old ones.

[lacygoill]

Closed #7658.

[lacygoill]

There is still the issue of the arguments of some functions like setqflist(). The syntax of the latter has grown too complex. It would be easier to use if we could provide them as a single dictionary. But I don't know whether a new mechanism could solve that.

[Yegappan Lakshmanan]

Hi,

On Mon, Jan 11, 2021 at 5:52 AM lacygoill <vim-dev...@256bit.org> wrote:

Is your feature request about something that is currently impossible or hard to do? Please describe the problem.

It is difficult to get used to some builtin function names, because of their inconsistency.

For example, many function related to Vim windows start with the prefix win or win_; type :h win*( on the command-line then press <C-D>, and you'll get this list:

winnr()           winwidth()        winlayout()       winrestcmd()      gettabwinvar()    getcmdwintype()

wincol()          win_getid()       win_gotoid()      win_execute()     settabwinvar()    windowsversion()

winline()         getwinpos()       win_id2win()      win_findbuf()     tabpagewinnr()

bufwinid()        getwinvar()       getwininfo()      win_gettype()     win_id2tabwin()

bufwinnr()        setwinvar()       getwinposx()      winrestview()     win_screenpos()

winbufnr()        winheight()       getwinposy()      winsaveview()     win_splitmove()

Notice that some of them don't start with win:

• getcmdwintype()
• gettabwinvar()
• getwininfo()
• getwinpos()
• getwinposx()
• getwinposy()
• getwinvar()
• setwinvar()

I left out bufwinid() and bufwinnr() because those make sense.

I also left out tabpagewinnr() and settabwinvar() because I'm not sure whether it would make sense to rename them; and if it is, I'm not sure how to rename them. For the same reasons, I left out function names which start with win without an underscore afterward.

Anyway, it might be useful to rename the previous list of functions like this:

I agree that we should have consistent naming for the builtin functions.

 

• win_getcmdtype()

The getcmdwintype() function returns the type of the command window (cmdwin).

So I am not sure whether splitting win and cmd in this case makes it more

readable.

 

• win_gettabvar()

The gettabwinvar() function returns the window local variable given the

window number and the tabpage number. The new name win_gettabvar()

implies this returns the tabpage local variable (??).

 

Regards,

Yegappan

--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php

---
You received this message because you are subscribed to the Google Groups "vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vim_dev+u...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/vim_dev/vim/vim/issues/7658%40github.com.

[vim-dev ML]

Hi,

On Mon, Jan 11, 2021 at 5:52 AM lacygoill <vim-dev...@256bit.org> wrote:

> *Is your feature request about something that is currently impossible or
> hard to do? Please describe the problem.*

>
> It is difficult to get used to some builtin function names, because of
> their inconsistency.
>
> For example, many function related to Vim windows start with the prefix
> win or win_; type :h win*( on the command-line then press <C-D>, and
> you'll get this list:
>
> winnr() winwidth() winlayout() winrestcmd() gettabwinvar() getcmdwintype()
>
> wincol() win_getid() win_gotoid() win_execute() settabwinvar() windowsversion()
>
> winline() getwinpos() win_id2win() win_findbuf() tabpagewinnr()
>
> bufwinid() getwinvar() getwininfo() win_gettype() win_id2tabwin()
>
> bufwinnr() setwinvar() getwinposx() winrestview() win_screenpos()
>
> winbufnr() winheight() getwinposy() winsaveview() win_splitmove()
>
>
> Notice that some of them don't start with win:
>

> - getcmdwintype()
> - gettabwinvar()
> - getwininfo()
> - getwinpos()
> - getwinposx()
> - getwinposy()
> - getwinvar()
> - setwinvar()

>
> I left out bufwinid() and bufwinnr() because those make sense.
>
> I also left out tabpagewinnr() and settabwinvar() because I'm not sure
> whether it would make sense to rename them; and if it is, I'm not sure how
> to rename them. For the same reasons, I left out function names which start
> with win without an underscore afterward.
>
> Anyway, it might be useful to rename the previous list of functions like
> this:
>

I agree that we should have consistent naming for the builtin functions.


>

> - win_getcmdtype()

>
>
The getcmdwintype() function returns the type of the command window
(cmdwin).
So I am not sure whether splitting win and cmd in this case makes it more
readable.


>

> - win_gettabvar()

>
> The gettabwinvar() function returns the window local variable given the
window number and the tabpage number. The new name win_gettabvar()
implies this returns the tabpage local variable (??).

Regards,
Yegappan

> - win_getinfo()
> - win_getpos()
> - win_getposx()
> - win_getposy()
> - win_getvar()
> - win_setvar()
>
> *Describe the solution you'd like*

>
> A new Ex command – as a temporary suggestion :defalias – which would work
> in a similar way as in emacs

> <https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Functions.html>

> .
>
> We could use it like this:
>
> :defalias getwininfo win_getinfo
>
>
> From now on, whenever we write win_getinfo(), Vim knows that it should –
> in fact – call getwininfo().
>

> *Describe alternatives you've considered*

> *Additional context*

>
> The fact that the most important property has not always been put first in
> a function name is a known issue, which causes some related functions to be
> scattered. See this comment

> <https://github.com/vim/vim/pull/6932#issuecomment-691212905> for example:

>
> In the past we have not put the most important property first, which
> causes related methods to be scattered. So getmatches() sorts far
> away from other match functions. matchesget() might have been better,
> although it doesn't sounds so good.
>
> Maybe aliases could address this issue.

> ------------------------------

>
> One could argue that it would create an inconsistent ecosystem: everyone
> would rename their functions however they want, and reading code would be
> more difficult.
>
> Still, I thought it was worth suggesting the idea. Maybe the community
> would come up with some sensible aliases, which would then be merged in the
> Vim repository as an optional package. Something similar to vim-sensible

> <https://github.com/tpope/vim-sensible> which tries to provide good

> default option settings.
>
> I guess it would make the code slower, because every time a function name
> is not found, Vim would need to look up whether it's an alias. But that
> should not be too much of an issue in Vim9 script, right? I mean, in Vim9
> script the code is compiled, so the cost of looking up whether an unknown
> function name is an error or an alias would only be paid once, at compile
> time.

> ------------------------------

>
> If it is implemented, it would be nice for the documentation to keep
> working. That is, pressing K on win_getinfo() in a Vim9 script should
> still bring up the help topic :h getwininfo(), and not raise an error.

> ------------------------------

>
> I also wanted to suggest something for the arguments of a function which –
> over time – can make the syntax of a function look weird and too difficult
> to remember (e.g. setqflist()), but:
>

> - it would make the current report too confusing
> - I'm not sure the current enhancement is technically possible
> - I'm not sure the current enhancement receives enough interest

>
> —
> You are receiving this because you are subscribed to this thread.
> Reply to this email directly, view it on GitHub

> <https://github.com/vim/vim/issues/7658>, or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/ACY5DGFTPS5TWU6QAGUQUOTSZL7A3ANCNFSM4V5S5IFA>
> .

>
> --
> --
> You received this message from the "vim_dev" maillist.
> Do not top-post! Type your reply below the text you are replying to.
> For more information, visit http://www.vim.org/maillist.php
>
> ---
> You received this message because you are subscribed to the Google Groups
> "vim_dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to vim_dev+u...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/vim_dev/vim/vim/issues/7658%40github.com

> <https://groups.google.com/d/msgid/vim_dev/vim/vim/issues/7658%40github.com?utm_medium=email&utm_source=footer>
> .

[Yegappan Lakshmanan]

Hi,

On Mon, Jan 11, 2021 at 6:57 AM lacygoill <vim-dev...@256bit.org> wrote:

There is still the issue of the arguments of some functions like setqflist(). The syntax of the latter has grown too complex. It would be easier to use if we could provide them as a single dictionary. But I don't know whether a new mechanism could solve that.

We did discuss about adding a new setqfprop() function last year:

https://github.com/vim/vim/pull/5741

I did create a patch for this several years ago which I haven't sent out yet.

I will try to create a new PR for this.

Regards,

Yegappan

[vim-dev ML]

[Bram Moolenaar]

> Yes, I'm closing because it looks like aliases would create more
> issues than they solve. Instead, I'll review all the function names,
> try to come up with more consistent names whenever possible, and open
> a new issue asking whether these new names could be provided as
> builtin replacements to the old ones.

Yes, the functions have been added one at a time, which has caused
names, and also arguments, to become unpredictable.

Before we add new names, we have to be sure it's an actual improvement.
Otherwise we just create more names and cause more confusion. It's a
dangerous thing to bring up for discussion, it can consume a lot of time
and disagreement.

We could see what other language has organised functions nicely.
Unfortunately I only know examples of libraries with the same problem of
Vim, where growth over time has caused confusion.

--
I'm writing a book. I've got the page numbers done.

/// Bram Moolenaar -- Br...@Moolenaar.net -- http://www.Moolenaar.net \\\
/// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\ an exciting new programming language -- http://www.Zimbu.org ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///

—
You are receiving this because you commented.