Plugins allow you to create a custom syntax that will then be output to a separate file. They cannot be used to report custom diagnostics.
You can use the provided template to get started.
- Add
--develop=truetomisc.parameters.- This allows the plugin to write to
LOGPATH/diffed.lua.
- This allows the plugin to write to
- Create a Lua file where you will crate the plugin. This could be in an addon, your workspace, or some random directory on your machine.
- Specify the path to the plugin via the
runtime.pluginsetting.
For info on how to debug the plugin, see Developing.
This function provides the uri and text of the file that has been edited and expects a list of differences to be returned. The result will be written to diffed.lua in your log location.
---@class diff
---@field start integer # The number of bytes at the beginning of the replacement
---@field finish integer # The number of bytes at the end of the replacement
---@field text string # What to replace
---@param uri string # The uri of file
---@param text string # The content of file
---@return nil|diff[]
function OnSetText(uri, text) end
Example
function OnSetText(uri, text)
if text:sub(1, 4) ~= '--##' then
return nil
end
local diffs = {}
diffs[#diffs+1] = {
start = 1,
finish = 4,
text = '',
}
for localPos, colonPos, typeName, finish in text:gmatch '()local%s+[%w_]+()%s*%:%s*([%w_]+)()' do
diffs[#diffs+1] = {
start = localPos,
finish = localPos - 1,
text = ('---@type %s\n'):format(typeName),
}
diffs[#diffs+1] = {
start = colonPos,
finish = finish - 1,
text = '',
}
end
return diffs
end
This function provides the ability to modify ast.
After the token is generated and before the comments are compiled, so it is possible to modify ast directly and ensure that changes to the comments take effect as well.
You can return new one ast or modify the origin ast.
---@param uri string # The uri of file
---@param ast parser.object # The file ast
---@return parser.object? ast
function OnTransformAst(uri, ast) end
This function modifies the behavior of a function when compiling (presumably) the type of its arguments.
next is the compiler's default behavior for functions. func is the function to be compiled, param is the parameter.
If all functions return false, the parameter is defined as any.
---@param next fun(func:parser.object, param:parser.object) # Default behavior
---@param func parser.object # The function
---@param param parser.object # The param
---@return boolean? ready # Already know the type.
function VM.OnCompileFunctionParam(next, func, param) end
Example
local nodeHelper = reuqire 'nodeHelper'
-- Create pattern that already matches code in the form of `*.components.`
local pattern = nodeHelper.createFieldPattern("*.components")
function VM.OnCompileFunctionParam (next, func, param)
-- Call the default
if next(func, param) then
return true -- If ready known the type, return true. Also you can continue
end
-- Try match pattern
if nodeHelper.matchPattern(source, pattern) then
-- Add a TestClass type to the parameters that match the pattern
local type = vm.declareGlobal('type', 'TestClass', TESTURI)
vm.setNode(source, vm.createNode(type, source))
return true
end
end
This function allows plugin to manually resolve require('...') file paths. Useful for environments that implement custom require resolution.
Return nil to use default LuaLS resolution. If you return an empty table - LuaLS will not resolve paths.
---@param uri string # The URI of file
---@param name string # Argument of require()
---@return string[]?
function ResolveRequire(uri, name) end
Example
---@param uri string # The URI of file
---@param name string # Argument of require()
---@return string[]?
function ResolveRequire(uri, name)
-- Check if it's our custom name format
if name:byte(1) ~= 0x40 then -- '@' at beginning
return nil
end
-- Return path to real file location
return { "file:///path/to/mods/" .. name:sub(2) .. "/main.lua" }
end