Add documentation for the plugin environment

[goldenstein64]

Plugins have a surprisingly large amount of flexibility when the surrounding environment is considered. Unfortunately, most of the environment is undocumented, which means there's a good chance plugin developers don't know how much their plugin can really do.

Currently, printing out package.path and package.cpath gives these directories

package.path

# directories provided by the extension
$LSP/script/?.lua
$LSP/script/?/init.lua

# access to the plugin's directory
$PLUGIN/?.lua

package.cpath

$LSP/bin/?.dll

where:

• $LSP is the path to this project's folder, and
• $PLUGIN is a path to the plugin's current directory. ~/project/config/plugin.lua would make $PLUGIN point to ~/project/config

Along with giving plugins the ability to have sub-modules, the LSP has some very useful utilities in its script folder like:

• vm for inspecting types (or so it seems)
• parser.compile for getting an AST
• inspect which looks like kikito/inspect.lua
• config for reading LSP settings like Lua.runtime.version

I don't work with Visual Studio enough to understand the DLLs in $LSP/bin, or at least not enough to work with them in Lua.

... has some useful information too.

local inspect = require("inspect")

print(inspect({ ... }))
--[[--> 
{ 
  <function 1>,                   -- this plugin loaded as a chunk using `load()`
  "file:///$WORKSPACE_FOLDER",    -- a URI pointing to the workspace folder
  {}                              -- arguments provided by the setting `Lua.runtime.pluginArgs`
}
]]

I think this information is useful enough to be documented in the wiki. I can contribute to it if need be.

It would be even more useful and accessible if there was a meta-addon that adds the $LSP/script directory to Lua.workspace.library or a boolean option that adds the directory internally. I can try to contribute to that as well.

I understand that $LSP/script may be updated often for bugfixes and other things. If this is the case, I think it would at least be useful to provide a directory for plugin utilities.

I'm not sure about what to do when the VS Code extension gets updated since it changes directory. Maybe, more generally, the LSP can warn you about missing libraries.

Also, if $LSP/script updates too frequently to be mentioned in the wiki, I think the meta-addon route would be more fruitful.

[carsakiller]

I am still yet to try making a plugin and so have no experience with them. The current plugin documentation is the same documentation that existed from before I started working on the wiki.

If you are able to improve the documentation for the wiki, that would be greatly appreciated! Feel free to clone the wiki from https://github.com/LuaLS/lua-language-server.wiki.git and you can just send the updated file here 🙂