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]]
    - [[#lsp][LSP]]
    - [[#lua-mode][Lua mode]]
- [[#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:
- =lsp-emmy= using clangd LSP server
- =lua-mode= using emacs package

*** LSP
LSP support is provided via the [[file:../../+tools/lsp/README.org][LSP layer]], currently only [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua]] is supported.

To use the =lsp-emmy= backend, 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-backend to =lsp-emmy=.

=Lsp-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-emmy
       lua-lsp-emmy-jar-path "~/.emacs.d/EmmyLua-LS-all.jar" ; default path
       lua-lsp-emmy-java-path "java"                         ; default path
       lua-lsp-emmy-enable-file-watchers t)                  ; enabled default
#+END_SRC

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

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