Home Explore Blog CI



neovim

7th chunk of `runtime/doc/lua.txt`
06cd8ae68dd2714cc1c93b278cc85c070c21d76f2a03fd100000000100000fa0
 it from a package.
    vim.bo[buf].omnifunc = 'v:lua.mymod.omnifunc'

You can also use `v:lua` to call Lua functions as Vimscript |method|s: >vim
    :eval arg1->v:lua.somemod.func(arg2)
<
Note: `v:lua` without a call is not allowed in a Vimscript expression:
|Funcref|s cannot represent Lua functions. The following are errors: >vim

    let g:Myvar = v:lua.myfunc        " Error
    call SomeFunc(v:lua.mycallback)   " Error
    let g:foo = v:lua                 " Error
    let g:foo = v:['lua']             " Error
<
==============================================================================
Lua standard modules                                              *lua-stdlib*

The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
various functions and sub-modules. It is always loaded, thus `require("vim")`
is unnecessary.

You can peek at the module properties: >vim

    :lua vim.print(vim)

Result is something like this: >

    {
      _os_proc_children = <function 1>,
      _os_proc_info = <function 2>,
      ...
      api = {
        nvim__id = <function 5>,
        nvim__id_array = <function 6>,
        ...
      },
      deepcopy = <function 106>,
      gsplit = <function 107>,
      ...
    }

To find documentation on e.g. the "deepcopy" function: >vim

    :help vim.deepcopy()

Note that underscore-prefixed functions (e.g. "_os_proc_children") are
internal/private and must not be used by plugins.

------------------------------------------------------------------------------
VIM.UV                                                   *lua-loop* *vim.uv*

`vim.uv` exposes the "luv" Lua bindings for the libUV library that Nvim uses
for networking, filesystem, and process management, see |luvref.txt|.
In particular, it allows interacting with the main Nvim |luv-event-loop|.

                                                    *E5560* *lua-loop-callbacks*
It is an error to directly invoke `vim.api` functions (except |api-fast|) in
`vim.uv` callbacks. For example, this is an error: >lua

    local timer = vim.uv.new_timer()
    timer:start(1000, 0, function()
      vim.api.nvim_command('echomsg "test"')
    end)
<
To avoid the error use |vim.schedule_wrap()| to defer the callback: >lua

    local timer = vim.uv.new_timer()
    timer:start(1000, 0, vim.schedule_wrap(function()
      vim.api.nvim_command('echomsg "test"')
    end))
<
(For one-shot timers, see |vim.defer_fn()|, which automatically adds the
wrapping.)

Example: repeating timer
    1. Save this code to a file.
    2. Execute it with ":luafile %". >lua

    -- Create a timer handle (implementation detail: uv_timer_t).
    local timer = vim.uv.new_timer()
    local i = 0
    -- Waits 1000ms, then repeats every 750ms until timer:close().
    timer:start(1000, 750, function()
      print('timer invoked! i='..tostring(i))
      if i > 4 then
        timer:close()  -- Always close handles to avoid leaks.
      end
      i = i + 1
    end)
    print('sleeping');
<
Example: File-change detection                                    *watch-file*
    1. Save this code to a file.
    2. Execute it with ":luafile %".
    3. Use ":Watch %" to watch any file.
    4. Try editing the file from another text editor.
    5. Observe that the file reloads in Nvim (because on_change() calls
       |:checktime|). >lua

    local w = vim.uv.new_fs_event()
    local function on_change(err, fname, status)
      -- Do work...
      vim.api.nvim_command('checktime')
      -- Debounce: stop/start.
      w:stop()
      watch_file(fname)
    end
    function watch_file(fname)
      local fullpath = vim.api.nvim_call_function(
        'fnamemodify', {fname, ':p'})
      w:start(fullpath, {}, vim.schedule_wrap(function(...)
        on_change(...) end))
    end
    vim.api.nvim_command(
      "command! -nargs=1 Watch call luaeval('watch_file(_A)', expand('<args>'))")
<
                                                         *inotify-limitations*
When on Linux you may need to increase

Title: Lua Standard Modules (vim) and vim.uv
Summary
This section discusses the `vim` module, the Nvim Lua standard library, and how to access its functions and sub-modules. It emphasizes that `require("vim")` is unnecessary. It also explains how to find documentation for functions within the module and notes that underscore-prefixed functions are internal and should not be used by plugins. The section then introduces `vim.uv`, which exposes the libUV library for networking, filesystem, and process management. It warns against directly invoking `vim.api` functions in `vim.uv` callbacks and suggests using `vim.schedule_wrap()` to defer them. It provides examples of a repeating timer and file-change detection using `vim.uv`.