Skip to content

Update plugins wiki page #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 24, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 62 additions & 6 deletions src/content/wiki/plugins.mdx
Original file line number Diff line number Diff line change
@@ -1,16 +1,18 @@
---
title: Plugins
description: Add support for a custom syntax that can export standard Lua.
incomplete: true
---

import Remark from "~/components/common/Remark.astro";
import Icon from "~/components/common/Icon.astro";
import Accordion from "~/components/common/Accordion.astro";

<video autoplay controls loop muted>
<source src="/videos/wiki/plugin-diff.webm" type="video/webm" />
<source src="/videos/wiki/plugin-diff.mp4" type="video/mp4" />
</video>
<div align="center">*[View code](#demo-example)*</div>

## Introduction
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](/wiki/diagnostics).

## Template

Expand Down Expand Up @@ -43,9 +45,8 @@ This function provides the uri and text of the file that has been edited and exp
function OnSetText(uri, text) end
```

## Example

The example [above](#plugins) uses the below code:
<Accordion>
<span slot="summary" id="demo-example">Example</span>

```Lua
function OnSetText(uri, text)
Expand Down Expand Up @@ -75,3 +76,58 @@ function OnSetText(uri, text)
return diffs
end
```

</Accordion>

### OnTransformAst
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`.

```Lua
---@param uri string # The uri of file
---@param ast parser.object # The file ast
---@return parser.object? ast
function OnTransformAst(uri, ast) end
```

### VM.OnCompileFunctionParam
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`.

```Lua
---@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
```

<Accordion>
<span slot="summary">Example</span>

```Lua
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
```

</Accordion>