*lua-guide.txt*                        Nvim

                            NVIM REFERENCE MANUAL

                          Guide to using Lua in Nvim


                                       Type |gO| to see the table of contents.

==============================================================================
Introduction                                                         *lua-guide*

This guide will go through the basics of using Lua in Nvim. It is not meant
to be a comprehensive encyclopedia of all available features, nor will it
detail all intricacies. Think of it as a survival kit -- the bare minimum
needed to know to comfortably get started on using Lua in Nvim.

An important thing to note is that this isn't a guide to the Lua language
itself. Rather, this is a guide on how to configure and modify Nvim through
the Lua language and the functions we provide to help with this. Take a look
at |luaref| and |lua-concepts| if you'd like to learn more about Lua itself.
Similarly, this guide assumes some familiarity with the basics of Nvim
(commands, options, mappings, autocommands), which are covered in the
|user-manual|.

------------------------------------------------------------------------------
Some words on the API                                            *lua-guide-api*

The purpose of this guide is to introduce the different ways of interacting
with Nvim through Lua (the "API"). This API consists of three different
layers:

1. The "Vim API" inherited from Vim: |Ex-commands| and |builtin-functions| as
well as |user-function|s in Vimscript. These are accessed through |vim.cmd()|
and |vim.fn| respectively, which are discussed under |lua-guide-vimscript|
below.

2. The "Nvim API" written in C for use in remote plugins and GUIs; see |api|.
These functions are accessed through |vim.api|.

3. The "Lua API" written in and specifically for Lua. These are any other
functions accessible through `vim.*` not mentioned already; see |lua-stdlib|.

This distinction is important, as API functions inherit behavior from their
original layer: For example, Nvim API functions always need all arguments to
be specified even if Lua itself allows omitting arguments (which are then
passed as `nil`); and Vim API functions can use 0-based indexing even if Lua
arrays are 1-indexed by default.

Through this, any possible interaction can be done through Lua without writing
a complete new API from scratch. For this reason, functions are usually not
duplicated between layers unless there is a significant benefit in
functionality or performance (e.g., you can map Lua functions directly through
|nvim_create_autocmd()| but not through |:autocmd|). In case there are multiple
ways of achieving the same thing, this guide will only cover what is most
convenient to use from Lua.

==============================================================================
Using Lua                                                  *lua-guide-using-Lua*

To run Lua code from the Nvim command 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