doomemacs/modules/lang/lua/README.org

#+title:    :lang lua
#+subtitle: One-based indices? one-based indices
#+created:  Jun 03, 2020
#+since:    21.12.0

* Description :unfold:
This module adds Lua support to Doom Emacs.

- REPL
- Love2D specific functions
- Moonscript support
- Fennel support

** Maintainers
- [[doom-user:][@hlissner]]

[[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +fennel ::
  Enable support for the Fennel language.
- +lsp ::
  Enable LSP support for ~lua-mode~. Requires [[doom-module::tools lsp]] and a langserver
  (supports EmmyLua, lua-language-server, and lua-lsp).
- +tree-sitter ::
  Leverages tree-sitter for better syntax highlighting and structural text
  editing. Requires [[doom-module::tools tree-sitter]]. Has support for both Lua and
  Fennel.
- +moonscript ::
  Enable support for the Moonscript language.

** Packages
- [[doom-package:company-lua]] if [[doom-module::completion company]]
- [[doom-package:fennel-mode]] if [[doom-module:+fennel]]
- [[doom-package:lua-mode]]
- if [[doom-module:+moonscript]]
  - [[doom-package:flycheck-moonscript]] if [[doom-module::checkers syntax]]
  - [[doom-package:moonscript-mode]]

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module requires Lua 5.1+ for most of its capabilities and, optionally, the
fennel and moonscript transpilers. An LSP server is also required for LSP
support.

** Language Server Protocol servers
LSP server support depends on which flavor of the [[doom-module::tools lsp]] module you have
installed ([[doom-package:eglot]] or [[doom-package:lsp-mode]]).

*** LSP-mode
Three servers are supported, ordered from highest to lowest priority:
- [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua-LanguageServer]] :: Must be in
  =$EMACSDIR/.local/etc/lsp/EmmyLua-LS-all.jar=. See
  ~lsp-clients-emmy-lua-jar-path~ variable to change this.
- [[https://github.com/sumneko/lua-language-server][Sumneko language server]] (lua-language-server) :: Must be in
  =$EMACSDIR/.local/etc/lsp/lua-language-server/=. See
  ~lsp-clients-lua-language-server-bin~ variable to change this.
- [[https://github.com/Alloyed/lua-lsp][lua-lsp]] :: Must be available in =~/.luarocks/bin/lua-lsp=. See
  ~lsp-clients-lua-lsp-server-install-dir~ variable to change this.

[[https://emacs-lsp.github.io/lsp-mode/page/lsp-emmy-lua/][LSP-mode documentation]] has more information about setting up the server and the
configuration variables correctly.

*** Eglot
Eglot currently only supports one of the above servers out of the box:
+ [[https://github.com/sumneko/lua-language-server][Sumneko language server]] (lua-language-server) :: Must be in
  =$EMACSDIR/.local/etc/lsp/lua-language-server/=. See ~+lua-lsp-dir~ variable
  to change this.

* TODO Usage
#+begin_quote
 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

- lua-lsp-dir :: This must be set when using [[doom-module:+lsp]] and using [[https://github.com/sumneko/lua-language-server][lua-language-server]].
  This controls where the repository has been cloned and built to finish the
  configuration of the server.

* Troubleshooting
[[doom-report:][Report an issue?]]

** Install lua-language-server
A [[https://github.com/sumneko/lua-language-server/issues/60][catch-all issue]] has been created to gather help for installing
lua-language-server on non-VSCode platforms.

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote