diff options
| -rw-r--r-- | runtime/doc/lua.txt | 43 |
1 files changed, 34 insertions, 9 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 25c5dd326e..46b9f0576f 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -21,19 +21,44 @@ Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the which can be used from Lua code. A good overview of using Lua in neovim is given by https://github.com/nanotee/nvim-lua-guide. -Module conflicts are resolved by "last wins". For example if both of these -are on 'runtimepath': - runtime/lua/foo.lua - ~/.config/nvim/lua/foo.lua -then `require('foo')` loads "~/.config/nvim/lua/foo.lua", and -"runtime/lua/foo.lua" is not used. See |lua-require| to understand how Nvim -finds and loads Lua modules. The conventions are similar to those of -Vimscript |plugin|s, with some extra features. See |lua-require-example| for -a walkthrough. +The |:source| and |:runtime| commands can run Lua scripts as well as Vim +scripts. Lua modules can be loaded with `require('name')`, which +conventionally returns a table but can return any value. + +See |lua-require| for details on how Nvim finds and loads Lua modules. +See |lua-require-example| for an example of how to write and use a module. ============================================================================== IMPORTING LUA MODULES *lua-require* +Modules are searched for under the directories specified in 'runtimepath', in +the order they appear. Any `.` in the module name is treated as a directory +separator when searching. For a module `foo.bar`, each directory is searched +for `lua/foo/bar.lua`, then `lua/foo/bar/init.lua`. If no files are found, +the directories are searched again for a shared library with a name matching +`lua/foo/bar.?`, where `?` is a list of suffixes (such as `so` or `dll`) +derived from the initial value of `package.cpath`. If still no files are +found, Nvim falls back to Lua's default search mechanism. The first script +found is run and `require()` returns the value returned by the script if any, +else `true`. + +The return value is cached after the first call to `require()` for each +module, with subsequent calls returning the cached value without searching for +or executing any script. For further details on `require()`, see the Lua +documentation at https://www.lua.org/manual/5.1/manual.html#pdf-require. + +For example, if 'runtimepath' is `foo,bar` and `package.cpath` was +`./?.so;./?.dll` at startup, `require('mod')` searches these paths in order +and loads the first module found: + foo/lua/mod.lua + foo/lua/mod/init.lua + bar/lua/mod.lua + bar/lua/mod/init.lua + foo/lua/mod.so + foo/lua/mod.dll + bar/lua/mod.so + bar/lua/mod.dll + *lua-package-path* Nvim automatically adjusts `package.path` and `package.cpath` according to effective 'runtimepath' value. Adjustment happens whenever 'runtimepath' is |