*lua.txt*    Nvim


                            NVIM REFERENCE MANUAL


Lua engine                                                           *lua* *Lua*

                                       Type |gO| to see the table of contents.

==============================================================================
INTRODUCTION                                                       *lua-intro*

The Lua 5.1 script engine is builtin and always available. Try this command to
get an idea of what lurks beneath: >vim

    :lua vim.print(package.loaded)

Nvim includes a "standard library" |lua-stdlib| for Lua.  It complements the
"editor stdlib" (|vimscript-functions| + |Ex-commands|) and the |API|, all of
which can be used from Lua code (|lua-vimscript| |vim.api|). These three
namespaces form the Nvim programming interface.

Lua plugins and user config are automatically discovered and loaded, just like
Vimscript. See |lua-guide| for practical guidance.

You can also run Lua scripts from your shell using the |-l| argument: >
    nvim -l foo.lua [args...]
<
                                                                  *lua-compat*
Lua 5.1 is the permanent interface for Nvim Lua. Plugins should target Lua 5.1
as specified in |luaref|; later versions (which are essentially different,
incompatible, dialects) are not supported. This includes extensions such as
`goto` that some Lua 5.1 interpreters like LuaJIT may support.

                                                                  *lua-luajit*
While Nvim officially only requires Lua 5.1 support, it should be built with
LuaJIT or a compatible fork on supported platforms for performance reasons.
LuaJIT also comes with useful extensions such as `ffi`, |lua-profile|, and
enhanced standard library functions; these cannot be assumed to be available,
and Lua code in |init.lua| or plugins should check the `jit` global variable
before using them: >lua
  if jit then
    -- code for luajit
  else
    -- code for plain lua 5.1
  end
<
One exception is the LuaJIT `bit` extension, which is always available: when
built with PUC Lua, Nvim includes a fallback implementation which provides
`require("bit")`. See |lua-bit|.

                                                                  *lua-profile*
If Nvim is built with LuaJIT, Lua code can be profiled via >lua
    -- Start a profiling session:
    require('jit.p').start('ri1', '/tmp/profile')

    -- Perform arbitrary tasks (use plugins, scripts, etc.) ...

    -- Stop the session. Profile is written to /tmp/profile.
    require('jit.p').stop()

See https://luajit.org/ext_profiler.html or the `p.lua` source for details: >
    :lua vim.cmd.edit(package.searchpath('jit.p', package.path))

==============================================================================
LUA CONCEPTS AND IDIOMS                                         *lua-concepts*

Lua is very simple, and _consistent_: while there are some quirks, once you
internalize those quirks, everything works the same everywhere. Scopes
(closures) in particular are very consistent, unlike JavaScript or most other
languages.

Lua has three fundamental mechanisms—one for "each major aspect of
programming": tables, closures, and coroutines.
https://www.lua.org/doc/cacm2018.pdf
- Tables are the "object" or container datastructure: they represent both
  lists and maps, you can extend them to represent your own datatypes and
  change their behavior using |metatable|s (like Python's "datamodel").
- EVERY scope in Lua is a closure: a function is a closure, a module is
  a closure, a `do` block (|lua-do|) is a closure--and they all work the same.
  A Lua module is literally just a big closure discovered on the "path"
  (where your modules are found: |package.cpath|).
- Stackful coroutines enable cooperative multithreading, generators, and
  versatile control for both Lua and its host (Nvim).

                                                          *lua-error-handling*
Lua functions may throw |lua-errors|