Home Explore Blog CI



neovim

2nd chunk of `runtime/doc/lua-guide.txt`
1eb2d416594a4f262ee51f7931c473898b5ad9a6600a31a50000000100000fbd
 line, use the |:lua| command:
>vim
    :lua print("Hello!")
<
Note: each |:lua| command has its own scope and variables declared with the
local keyword are not accessible outside of the command. This won't work:
>vim
    :lua local foo = 1
    :lua print(foo)
    " prints "nil" instead of "1"
<
You can also use `:lua=`, which is equivalent to `:lua vim.print(...)`, to
conveniently check the value of a variable or a table:
>vim
    :lua =package
<
To run a Lua script in an external file, you can use the |:source| command
exactly like for a Vimscript file:
>vim
    :source ~/programs/baz/myluafile.lua
<
Finally, you can include Lua code in a Vimscript file by putting it inside a
|:lua-heredoc| block:
>vim
    lua << EOF
      local tbl = {1, 2, 3}
      for k, v in ipairs(tbl) do
        print(v)
      end
    EOF
<
------------------------------------------------------------------------------
Using Lua files on startup                                    *lua-guide-config*

Nvim supports using `init.vim` or `init.lua` as the configuration file, but
not both at the same time. This should be placed in your |config| directory
(run `:echo stdpath('config')` to see where it is). Note that you can also use
Lua in `init.vim` and Vimscript in `init.lua`, which will be covered below.

If you'd like to run any other Lua script on |startup| automatically, then you
can simply put it in `plugin/` in your |'runtimepath'|.

------------------------------------------------------------------------------
Lua modules                                                  *lua-guide-modules*

If you want to load Lua files on demand, you can place them in the `lua/`
directory in your |'runtimepath'| and load them with `require`. (This is the
Lua equivalent of Vimscript's |autoload| mechanism.)

Let's assume you have the following directory structure:
>
    ~/.config/nvim
    |-- after/
    |-- ftplugin/
    |-- lua/
    |   |-- myluamodule.lua
    |   |-- other_modules/
    |       |-- anothermodule.lua
    |       |-- init.lua
    |-- plugin/
    |-- syntax/
    |-- init.vim
<
Then the following Lua code will load `myluamodule.lua`:
>lua
    require("myluamodule")
<
Note the absence of a `.lua` extension.

Similarly, loading `other_modules/anothermodule.lua` is done via
>lua
    require('other_modules/anothermodule')
    -- or
    require('other_modules.anothermodule')
<
Note how "submodules" are just subdirectories; the `.` is equivalent to the
path separator `/` (even on Windows).

A folder containing an |init.lua| file can be required directly, without
having to specify the name of the file:
>lua
    require('other_modules') -- loads other_modules/init.lua
<
Requiring a nonexistent module or a module which contains syntax errors aborts
the currently executing script. `pcall()` may be used to catch such errors. The
following example tries to load the `module_with_error` and only calls one of
its functions if this succeeds and prints an error message otherwise:
>lua
    local ok, mymod = pcall(require, 'module_with_error')
    if not ok then
      print("Module had an error")
    else
      mymod.func()
    end
<
In contrast to |:source|, |require()| not only searches through all `lua/` directories
under |'runtimepath'|, it also caches the module on first use. Calling
`require()` a second time will therefore _not_ execute the script again and
instead return the cached file. To rerun the file, you need to remove it from
the cache manually first:
>lua
    package.loaded['myluamodule'] = nil
    require('myluamodule')    -- read and execute the module again from disk
<
------------------------------------------------------------------------------
See also:
• |lua-module-load|
• |pcall()|

==============================================================================
Using Vim commands and functions from Lua                  *lua-guide-vimscript*

All Vim commands and functions are accessible from Lua.

------------------------------------------------------------------------------

Title: Lua Configuration, Modules, and Vimscript Interaction
Summary
This section details how to configure Nvim using Lua files on startup, placing them in the appropriate configuration directory. It also explains how to use Lua modules with `require` by placing them in the `lua/` directory within the runtime path, demonstrating directory structure and module loading, including handling errors with `pcall()` and caching behavior. Finally, it mentions that all Vim commands and functions are accessible from Lua.