Working with lua

Contents

1. Manage lua packages with luarocks
2. Get lua code completion in neovim
3. Get code completion & documentation for Hammerspoon fields and methods
4. Lint with luacheck
5. Autoformat lua with lua-formatter
6. Run and evaluate tests with busted & luacov

Install everything all at once

brew install luarocks
luarocks install lua-lsp
luarocks install luacheck
luarocks install argcheck
luarocks install luaformatter
luarocks install busted
luarocks install luacov

---

install luarocks

luarocks is the package manager for the Lua programming language. It is the easiest way to install each of the lua development tools described below.

luarocks is the package manager for the Lua programming language. It is the easiest way to install each of the lua development tools described below.

brew install luarocks

---

setup lua code-completion in (neo)vim

Language-server-protocol (LSP) enables content and library aware code completion in your editor.

In VSCode, enabling LSP-powered code completion is as easy as installing an extension. Read on to see how to get the same experience in vim or neovim.

Install lus-lsp with luarocks

We'll assume you're using coc.nvim for autocompletion (until neovim releases native LSP, that is). Also, see lua package manager if you haven't installed luarocks.

luarocks install lua-lsp

Add this section to your coc-settings.json:

"languageserver": {
        "lua": {
            "command": "YOUR-PATH-TO/lua-language-server/bin/macOS/lua-language-server",
            "args": ["-E", "YOUR-PATH-TO/lua-language-server/main.lua"],
            "filetypes": ["lua"],
            "rootPatterns": [".git/"],
            "settings": {
                "Lua": {
                    "workspace": {
                        "library": {
                            "YOUR-PATH-TO/hs-lsp-completion/build/stubs": true,
                            "YOUR-PATH-TO/neovim/runtime/lua": true,
                            "YOUR-PATH-TO/neovim/src/nvim/lua": true
                        },
                        "ignoreDir": [".cache"],
                        "maxPreload": 2000,
                        "preloadFileSize": 1000
                    },
                    "runtime": {
                        "version": "5.4.0"
                    },
                    "diagnostics": {
                        "enable": true,
                        "disable": ["lowercase-global", "unused-local"],
                        "globals": [
                            "hs",
                            "vim",
                            "it",
                            "describe",
                            "setup",
                            "teardown",
                            "before_each",
                            "after_each",
                            "pending",
                            "insulate"
                        ]
                    },
                    "completion": {
                        "keywordSnippet": "Disable"
                    }
                }
            }
        }

},

---

Setup code completion specifically for Hammerspoon modules

Follow the instructions here.

I've created a python script that uses build/docs.json to generate Hammerspoon API stubs using EmmyLua annotations These kinds of annotations are supported by the following lsp servers:

---

Linting with luacheck

If you're not using VS Code, there is still hope. Here's my setup with neovim:

luarocks install luacheck

~/.luacheckrc config file:

-- vim:set ft=lua:

globals = {'hs', 'vim', 'nvim'}

exclude_files = {"/Users/adamwagner/.luacheckrc"}

allow_defined = true

ignore = {
    "113",
    "211/_.*",  -- unused local var, except when prefixed with  "_"
    "212/_.*",  -- unused argument, except when prefixed with  "_"
    "212/self", -- unused argument 'self'
    "213/_.*",  -- unused var in loop, except when prefixed with "_"
    "631",
    "614",
}

.luacheckrc inspiration:

• https://github.com/jaythomas/love-experiment/blob/1aa201e0e6b78639ba778f3e6a78c337f051fea6/.luacheckrc
• https://github.com/d954mas/indicator-2019/blob/fef7bb8a01fbb7addb6dafa7b29b18cd05a246dc/.luacheckrc
• https://github.com/Hugheth/shed-wars/blob/2eeff7353806226b48fed7eef11e3d3ea466417c/.luacheckrc

Config lua-lsp and luacheck for coc.nvim:

Add this section to your coc-settings.json:

"diagnostic-languageserver.filetypes": {
    "lua": "luacheck"
},

Check argument types with argcheck

Link to argcheck Github repo. WARNING: Not available for lua 5.4 :(

Install with luarocks install argcheck.

Run it from the commandline on sourcecode like this:

lua -largcheck file.lua

Argument specifications are parsed from comments near the function declaration in the code.

These can be quite simple comments:

-- string
-- number
function printn(s, n)
  for i = 1, n do print(s) end
end

printn(10, "hello")

$ lua -largcheck test/simple.lua 
lua: test/simple.lua:7: bad argument #1 to 'printn' (string expected, got number '10')

Or LuaDoc-like comments:

--- prints the string s n times
-- @tparam number n how many times to print the string
-- @tparam string s the string to print
function printn(s, n)
  for i = 1, n do print(s) end
end

printn(10, "hello")

$ lua -largcheck test/ldoc.lua 
lua: test/ldoc.lua:8: bad argument #1 to 'printn' (string expected, got number '10')

---

Lua formatter

luarocks install luaformatter

Add this section to your coc-settings.json:

"diagnostic-languageserver.formatters": {
    "lua-format": {
        "command": "lua-format",
        "args": ["-c", "~/.config/luaformatter/config.yaml"]

    }
},
"diagnostic-languageserver.formatFiletypes": {
     "lua": "lua-format"
},

Run and evaluate tests with busted and luacov

luarocks install busted
luarocks install luacov