doc: getting started with lua

[clason]

Lua integration is quickly shaping up to be the killer feature of neovim, and the upcoming LSP functionality will likely get many more people interested in customizing and extending it via Lua.
In order to make this as pleasant as possible, it would be good to have some sort of introduction to writing Lua for neovim.

This should assume familiarity with Lua (there are enough good introductions to the language around) and not replace the :h lua documentation; rather, it should give an overview of the fundamental ways of interacting with neovim and show what's possible: for example, addressing vim.call, vim.fn, vim.cmd, and the difference between them, or when to use lua vs. luaeval

One possibility would be adding a wiki page structured around common tasks with small examples each, such as on

1. reading vimscript variables or options from lua
2. setting vimscript variables or options from lua
3. calling vim functions from lua
4. calling lua functions from vim
5. the same, but catching return values
6. defining mappings from lua
7. defining autocommands from lua
8. ...
   (feel free to suggest others that you wish you had known when starting to write lua for neovim).

(Basically, a more comprehensive version of https://teukka.tech/luanvim.html. The advantage of an official wiki page would be discoverability via search engines. Ideally, googling neovim autocommand lua would lead to that page first rather than test code on github, followed by an old reddit post...)

EDIT: This is pretty close to what I had in mind: https://github.com/nanotee/nvim-lua-guide

@tjdevries

[Iron-E]

I recently wrote nvim-libmodal using the Lua API for Neovim (0.4 and 0.5 versions). There are some things that I really didn't understand from the :help pages, and sort of just had to toy with it until it worked.

These are all things I discovered through lua.txt but then kind of floundered with:

1. nvim_call_atomic seems to be absent from Vimscript and Lua.
   • The docs also could use an example, if it's meant to still be there.
2. v:lua.require.
   • See here.
3. custom/customlist in command/input() requires a Vimscript wrapper function.
   • This one I had to toy with a lot. I think adding something for how to get Lua functions into places where they can only be strings would be really helpful.
4. No workaround noted for funcref limitations between Vimscript and lua.
   • e.g. my plugin has a function that applies a "layer" over the currently active keybindings. It returns a function to undo the layer's changes. However, I can't implement a Vimscript function for it because I haven't been able to find a way to get the exit function across to Vimscript (without global declarations).
5. vim.loop has a lot of missing pieces.
   • vim.loop.spawn has no references.
   • I had to guess which functions existed for timers, as only :start is demonstrated for new_timer.
     • And, you can't vim.inspect userdata.
   • e.g. :stop() is a function (in place of timer_stop), but :info() is not (in place of timer_info).
6. vim.g, vim.o, vim.b, vim.v, etc don't have help references yet.
   • Once I learned about these, though, it took quite a few API calls out of the codebase (down from 3% to 2% of my code).
7. No vim.cmd help yet (this issue actually introduced me to it).

I would like to say that the treesitter docs are fantastic!

Probably the most helpful thing was the lua-require-example— I probably referenced that tag in 10 places in my own docs.

[ms-jpq]

To add to OP.

The async Lua APIs in neovim are heavily callback based. Yet we don't have an out of box way of doing async await. This hurts ergonomics quit a bit imo.

Thankfully, it is actually pretty easy to add some sugar on top of lua coroutines to assemble async await.

I wrote a guide for doing it here: https://github.com/ms-jpq/neovim-async-tutorial. I hope it helps :)

[tjdevries]

@ms-jpq Does the new vim.wait that was just merged into master help w/ anything you were doing there? (I did not have time to investigate your example much, just wondering)

[clason]

Update: https://github.com/nanotee/nvim-lua-guide is exactly what I was looking for and is actively maintained. I think it is sufficient to advertise this in lua.txt (and maybe in the README, if this mentions Lua integration as a standout feature).