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.
------------------------------------------------------------------------------