From 60d79ef57efc01ae04538fc4da5fa7325a746e90 Mon Sep 17 00:00:00 2001 From: nerix Date: Fri, 29 Dec 2023 18:12:50 +0100 Subject: [PATCH] Improve docs/supplemental files for plugins (#5047) Co-authored-by: Mm2PL --- CHANGELOG.md | 2 +- docs/chatterino.d.ts | 4 +-- docs/plugin-info.schema.json | 3 ++- docs/plugin-meta.lua | 50 ++++++++++++++++++++++++++++++++++++ docs/wip-plugins.md | 36 ++++++++++++++++++++++++++ 5 files changed, 91 insertions(+), 4 deletions(-) create mode 100644 docs/plugin-meta.lua diff --git a/CHANGELOG.md b/CHANGELOG.md index a65e2cf27..478ae83e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ - Minor: Add an option to use new experimental smarter emote completion. (#4987) - Minor: Add `--safe-mode` command line option that can be used for troubleshooting when Chatterino is misbehaving or is misconfigured. It disables hiding the settings button & prevents plugins from loading. (#4985) - Minor: Updated the flatpakref link included with nightly builds to point to up-to-date flathub-beta builds. (#5008) -- Minor: Add a new completion API for experimental plugins feature. (#5000) +- Minor: Add a new completion API for experimental plugins feature. (#5000, #5047) - Minor: Re-enabled _Restart on crash_ option on Windows. (#5012) - Bugfix: Fixed an issue where certain emojis did not send to Twitch chat correctly. (#4840) - Bugfix: Fixed capitalized channel names in log inclusion list not being logged. (#4848) diff --git a/docs/chatterino.d.ts b/docs/chatterino.d.ts index aece0988d..23cbdc2bb 100644 --- a/docs/chatterino.d.ts +++ b/docs/chatterino.d.ts @@ -26,7 +26,7 @@ declare module c2 { } enum EventType { - RegisterCompletions = "RegisterCompletions", + CompletionRequested = "CompletionRequested", } type CbFuncCompletionsRequested = ( @@ -35,7 +35,7 @@ declare module c2 { cursor_position: number, is_first_word: boolean ) => CompletionList; - type CbFunc = T extends EventType.RegisterCompletions + type CbFunc = T extends EventType.CompletionRequested ? CbFuncCompletionsRequested : never; diff --git a/docs/plugin-info.schema.json b/docs/plugin-info.schema.json index da4750c1a..2b5203ef6 100644 --- a/docs/plugin-info.schema.json +++ b/docs/plugin-info.schema.json @@ -43,7 +43,8 @@ "type": "string", "description": "A small description of your license.", "examples": ["MIT", "GPL-2.0-or-later"] - } + }, + "$schema": { "type": "string" } }, "required": ["name", "description", "authors", "version", "license"] } diff --git a/docs/plugin-meta.lua b/docs/plugin-meta.lua new file mode 100644 index 000000000..c24647490 --- /dev/null +++ b/docs/plugin-meta.lua @@ -0,0 +1,50 @@ +---@meta Chatterino2 + +-- This file is intended to be used with LuaLS (https://luals.github.io/). +-- Add the folder this file is in to "Lua.workspace.library". + +---@alias LogLevel integer + +---@class CommandContext +---@field words string[] The words typed when executing the command. For example `/foo bar baz` will result in `{"/foo", "bar", "baz"}`. +---@field channel_name string The name of the channel the command was executed in. + +---@class CompletionList +---@field values string[] The completions +---@field hide_others boolean Whether other completions from Chatterino should be hidden/ignored. + +c2 = {} + +---@type { Debug: LogLevel, Info: LogLevel, Warning: LogLevel, Critical: LogLevel } +c2.LogLevel = {} + +--- Writes a message to the Chatterino log. +---@param level LogLevel The desired level. +---@param ... any Values to log. Should be convertible to a string with `tostring()`. +function c2.log(level, ...) end + +--- Registers a new command called `name` which when executed will call `handler`. +---@param name string The name of the command. +---@param handler fun(ctx: CommandContext) The handler to be invoked when the command gets executed. +---@return boolean ok Returns `true` if everything went ok, `false` if a command with this name exists. +function c2.register_command(name, handler) end + +--- Sends a message to `channel` with the specified text. Also executes commands. +--- +--- **Warning**: It is possible to trigger your own Lua command with this causing a potentially infinite loop. +--- +---@param channel string The name of the Twitch channel +---@param text string The text to be sent +---@return boolean ok +function c2.send_msg(channel, text) end + +--- Creates a system message (gray message) and adds it to the Twitch channel specified by `channel`. +---@param channel string +---@param text string +---@return boolean ok +function c2.system_msg(channel, text) end + +--- Registers a callback to be invoked when completions for a term are requested. +---@param type "CompletionRequested" +---@param func fun(query: string, full_text_content: string, cursor_position: integer, is_first_word: boolean): CompletionList The callback to be invoked. +function c2.register_callback(type, func) end diff --git a/docs/wip-plugins.md b/docs/wip-plugins.md index b77bf2b4d..2e3284350 100644 --- a/docs/wip-plugins.md +++ b/docs/wip-plugins.md @@ -113,6 +113,42 @@ Limitations/known issues: rebuilding the window content caused by reloading another plugin will solve this. - Spaces in command names aren't handled very well (https://github.com/Chatterino/chatterino2/issues/1517). +#### `register_callback("CompletionRequested", handler)` + +Registers a callback (`handler`) to process completions. The callback gets the following parameters: + +- `query`: The queried word. +- `full_text_content`: The whole input. +- `cursor_position`: The position of the cursor in the input. +- `is_first_word`: Flag whether `query` is the first word in the input. + +Example: + +| Input | `query` | `full_text_content` | `cursor_position` | `is_first_word` | +| ---------- | ------- | ------------------- | ----------------- | --------------- | +| `foo│` | `foo` | `foo` | 3 | `true` | +| `fo│o` | `fo` | `foo` | 2 | `true` | +| `foo bar│` | `bar` | `foo bar` | 7 | `false` | +| `foo │bar` | `foo` | `foo bar` | 4 | `false` | + +```lua +function string.startswith(s, other) + return string.sub(s, 1, string.len(other)) == other +end + +c2.register_callback( + "CompletionRequested", + function(query, full_text_content, cursor_position, is_first_word) + if ("!join"):startswith(query) then + ---@type CompletionList + return { hide_others = true, values = { "!join" } } + end + ---@type CompletionList + return { hide_others = false, values = {} } + end +) +``` + #### `send_msg(channel, text)` Sends a message to `channel` with the specified text. Also executes commands.