spacemacs/layers/+lang/lua/README.org

#+TITLE: Lua layer

#+TAGS: general|layer|multi-paradigm|programming

[[file:img/lua.gif]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#layer][Layer]]
  - [[#backends][Backends]]
    - [[#lua-mode][Lua mode]]
    - [[#lsp][LSP]]
      - [[#emmy-server-setup][Emmy server setup]]
      - [[#lua-language-server-setup][Lua-language server setup]]
      - [[#lua-lsp-server-setup][Lua-lsp server setup]]
- [[#key-bindings][Key bindings]]
  - [[#lsp-1][LSP]]
  - [[#commands][Commands]]

* Description
This layer adds support for editing Lua.

** Features:
- Editing lua files using [[https://github.com/immerrr/lua-mode][lua-mode]]
- Code-Completion with =lsp= or =company-lua=
- Sending code to a lua REPL
- Code linting using [[https://github.com/mpeterv/luacheck][Luacheck]]
- Cross references (definitions, references, rename...)

* Install
** Layer
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =lua= to the existing =dotspacemacs-configuration-layers= list in this
file.

In order to enable code linting, install [[https://github.com/mpeterv/luacheck][Luacheck]].

** Backends
Supported backends are:
- =lua-mode= using emacs packages
- =lsp= using one of below LSP servers
  - emmy LSP server (default)
  - lua-language-server.
  - lua-lsp.

*** Lua mode
This backend provides basic support via pure emacs packages. It requires less setup than a full blown LSP setup
but also provides less features. To enable it set the =lua-backend= to =lua-mode=.

#+BEGIN_SRC elisp
  (lua :variables
       lua-backend 'lua-mode)
#+END_SRC

*** LSP
This is the prefered backend choice. It relies on an external server implementing the LSP protocol.
It requires installing one of the supported server implementations below:
  - [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua]]
  - [[https://github.com/sumneko/lua-language-server][lua-language-server]]
  - [[https://github.com/Alloyed/lua-lsp][lua-lsp]]

Once it is installed the keybindings are provided by [[file:../../+tools/lsp/README.org][LSP layer]] allowing
consistent keybindings among different layers.

To enable LSP set =lua-backend= to =lsp=. If =lua-backend= is =nil= and the =LSP layer= is loaded
=LSP= will be used automatically otherwise it will fallback to =lua-mode=.

#+BEGIN_SRC elisp
  (lua :variables
       lua-backend 'lsp)
#+END_SRC

**** Emmy server setup
To use the =emmy= lsp server, please download the [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua-LS-all.jar]] and put it into =~/.emacs.d/=.
Then set the layer variable =lua-lsp-server= to =emmy=. This is also the default choice if no specific
lsp server has been selected.

=emmy= requires a working java installation in the path as well as the path to the LSP server jar.
The java path and the path to the server executable can be configured as is shown below:

#+BEGIN_SRC elisp
  (lua :variables
       lua-backend 'lsp
       lua-lsp-server 'emmy
       lsp-clients-emmy-lua-jar-path "~/.emacs.d/.cache/lsp/EmmyLua-LS-all.jar" ; default path
       lsp-clients-emmy-lua-java-path "java") ; default path
#+END_SRC

**** Lua-language server setup
To use the =lua-language-server= lsp server, please follow [[https://github.com/sumneko/lua-language-server][lua-language-server]] to compile the standalone binary. 
Then set the layer variables as shown below:
#+BEGIN_SRC elisp
  (lua :variables
       lua-backend 'lsp
       lua-lsp-server 'lua-language-server
       lsp-clients-lua-language-server-bin "~/.emacs.d/.cache/lsp/lua-language-server/bin/Linux/lua-language-server" ; default path
       lsp-clients-lua-language-server-main-location "~/.emacs.d/.cache/lsp/lua-language-server/main.lua") ; default path
#+END_SRC

**** Lua-lsp server setup
To use the =lua-lsp= lsp server, please follow [[https://github.com/Alloyed/lua-lsp][lua-lsp]] to install the server via
luarocks. Remember that the capabilities of this server are mainly dependent
on the installed luarocks packages, so make sure you have them all installed
for maximum benefit.

To instruct Spacemacs to use this server set your config as shown below:
#+BEGIN_SRC elisp
  (lua :variables
       lua-backend 'lsp
       lua-lsp-server 'lua-lsp
       lsp-clients-luarocks-bin-dir "~/.luarocks/bin/") ; default path
#+END_SRC

* Key bindings
** LSP
The default key bindings for the LSP implementations are defined and documented in
the [[file:../../+tools/lsp/README.org][LSP layer]].

** Commands

| Key binding | Description                                |
|-------------+--------------------------------------------|
| ~SPC m d~   | lookup thing at point in lua documentation |
| ~SPC m s b~ | send buffer contents to REPL               |
| ~SPC m s f~ | send current function to REPL              |
| ~SPC m s l~ | send current line to REPL                  |
| ~SPC m s r~ | send current region to REPL                |
| ~SPC m '~   | open repl buffer                           |