From 40e39cef3493c3d0a3ceb3fa021ba21c1154e4cc Mon Sep 17 00:00:00 2001 From: roridev Date: Mon, 20 Jun 2022 22:50:14 -0300 Subject: [PATCH 01/43] [core] Add basic feature set --- sisbasekt/core.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 432f9a1..91f6196 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -2,3 +2,37 @@ `Type: Subproject` Subproject of : [`SisbaseKT`](../sisbasekt.md) +Discord extension manager + +## Features + +- Commands `META!` + User-provided commands following the contract: + `Command [Arguments...]` + The prefix is usually ommited from the extension unless the `@RequiresPrefixes` annotation is used. + Commands are functions, be them anonymous or not, which can be inside of one or more Command Groups. + Command Groups are classes where a `@Group` annotation is used. + All preconditions can be checked simultaneous by calling `core.Commands::checkPreconditions`. + +- Systems `META!` + User-provided lifelong processes. Uses range from repeating jobs bound to a timer or connectors between the bot and an external data source. + Systems can be manually unregistered during runtime via the `core.Manager::unregister` API. + Systems can depend on other systems using the `@DependsOn` annotation. + Systems can add "soft dependencies" using the `@Extends` annotation. + +- Command Parsing `Important!` + Parses a user given string and serializes all inputs into commands/parameters with an extensible interface. + Likely to follow [`kotlinx.serialization`](https://github.com/Kotlin/kotlinx.serialization)'s `Serializable` format. + +- System Handling `Important!` + Handles the lifetime of systems. + The system lifetime is as follows: + - `PreInit` + - `Init` - **Required** + - `PostInit` + - `Disable` - **Required** + +- Discord Connection `Important!` +- Secret Storage +- Configuration API +- Prefix Handling `Important!` From d823034ad2411a4cef4fda18a5cd238b5a086db8 Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 17 Jul 2022 18:27:00 -0300 Subject: [PATCH 02/43] Add starting API details --- sisbasekt/api.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/sisbasekt/api.md b/sisbasekt/api.md index 2112901..37d7ae3 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -1,3 +1,46 @@ # sisbase-api `Type: Subproject` Subproject of: [`SisbaseKT`](../sisbasekt.md) + +Api for developing extensions, has two main abstractions: Commands and Systems. + +## Commands +Simple interactions with the user caused by a direct call to them. + +Has the following attributes: + +| Field | Type | Description | +|---------------|----------|---------------------------------------------------------------------------------| +| `name` | String | Name of the command | +| `description` | String? | A short description of the command | +| `user` | User | The user that called the command | +| `channel` | Channel | The channel on which the command was called | +| `guild` | Guild? | The guild on which the command was called | + +### Text-based +The third-party command system, based on detecting commands from messages sent on a given discord channel. +Has an extensive permission system since the code is fully controlled by the library. +Requires a system that checks every message for a valid command. + +Extends the base attributes with: + +| Field | Type | Description | +|----------|----------------|-------------------------------------------------------------------------------------------------------------| +| `checks` | [Precondition] | An array with all checks done to the text command by the permission engine, or an empty array if none exist | +| `group` | Group? | The group the command is a part of | +| `alias` | [String] | An array containing all aliases to the command, or an empty array if none exist | + +### Slash +Discord's native command system, supercedes text-based commands but has a limit of how many commands can be registered and require modifying the application. +Does not require a system since discord dispatches the command to the bot via the gateway. + +**Currently, support for slash commands isn't planned, this could change in the future** + +## Systems +Long-term, usually lifelong background procedures. + +### Repeating +Background procedures that repeat at a set interval given by the user. + +### Single-instance +Simple background procedures that are set once the bot loads and are used in other parts of the bot. From 099d79eeef9a04ccafe221ce3342b90289eef55a Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 17 Jul 2022 19:22:06 -0300 Subject: [PATCH 03/43] Add information for systems --- sisbasekt/api.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/sisbasekt/api.md b/sisbasekt/api.md index 37d7ae3..35d7413 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -39,8 +39,35 @@ Does not require a system since discord dispatches the command to the bot via th ## Systems Long-term, usually lifelong background procedures. +Has the following attributes: + +| Field | Type | Description | +|----------------------|---------------------|-------------------------------------------------------------------------------------------------------------------| +| `name` | String | Name of the system | +| `description` | String? | A short description of the system | +| `expansions` | [Expansion] | An array of system expansions, or an empty array if none exist | +| `OnInit` | suspend fun | A function that runs on the start of the system's lifetime | +| `OnDisable` | suspend fun | A function that runs on the end of the system's lifetime | +| `CheckPreconditions` | suspend fun -> Bool | A function that runs before `OnInit`, if it returns `true` the system is loaded, otherwise the system is skipped. | + + ### Repeating Background procedures that repeat at a set interval given by the user. +Implemented by a `Expansion` that has the following attributes: +| Field | Type | Description | +|-------------|-------------|-----------------------------------------------------------------| +| `timeout` | Duration | The period of time that will be used for repeating the function | +| `OnElapsed` | suspend fun | The function that will be repeated once `timeout` elapses | + +### Discord-linked +Background procedures that reads/writes data to Discord. + +Implemented by a `Expansion` that has the following attributes: +| Field | Type | Description | +|-----------------|--------------------|----------------------------------------------------------------------| +| `applyToClient` | suspend fun (Kord) | A function that will be applied to the discord client after `OnInit` | + ### Single-instance Simple background procedures that are set once the bot loads and are used in other parts of the bot. + From e0ab0652dfb56489aaa79269d4ad6fd47e716ded Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 17 Jul 2022 21:34:03 -0300 Subject: [PATCH 04/43] Add `sisbase-commands` subproject --- sisbasekt.md | 1 + sisbasekt/commands.md | 6 ++++++ 2 files changed, 7 insertions(+) create mode 100644 sisbasekt/commands.md diff --git a/sisbasekt.md b/sisbasekt.md index dc2210d..2b7e107 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -9,6 +9,7 @@ Kotlin discord bot framework using the lessons learned by developing sisbase.net ## Subprojects [`sisbase-core`](sisbasekt/core.md) - Fabric-like extension manager. [`sisbase-api`](sisbasekt/api.md) - Api for writing sisbase extensions. +[`sisbase-commands`](sisbasekt/commands.md) - Command Parsing Library. ## Rationale Learning [`kotlin-coroutines`](https://github.com/Kotlin/kotlinx.coroutines). diff --git a/sisbasekt/commands.md b/sisbasekt/commands.md new file mode 100644 index 0000000..6c46af7 --- /dev/null +++ b/sisbasekt/commands.md @@ -0,0 +1,6 @@ +# sisbase-commands +`Type: Subproject` +Subproject of: [`SisbaseKT`](../sisbasekt.md) + +Command parsing library. + From 9919363f68ed613125aeb309b613261886be1b3e Mon Sep 17 00:00:00 2001 From: roridev Date: Wed, 20 Jul 2022 01:20:46 -0300 Subject: [PATCH 05/43] Add more design details for `sisbase-commands` --- sisbasekt/commands.md | 90 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/sisbasekt/commands.md b/sisbasekt/commands.md index 6c46af7..655cafe 100644 --- a/sisbasekt/commands.md +++ b/sisbasekt/commands.md @@ -4,3 +4,93 @@ Subproject of: [`SisbaseKT`](../sisbasekt.md) Command parsing library. +Implemented as an extension. Users can use `sisbase-commands` optionally for command handling, but can also use their own command handling solutions if they so desire. + +## Structure of the `sisbase-commands` extension + +### Persistent Data +The extension must hold a `Registry` for commands during the bot lifetime. + +The `Registry` must safeguard against command conflicts, as **only one command** (including overloads) can be registered for a given `Identifier`. + +`Identifier`s are a way to uniquely identify a given command and they include the following fields: + +| Field | Type | Description | Observations | +|----------------------|--------|----------------------------------------------------|----------------------------------------------------------| +| `source` | String | The id of the extension that registers the command | Automatically set based on the extension's metadata file | +| `fullyQualifiedName` | String | The full command path for a given command | Automatically set once the command is registered | + +An example of a `Identifier` is given below: + +Command is called as `/help` +```yml +source: "your-bot" +command: "help" +identifier: "your-bot::help" +``` + +Command is called as `/group subcommand` +```yml +source: "your-bot" +command: "group/subcommand" +identifier: "your-bot::group/subcommand" +``` + +Identifiers don't care about overloads, this is handled internally by the library. +Mismatches for commands with equal names registered by the same extension will cause the extension to be rejected. (DUPLICATE COMMAND) +Mismatches for commands with equal names registered by different extensions are to be resolved manually on the `overrides.yml` file. (COMMAND MISMATCH) + +Example of a mismatch: + +`ext-a` registers a `help` command. -> `ext-a::help` +`ext-b` also registers a `help` command. -> `ext-b::help` + +Console Output: +``` +[Sisbase-Commands] Command Mismatch Detected: + +The following commands will become unavailable until their mismatches are resolved. + + for `help`: + + `ext-a@version` registered `help` + `ext-b@version` registered `help` + +Please resolve all command mismatches on `overrides.yaml.` + +[Sisbase-Commands] Disabled `ext-a::help` due to: COMMAND MISMATCH +[Sisbase-Commands] Disabled `ext-b::help` due to: COMMAND MISMATCH +``` + +Example of a duplicate command: + +`ext-a` registers a `help` command. -> `ext-a::help` +`ext-a` later registers a `help` command. -> `ext-a::help` + +Console Output: +``` +[Sisbase-Commands] Duplicate Command Detected: + +The following extensions will become unavailable until their duplicate commands are removed. + + for `ext-a`: + + Duplicate `help` command registered. + +Please contact the extension authors to remove the duplicate commands. + +[Sisbase-Commands] Disabled `ext-a` due to: DUPLICATE COMMAND + +``` + +On the case of a critical failure that leads to the extension being shutdown (or on the case of it being disabled) +all commands and hooks **must be unregistered** immediately. + +### Required hooks + +For command parsing: + +| Hook | Usage | +|--------------------------|---------------------------------------------------------------------------------------------------------------| +| `onMessageReceived` | Used for parsing the message contents, building the CommandContext, and forwarding the data to the call site. | +| `onGuildMessageReceived` | Same as `onMessageReceived` | From 82c0a76df4cc3a0c7bc092b6cc0322e435f4432a Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 01:50:59 -0300 Subject: [PATCH 06/43] Clarify which overload --- sisbasekt/commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sisbasekt/commands.md b/sisbasekt/commands.md index 655cafe..6ec0d2b 100644 --- a/sisbasekt/commands.md +++ b/sisbasekt/commands.md @@ -36,7 +36,7 @@ command: "group/subcommand" identifier: "your-bot::group/subcommand" ``` -Identifiers don't care about overloads, this is handled internally by the library. +Identifiers don't care about command overloads, this is handled internally by the library. Mismatches for commands with equal names registered by the same extension will cause the extension to be rejected. (DUPLICATE COMMAND) Mismatches for commands with equal names registered by different extensions are to be resolved manually on the `overrides.yml` file. (COMMAND MISMATCH) From d204545677e0f90ba7ac30fe6f0f7a4550ad62b9 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 02:40:25 -0300 Subject: [PATCH 07/43] Add goals section --- sisbasekt.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/sisbasekt.md b/sisbasekt.md index 2b7e107..5184a37 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -18,3 +18,38 @@ Simplifying discord bot creation by centralizing all the boilerplate in a single Future proofing code by having an easy-to-update path for extensions since all low-level bookkeeping is delegated to the manager. +## Goals + +- Extensibility + +The library should be as extensible as possible as to allow advanced extension authors to have all tools necessary to implement their already existing code into an extension. + +- Easy upgrade path + +If discord changes their API, upgrading a sisbasekt bot would be as easy as updating the `sisbase-core.jar` loader. +If an extension author updates their extension, upgrading it would be as easy as replacing the `extensions/extension.jar` file. +If someone decides to port their fat bot into a sisbase extension the path should be as clear as possible. + +- Modularity + +Extension writers should only import what they need. +E.g. If they already have their own solutions for command handling there would be no need to use `sisbase-commands`. + +- Abstraction + +The end goal is to abstract away as much as possible from the bot creation process. +In the most ideal scenario, an extension shouldn't care what discord library is used on the backend. + +- Backend Agnostic + +In order to explain why this is a goal, a bit of history is required. +Between 2019 and 2021 I had to swap between discord libraries constanly in order to keep my bots up-to-date with the latest API revision (at least 4 times [Discord4J -> discord.py -> DSharpPlus -> Discord.Net]), it was a complete pain and involved rewriting all of my bots' code (since in most cases the code is tied to the library). +Some libraries had a very slow update cycle and had a "bleeding edge" fork where "experiments" (like keeping the Discord API version up-to-date, for some wierd reason) were done and you were forced to add a separate source and keep track of that, leading to "Update Framework Version" commits being way too frequent. +Some libraries were propperly maintained but their design goals were incompatible with my use case and lacked the flexibility necessary to create personalized solutions to even prefix handling (which if you ever made anything more complex then a single-guild bot is a necessity). +Some other libraries just were left in the dust with no one to take care of them. +While some libraries never left the beta phase. + +**Developing bots shouldn't require you to pray that your flavour of library is updated.** +If the library you're using dies, just *swap to a different one*, **no code changes required**. +Make the choice of the backing a mere ~runtime detail~. Your code shall run the same on Discord4j and Kord. + From 86b93d27717e5a5019959b83e6cfea2426074cc4 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 02:45:01 -0300 Subject: [PATCH 08/43] Remove reduntant abstraction section --- sisbasekt.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/sisbasekt.md b/sisbasekt.md index 5184a37..f2d076e 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -35,11 +35,6 @@ If someone decides to port their fat bot into a sisbase extension the path shoul Extension writers should only import what they need. E.g. If they already have their own solutions for command handling there would be no need to use `sisbase-commands`. -- Abstraction - -The end goal is to abstract away as much as possible from the bot creation process. -In the most ideal scenario, an extension shouldn't care what discord library is used on the backend. - - Backend Agnostic In order to explain why this is a goal, a bit of history is required. From 34a510bf8682ffcdb5e194653a1a892ccb9dbd6e Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 02:50:45 -0300 Subject: [PATCH 09/43] Add explanation on "fat bot" --- sisbasekt.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sisbasekt.md b/sisbasekt.md index f2d076e..8dec4bb 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -28,7 +28,9 @@ The library should be as extensible as possible as to allow advanced extension a If discord changes their API, upgrading a sisbasekt bot would be as easy as updating the `sisbase-core.jar` loader. If an extension author updates their extension, upgrading it would be as easy as replacing the `extensions/extension.jar` file. -If someone decides to port their fat bot into a sisbase extension the path should be as clear as possible. +If someone decides to port their "fat bot"1 into a sisbase extension the path should be as clear as possible. + +1- Bots which embed the discord library with them. - Modularity From 91039ec305cc634c7e0d645411e393f8ac1dc15b Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:20:40 -0300 Subject: [PATCH 10/43] Add `sisbase-types` shared dependency --- sisbasekt.md | 1 + sisbasekt/types.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+) create mode 100644 sisbasekt/types.md diff --git a/sisbasekt.md b/sisbasekt.md index 8dec4bb..33d1db6 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -10,6 +10,7 @@ Kotlin discord bot framework using the lessons learned by developing sisbase.net [`sisbase-core`](sisbasekt/core.md) - Fabric-like extension manager. [`sisbase-api`](sisbasekt/api.md) - Api for writing sisbase extensions. [`sisbase-commands`](sisbasekt/commands.md) - Command Parsing Library. +[`sisbase-types`](sisbasekt/types.md) - Shared discord types. ## Rationale Learning [`kotlin-coroutines`](https://github.com/Kotlin/kotlinx.coroutines). diff --git a/sisbasekt/types.md b/sisbasekt/types.md new file mode 100644 index 0000000..9b27e37 --- /dev/null +++ b/sisbasekt/types.md @@ -0,0 +1,15 @@ +# sisbase-types + +`Type: Shared Dependency` +[Go Back to Project Outline](../sisbasekt.md) + + +Discord data types. + +The types from this project will be used by all other sisbasekt projects. + +The objective of this project is to serve as a bridge between different backends, so all objects here will be high level and directly reflect the official API documentation. + +## Package Structure +`org.siscode.sisbase-types` +Base Package. From 005986152b4df102ed2a4465cc7a46305bfc27e8 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:22:39 -0300 Subject: [PATCH 11/43] Remove unecessary "Uses" section on project outline --- sisbasekt.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/sisbasekt.md b/sisbasekt.md index 33d1db6..ffb9a9a 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -2,10 +2,6 @@ `Type: Metaproject` Kotlin discord bot framework using the lessons learned by developing sisbase.net -## Uses -[`Kord`](https://github.com/kordlib/kord) - **Discord Library Wrapper** -[`pf4j`](https://github.com/pf4j/pf4j) - **Plugin Framework** - ## Subprojects [`sisbase-core`](sisbasekt/core.md) - Fabric-like extension manager. [`sisbase-api`](sisbasekt/api.md) - Api for writing sisbase extensions. From 86bab143be08fc59d9e852b6e8afc7e990b77edb Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:25:56 -0300 Subject: [PATCH 12/43] Add "Uses" section --- sisbasekt/core.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 91f6196..5b79e7f 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -4,6 +4,9 @@ Subproject of : [`SisbaseKT`](../sisbasekt.md) Discord extension manager +## Uses +[PF4J](https://github.com/pf4j/pf4j) - Plugin Framework + ## Features - Commands `META!` From 25061903a6950d85f3d1bd4797f1a1fc044432c9 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:27:25 -0300 Subject: [PATCH 13/43] Remove features related to commands Those were delegated to `sisbase-commands` --- sisbasekt/core.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 5b79e7f..f79d736 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -9,24 +9,12 @@ Discord extension manager ## Features -- Commands `META!` - User-provided commands following the contract: - `Command [Arguments...]` - The prefix is usually ommited from the extension unless the `@RequiresPrefixes` annotation is used. - Commands are functions, be them anonymous or not, which can be inside of one or more Command Groups. - Command Groups are classes where a `@Group` annotation is used. - All preconditions can be checked simultaneous by calling `core.Commands::checkPreconditions`. - - Systems `META!` User-provided lifelong processes. Uses range from repeating jobs bound to a timer or connectors between the bot and an external data source. Systems can be manually unregistered during runtime via the `core.Manager::unregister` API. Systems can depend on other systems using the `@DependsOn` annotation. Systems can add "soft dependencies" using the `@Extends` annotation. -- Command Parsing `Important!` - Parses a user given string and serializes all inputs into commands/parameters with an extensible interface. - Likely to follow [`kotlinx.serialization`](https://github.com/Kotlin/kotlinx.serialization)'s `Serializable` format. - - System Handling `Important!` Handles the lifetime of systems. The system lifetime is as follows: From ba3c173b7d2e97dc80ae2b14ada548c244dc9d32 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:29:17 -0300 Subject: [PATCH 14/43] Add note on prefix handling --- sisbasekt/core.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index f79d736..0c82bbd 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -26,4 +26,5 @@ Discord extension manager - Discord Connection `Important!` - Secret Storage - Configuration API -- Prefix Handling `Important!` +- Prefix Handling `Important!` +*Note: Prefix handling must be open to the user as easily allow configuring an external prefix handler.* From a3201e43377b6363a1fe05119047a1b3b4bd0283 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:34:19 -0300 Subject: [PATCH 15/43] Add note on Discord Connection --- sisbasekt/core.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 0c82bbd..5713b72 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -23,7 +23,8 @@ Discord extension manager - `PostInit` - `Disable` - **Required** -- Discord Connection `Important!` +- Discord Connection `Important!` +*Note: Actual discord connection will be delegated to a `Backend`* - Secret Storage - Configuration API - Prefix Handling `Important!` From 38e234ef9480ab1502299843c8e9aa17671077fa Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:43:37 -0300 Subject: [PATCH 16/43] Add "Lifetime Description" section --- sisbasekt/core.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 5713b72..97fdaf5 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -29,3 +29,23 @@ Discord extension manager - Configuration API - Prefix Handling `Important!` *Note: Prefix handling must be open to the user as easily allow configuring an external prefix handler.* + +## Sisbase-Core Lifetime Description + +### Initialization + +1. Loads configuration +2. Start the Backend +3. Wait for the Backend to connect to Discord +4. Loads Extensions + +### Lost Connection to Backend + +5. Stops all Extensions +6. Try restarting the backend 3 times +7. Shuts down the backend +8. Shuts down + +### Connection to Backend is Resumed + +5. Loads Extensions From 48fbec568c8d844acd0d6c64fee961629d416130 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:47:39 -0300 Subject: [PATCH 17/43] Move "Commands" section to commands.md --- sisbasekt/api.md | 32 -------------------------------- sisbasekt/commands.md | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 32 deletions(-) diff --git a/sisbasekt/api.md b/sisbasekt/api.md index 35d7413..990ea79 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -4,38 +4,6 @@ Subproject of: [`SisbaseKT`](../sisbasekt.md) Api for developing extensions, has two main abstractions: Commands and Systems. -## Commands -Simple interactions with the user caused by a direct call to them. - -Has the following attributes: - -| Field | Type | Description | -|---------------|----------|---------------------------------------------------------------------------------| -| `name` | String | Name of the command | -| `description` | String? | A short description of the command | -| `user` | User | The user that called the command | -| `channel` | Channel | The channel on which the command was called | -| `guild` | Guild? | The guild on which the command was called | - -### Text-based -The third-party command system, based on detecting commands from messages sent on a given discord channel. -Has an extensive permission system since the code is fully controlled by the library. -Requires a system that checks every message for a valid command. - -Extends the base attributes with: - -| Field | Type | Description | -|----------|----------------|-------------------------------------------------------------------------------------------------------------| -| `checks` | [Precondition] | An array with all checks done to the text command by the permission engine, or an empty array if none exist | -| `group` | Group? | The group the command is a part of | -| `alias` | [String] | An array containing all aliases to the command, or an empty array if none exist | - -### Slash -Discord's native command system, supercedes text-based commands but has a limit of how many commands can be registered and require modifying the application. -Does not require a system since discord dispatches the command to the bot via the gateway. - -**Currently, support for slash commands isn't planned, this could change in the future** - ## Systems Long-term, usually lifelong background procedures. diff --git a/sisbasekt/commands.md b/sisbasekt/commands.md index 6ec0d2b..8dfbf45 100644 --- a/sisbasekt/commands.md +++ b/sisbasekt/commands.md @@ -6,6 +6,39 @@ Command parsing library. Implemented as an extension. Users can use `sisbase-commands` optionally for command handling, but can also use their own command handling solutions if they so desire. +## Commands +Simple interactions with the user caused by a direct call to them. + +Has the following attributes: + +| Field | Type | Description | +|---------------|----------|---------------------------------------------------------------------------------| +| `name` | String | Name of the command | +| `description` | String? | A short description of the command | +| `user` | User | The user that called the command | +| `channel` | Channel | The channel on which the command was called | +| `guild` | Guild? | The guild on which the command was called | + +### Text-based +The third-party command system, based on detecting commands from messages sent on a given discord channel. +Has an extensive permission system since the code is fully controlled by the library. +Requires a system that checks every message for a valid command. + +Extends the base attributes with: + +| Field | Type | Description | +|----------|----------------|-------------------------------------------------------------------------------------------------------------| +| `checks` | [Precondition] | An array with all checks done to the text command by the permission engine, or an empty array if none exist | +| `group` | Group? | The group the command is a part of | +| `alias` | [String] | An array containing all aliases to the command, or an empty array if none exist | + +### Slash +Discord's native command system, supercedes text-based commands but has a limit of how many commands can be registered and require modifying the application. +Does not require a system since discord dispatches the command to the bot via the gateway. + +**Currently, support for slash commands isn't planned, this could change in the future** + + ## Structure of the `sisbase-commands` extension ### Persistent Data From f257c3f42c418a7c1432234ac85f84770b3195c2 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:50:05 -0300 Subject: [PATCH 18/43] Move "System" section to core.md --- sisbasekt/api.md | 34 ---------------------------------- sisbasekt/core.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 34 deletions(-) diff --git a/sisbasekt/api.md b/sisbasekt/api.md index 990ea79..9c92bc2 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -4,38 +4,4 @@ Subproject of: [`SisbaseKT`](../sisbasekt.md) Api for developing extensions, has two main abstractions: Commands and Systems. -## Systems -Long-term, usually lifelong background procedures. - -Has the following attributes: - -| Field | Type | Description | -|----------------------|---------------------|-------------------------------------------------------------------------------------------------------------------| -| `name` | String | Name of the system | -| `description` | String? | A short description of the system | -| `expansions` | [Expansion] | An array of system expansions, or an empty array if none exist | -| `OnInit` | suspend fun | A function that runs on the start of the system's lifetime | -| `OnDisable` | suspend fun | A function that runs on the end of the system's lifetime | -| `CheckPreconditions` | suspend fun -> Bool | A function that runs before `OnInit`, if it returns `true` the system is loaded, otherwise the system is skipped. | - - -### Repeating -Background procedures that repeat at a set interval given by the user. - -Implemented by a `Expansion` that has the following attributes: -| Field | Type | Description | -|-------------|-------------|-----------------------------------------------------------------| -| `timeout` | Duration | The period of time that will be used for repeating the function | -| `OnElapsed` | suspend fun | The function that will be repeated once `timeout` elapses | - -### Discord-linked -Background procedures that reads/writes data to Discord. - -Implemented by a `Expansion` that has the following attributes: -| Field | Type | Description | -|-----------------|--------------------|----------------------------------------------------------------------| -| `applyToClient` | suspend fun (Kord) | A function that will be applied to the discord client after `OnInit` | - -### Single-instance -Simple background procedures that are set once the bot loads and are used in other parts of the bot. diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 97fdaf5..37dfbf7 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -30,6 +30,43 @@ Discord extension manager - Prefix Handling `Important!` *Note: Prefix handling must be open to the user as easily allow configuring an external prefix handler.* + +## Systems +Long-term, usually lifelong background procedures. + +Has the following attributes: + +| Field | Type | Description | +|----------------------|---------------------|-------------------------------------------------------------------------------------------------------------------| +| `name` | String | Name of the system | +| `description` | String? | A short description of the system | +| `expansions` | [Expansion] | An array of system expansions, or an empty array if none exist | +| `OnInit` | suspend fun | A function that runs on the start of the system's lifetime | +| `OnDisable` | suspend fun | A function that runs on the end of the system's lifetime | +| `CheckPreconditions` | suspend fun -> Bool | A function that runs before `OnInit`, if it returns `true` the system is loaded, otherwise the system is skipped. | + + +### Repeating +Background procedures that repeat at a set interval given by the user. + +Implemented by a `Expansion` that has the following attributes: +| Field | Type | Description | +|-------------|-------------|-----------------------------------------------------------------| +| `timeout` | Duration | The period of time that will be used for repeating the function | +| `OnElapsed` | suspend fun | The function that will be repeated once `timeout` elapses | + +### Discord-linked +Background procedures that reads/writes data to Discord. + +Implemented by a `Expansion` that has the following attributes: +| Field | Type | Description | +|-----------------|--------------------|----------------------------------------------------------------------| +| `applyToClient` | suspend fun (Kord) | A function that will be applied to the discord client after `OnInit` | + +### Single-instance +Simple background procedures that are set once the bot loads and are used in other parts of the bot. + + ## Sisbase-Core Lifetime Description ### Initialization From 6a3d63030bf33f709ecbfef39300c3901da193c5 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 03:55:36 -0300 Subject: [PATCH 19/43] Repurpose `sisbase-api` This project was left hanging since its original intent got superseded by `sisbase-commands` becoming its own project and systems becoming first-class citizens of `sisbase-core`. --- sisbasekt.md | 2 +- sisbasekt/api.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sisbasekt.md b/sisbasekt.md index ffb9a9a..00787d7 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -4,7 +4,7 @@ Kotlin discord bot framework using the lessons learned by developing sisbase.net ## Subprojects [`sisbase-core`](sisbasekt/core.md) - Fabric-like extension manager. -[`sisbase-api`](sisbasekt/api.md) - Api for writing sisbase extensions. +[`sisbase-api`](sisbasekt/api.md) - A collection of interfaces representing the Discord API Spec. [`sisbase-commands`](sisbasekt/commands.md) - Command Parsing Library. [`sisbase-types`](sisbasekt/types.md) - Shared discord types. diff --git a/sisbasekt/api.md b/sisbasekt/api.md index 9c92bc2..c7a95d8 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -2,6 +2,6 @@ `Type: Subproject` Subproject of: [`SisbaseKT`](../sisbasekt.md) -Api for developing extensions, has two main abstractions: Commands and Systems. - +A collection of interfaces representing the Discord API Spec. +Implemented by `Backends`. From e61fa83e0824ff8d3817e7da11a426eab5977ff9 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 04:02:29 -0300 Subject: [PATCH 20/43] Remove reference to Kord --- sisbasekt/core.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 37dfbf7..ae3fbcf 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -59,9 +59,9 @@ Implemented by a `Expansion` that has the following attributes: Background procedures that reads/writes data to Discord. Implemented by a `Expansion` that has the following attributes: -| Field | Type | Description | -|-----------------|--------------------|----------------------------------------------------------------------| -| `applyToClient` | suspend fun (Kord) | A function that will be applied to the discord client after `OnInit` | +| Field | Type | Description | +|-----------------|----------------------|----------------------------------------------------------------------| +| `applyToClient` | suspend fun (Client) | A function that will be applied to the discord client after `OnInit` | ### Single-instance Simple background procedures that are set once the bot loads and are used in other parts of the bot. From 942a9e75c58db51d0cbd1d391c9377f31658add6 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 04:07:28 -0300 Subject: [PATCH 21/43] Update `sisbase-commands` description The functionality stopped being "just a parser" ages ago. --- sisbasekt.md | 2 +- sisbasekt/commands.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sisbasekt.md b/sisbasekt.md index 00787d7..33ee65c 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -5,7 +5,7 @@ Kotlin discord bot framework using the lessons learned by developing sisbase.net ## Subprojects [`sisbase-core`](sisbasekt/core.md) - Fabric-like extension manager. [`sisbase-api`](sisbasekt/api.md) - A collection of interfaces representing the Discord API Spec. -[`sisbase-commands`](sisbasekt/commands.md) - Command Parsing Library. +[`sisbase-commands`](sisbasekt/commands.md) - Command Library. [`sisbase-types`](sisbasekt/types.md) - Shared discord types. ## Rationale diff --git a/sisbasekt/commands.md b/sisbasekt/commands.md index 8dfbf45..3a9300e 100644 --- a/sisbasekt/commands.md +++ b/sisbasekt/commands.md @@ -2,7 +2,7 @@ `Type: Subproject` Subproject of: [`SisbaseKT`](../sisbasekt.md) -Command parsing library. +Command library. Implemented as an extension. Users can use `sisbase-commands` optionally for command handling, but can also use their own command handling solutions if they so desire. From b32551e5916038348c96e7b8256940f94a96e99d Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 16:39:10 -0300 Subject: [PATCH 22/43] Add "Project Structure" section --- sisbasekt/api.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/sisbasekt/api.md b/sisbasekt/api.md index c7a95d8..090d640 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -5,3 +5,13 @@ Subproject of: [`SisbaseKT`](../sisbasekt.md) A collection of interfaces representing the Discord API Spec. Implemented by `Backends`. +## Project Structure +`org.sisbase.sisbase-api` +Base package + +`org.sisbase.sisbase-api.rest` +High level wrapper for Discord's Rest API + +`org.sisbase.sisbase-api.gateway` +High level wrapper for Discord's Gateway + From aabf5367413910d360616c2e76d8b22a483a23a5 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 16:40:18 -0300 Subject: [PATCH 23/43] Add "Usage" section --- sisbasekt/api.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/sisbasekt/api.md b/sisbasekt/api.md index 090d640..85d8731 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -15,3 +15,59 @@ High level wrapper for Discord's Rest API `org.sisbase.sisbase-api.gateway` High level wrapper for Discord's Gateway +## Usage + +### Implementing a Backend +Backends are the actual libraries that connect to discord. +An example of a valid backend would be Discord4J. + +To implement a gateway backend, extend `GatewayBackend` +To implement a rest backend, extend `RestBackend` +To implement a backend that supports both, extend `AbstractBackend` + +```kt +package org.siscode.sisbasekt-backends.discord4j +class Discord4JBackend() : AbstractBackend { + public restBackend = Discord4JRest(); + public gatewaybackend = Discord4JGateway() +} +``` + +### Developing extensions +Extension writers call the API provided by sisbase-api directly, and as such +can't know which backend will be chosen by the end user. + +In order to make sure your extension is propperly supported, extension writers can annotate their systems with `@RequireApiFeatures` and `@RequireApiVersion`. + +On the case of a backend not supporting said version or feature that system will be disabled and a warning will be printed to the console. + +``` +[Sisbase-API] Dependency Error: + Extension `id@version` requires + Discord API Version >= X + Backend `id@version` provides + Discord API Version == Z + +The following features will be disabled: +- Feature Name [Description] +- Feature Name [Description] + +Please update or change the backend to get these features back. +``` + +Extension writers can also add `require-api-version` and `require-api-features` to the `mod.json` metadata file. + +On the case of a backend not supporting said version or features the extension won't be loaded and an error will be printed to the console. + +``` +[Sisbase-API] Critical Dependency Failure: + Extension `id@version` requires + Discord API Version >= X + Backend `id@version` provides + Discord API Version == Z + +Extension `id@version` is now disabled. + +Please update or change the backend to get `id` back. +``` + From 92b20674d4466bce2be06c81b2fa61527fbc8f33 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 16:54:48 -0300 Subject: [PATCH 24/43] Add missing packages to package structure --- sisbasekt/types.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/sisbasekt/types.md b/sisbasekt/types.md index 9b27e37..e625c37 100644 --- a/sisbasekt/types.md +++ b/sisbasekt/types.md @@ -12,4 +12,10 @@ The objective of this project is to serve as a bridge between different backends ## Package Structure `org.siscode.sisbase-types` -Base Package. +Base Package. + +`org.siscode.sisbase-types.rest` +Discord Rest API Types. + +`org.siscode.sisbase-type.gateway` +Discord Gateway Types. From fc33f857e0de9455272a5531bed2a9758ec61eeb Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 17:02:15 -0300 Subject: [PATCH 25/43] Add "Other Types" section --- sisbasekt/types.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/sisbasekt/types.md b/sisbasekt/types.md index e625c37..3cde6da 100644 --- a/sisbasekt/types.md +++ b/sisbasekt/types.md @@ -19,3 +19,8 @@ Discord Rest API Types. `org.siscode.sisbase-type.gateway` Discord Gateway Types. +## Other Types + +### `DiscordApiVersion` +An Enum containing all Discord API Versions so that no invalid versions can be represented. + From 2cedbb62feea158f479c25ba4d4670e9b422072e Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 17:02:49 -0300 Subject: [PATCH 26/43] Add "Annotations" section --- sisbasekt/types.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/sisbasekt/types.md b/sisbasekt/types.md index 3cde6da..9fe590f 100644 --- a/sisbasekt/types.md +++ b/sisbasekt/types.md @@ -19,6 +19,19 @@ Discord Rest API Types. `org.siscode.sisbase-type.gateway` Discord Gateway Types. + +`org.siscode.sisbase-type.annotation` +Annotations used by the library + +## Annotations + +### `@Since` +Describes which version of the API added that Type. + +| Field | Type | Description | +|-----------|-------------------|------------------------------------------| +| `version` | DiscordApiVersion | Version of the API which added that type | + ## Other Types ### `DiscordApiVersion` From 7966fd23320aefb05bc351ee1c98057763d51492 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 17:11:41 -0300 Subject: [PATCH 27/43] Add note on "Backend Agnostic" --- sisbasekt.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sisbasekt.md b/sisbasekt.md index 33ee65c..ad7a615 100644 --- a/sisbasekt.md +++ b/sisbasekt.md @@ -47,3 +47,5 @@ While some libraries never left the beta phase. If the library you're using dies, just *swap to a different one*, **no code changes required**. Make the choice of the backing a mere ~runtime detail~. Your code shall run the same on Discord4j and Kord. +*Note: +Thanks to @wffirilat for bringing this to my attention, wouldn't have thougth about this on my own!* From 8e74767d4d9213e0971c3f478f76a8fd30b60c4d Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 21:38:59 -0300 Subject: [PATCH 28/43] Add mod_json.md --- sisbasekt/mod_json.md | 62 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 sisbasekt/mod_json.md diff --git a/sisbasekt/mod_json.md b/sisbasekt/mod_json.md new file mode 100644 index 0000000..8ce5238 --- /dev/null +++ b/sisbasekt/mod_json.md @@ -0,0 +1,62 @@ +# [tbd].mod.json +The [tbd].mod.json is a extension metadata file used by the [`sisbase-loader`](./core.md) to load extensions. +In order to be loaded, an extension **must** have this file with the exact name placed in the root directory of the mod JAR. + +## Mandatory Fields +| Name | Type | Description | +|-----------------|---------|-----------------------------------------------------------------------------------------------------------| +| `id` | String | Defines the extension's identifier - A String of Latin Letters, Digits, Underscores with Lenght from 1-63 | +| `version` | String | Defines the extension's version. - A String value, Optionally matching [`SemVer`](). | +| `schemaVersion` | Integer | Used Internally. Must be `1`. | + +## Optional Fields + +### Metadata +| Name | Type | Description | +|----------------|----------|----------------------------------------------------------------------------------| +| `name` | String | Defines the user-friendly extension name. If not present, assume it matches `id` | +| `description` | String | Defines the extension's description. If not present, assume empty string. | +| `contact` | Contact | Defines the contact information for the project. | +| `authors` | [Author] | A list of authors of the extension. | +| `contributors` | [Author] | Same as `authors` | + + +### Dependency resolution + +| Name | Type | Description | +|------------------------|------------|-----------------------------------------------------------------------------------------| +| `required-api-version` | Integer | Defines the minimum required Discord API Version necessary for the extension to load. | +| `depends` | Dependency | For dependencies **required** to run. Without them the extension won't load. | +| `recommends` | Dependency | For dependencies **not required** to run. Without them the loader will print a warning. | + +## Data Types + +### Dependency +Object whose key is the `id` of the dependency, and whose value is either a string or an array of strings declaring supported version ranges. + +Example: +```json +{ + "my_dependency":">=1.0.0" +} +``` + + +### Author +Single Name (String) or an object containing these fields: +| Name | Type | Description | +|-----------|---------|----------------------------------------------------| +| `name` | String | The real name, username, of the person (Mandatory) | +| `contact` | Contact | Person's contact information (Optional) | + + +### Contact +An object containing any of those fields. +All of the following fields are **optional** +| Name | Type | Description | +|------------|--------|---------------------------------------------------------------| +| `email` | String | Must be a valid email | +| `irc` | String | Must be a valid URL format | +| `homepage` | String | Must be a valid HTTP/HTTPS address | +| `issues` | String | Extension's issue tracker. Must be a valid HTTP/HTTPS address | +| `sources` | String | Must be a valid URL format | From 4a332f25ee09efeeb0fb682d50067314be8474b9 Mon Sep 17 00:00:00 2001 From: roridev Date: Sat, 23 Jul 2022 21:39:34 -0300 Subject: [PATCH 29/43] Add "Configuration / Metadata" section --- sisbasekt/core.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index ae3fbcf..a3023a1 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -86,3 +86,7 @@ Simple background procedures that are set once the bot loads and are used in oth ### Connection to Backend is Resumed 5. Loads Extensions + +## Configuration / Metadata + +See the [sisbasekt.mod.json Documentation](./mod_json.md) for information about the Metadata File Format. From cd5a2e9113829d169dcb540d280e1ac71f71e27b Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 31 Jul 2022 21:58:18 -0300 Subject: [PATCH 30/43] Add Dependencies section --- sisbasekt/api.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sisbasekt/api.md b/sisbasekt/api.md index 85d8731..5f919bf 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -5,6 +5,9 @@ Subproject of: [`SisbaseKT`](../sisbasekt.md) A collection of interfaces representing the Discord API Spec. Implemented by `Backends`. +## Dependencies +[types](types.md) + ## Project Structure `org.sisbase.sisbase-api` Base package From 51699cbb7f9c84026eef1544b7b7de8af741c2f0 Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 31 Jul 2022 21:58:52 -0300 Subject: [PATCH 31/43] Add Dependencies section --- sisbasekt/commands.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sisbasekt/commands.md b/sisbasekt/commands.md index 3a9300e..3fc4723 100644 --- a/sisbasekt/commands.md +++ b/sisbasekt/commands.md @@ -6,6 +6,9 @@ Command library. Implemented as an extension. Users can use `sisbase-commands` optionally for command handling, but can also use their own command handling solutions if they so desire. +## Dependencies +[core](core.md) + ## Commands Simple interactions with the user caused by a direct call to them. From 79033deab04d62a9b096e5cbd90b3a75efd39eeb Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 31 Jul 2022 21:59:49 -0300 Subject: [PATCH 32/43] Add `api` to Uses section --- sisbasekt/core.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index a3023a1..fcd13c5 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -6,6 +6,7 @@ Discord extension manager ## Uses [PF4J](https://github.com/pf4j/pf4j) - Plugin Framework +[api](api.md) ## Features From ee1f9d6ab35693b917a3cebf530c811cb387eebe Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 31 Jul 2022 22:00:49 -0300 Subject: [PATCH 33/43] Rename Uses section to Dependencies --- sisbasekt/core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index fcd13c5..3728a1a 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -4,7 +4,7 @@ Subproject of : [`SisbaseKT`](../sisbasekt.md) Discord extension manager -## Uses +## Dependencies [PF4J](https://github.com/pf4j/pf4j) - Plugin Framework [api](api.md) From 5eeaa0d7fbeade35b390e73a28cd3f43a1c177b8 Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 31 Jul 2022 22:02:08 -0300 Subject: [PATCH 34/43] Move "Developing extensions" section to `core.md` Extensions are an abstraction that are a part of core. As such there is no need to have a section about them on the api specifications. --- sisbasekt/api.md | 38 -------------------------------------- sisbasekt/core.md | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 38 deletions(-) diff --git a/sisbasekt/api.md b/sisbasekt/api.md index 5f919bf..5b4c893 100644 --- a/sisbasekt/api.md +++ b/sisbasekt/api.md @@ -36,41 +36,3 @@ class Discord4JBackend() : AbstractBackend { } ``` -### Developing extensions -Extension writers call the API provided by sisbase-api directly, and as such -can't know which backend will be chosen by the end user. - -In order to make sure your extension is propperly supported, extension writers can annotate their systems with `@RequireApiFeatures` and `@RequireApiVersion`. - -On the case of a backend not supporting said version or feature that system will be disabled and a warning will be printed to the console. - -``` -[Sisbase-API] Dependency Error: - Extension `id@version` requires - Discord API Version >= X - Backend `id@version` provides - Discord API Version == Z - -The following features will be disabled: -- Feature Name [Description] -- Feature Name [Description] - -Please update or change the backend to get these features back. -``` - -Extension writers can also add `require-api-version` and `require-api-features` to the `mod.json` metadata file. - -On the case of a backend not supporting said version or features the extension won't be loaded and an error will be printed to the console. - -``` -[Sisbase-API] Critical Dependency Failure: - Extension `id@version` requires - Discord API Version >= X - Backend `id@version` provides - Discord API Version == Z - -Extension `id@version` is now disabled. - -Please update or change the backend to get `id` back. -``` - diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 3728a1a..5560947 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -91,3 +91,39 @@ Simple background procedures that are set once the bot loads and are used in oth ## Configuration / Metadata See the [sisbasekt.mod.json Documentation](./mod_json.md) for information about the Metadata File Format. +### Developing extensions + +In order to make sure your extension is propperly supported, extension writers can annotate their systems with `@RequireApiVersion`. + +On the case of a backend not supporting said version that system will be disabled and a warning will be printed to the console. + +``` +[Sisbase-Loader] Dependency Error: + Extension `id@version` requires + Discord API Version >= X + Backend `id@version` provides + Discord API Version == Z + +The following features will be disabled: +- Feature Name [Description] +- Feature Name [Description] + +Please update or change the backend to get these features back. +``` + +Extension writers can also add `require-api-version` to the `mod.json` metadata file. + +On the case of a backend not supporting said version the extension won't be loaded and an error will be printed to the console. + +``` +[Sisbase-Loader] Critical Dependency Failure: + Extension `id@version` requires + Discord API Version >= X + Backend `id@version` provides + Discord API Version == Z + +Extension `id@version` is now disabled. + +Please update or change the backend to get `id` back. +``` + From 320644f2516f1c7da7bb995abe202827d8a573c9 Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 31 Jul 2022 22:02:59 -0300 Subject: [PATCH 35/43] [Idea] Add "`RequireApiVersion` deriving automatically" --- sisbasekt/core.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 5560947..a70923f 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -91,6 +91,10 @@ Simple background procedures that are set once the bot loads and are used in oth ## Configuration / Metadata See the [sisbasekt.mod.json Documentation](./mod_json.md) for information about the Metadata File Format. + +-! IDEA: Due to an change in [`types`](types.md), deriving the `@RequireApiVersion` automatically could be done. +-: [Not Required] [FUTURE] + ### Developing extensions In order to make sure your extension is propperly supported, extension writers can annotate their systems with `@RequireApiVersion`. From 15cf55fb7c28daf89c39fb424b4e0a4bd6c4fbb0 Mon Sep 17 00:00:00 2001 From: roridev Date: Sun, 31 Jul 2022 22:09:59 -0300 Subject: [PATCH 36/43] Make `Developing Extensions` a section --- sisbasekt/core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index a70923f..1503946 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -95,7 +95,7 @@ See the [sisbasekt.mod.json Documentation](./mod_json.md) for information about -! IDEA: Due to an change in [`types`](types.md), deriving the `@RequireApiVersion` automatically could be done. -: [Not Required] [FUTURE] -### Developing extensions +## Developing extensions In order to make sure your extension is propperly supported, extension writers can annotate their systems with `@RequireApiVersion`. From b2fd1acc9bbe4138fb2d3b6964c2a805900a878d Mon Sep 17 00:00:00 2001 From: roridev Date: Mon, 1 Aug 2022 18:08:21 -0300 Subject: [PATCH 37/43] Add `systems.md` --- sisbasekt/core.md | 2 +- sisbasekt/core/systems.md | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 sisbasekt/core/systems.md diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 1503946..b76108a 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -10,7 +10,7 @@ Discord extension manager ## Features -- Systems `META!` +- [Systems](core/systems.md) `META!` User-provided lifelong processes. Uses range from repeating jobs bound to a timer or connectors between the bot and an external data source. Systems can be manually unregistered during runtime via the `core.Manager::unregister` API. Systems can depend on other systems using the `@DependsOn` annotation. diff --git a/sisbasekt/core/systems.md b/sisbasekt/core/systems.md new file mode 100644 index 0000000..3d87247 --- /dev/null +++ b/sisbasekt/core/systems.md @@ -0,0 +1,4 @@ +# Systems +`Type: Feature` +Part of [`core`](../core.md) + From 1243725841ba8edd88c8dbbf6adb311d3092ca2f Mon Sep 17 00:00:00 2001 From: roridev Date: Mon, 1 Aug 2022 18:14:07 -0300 Subject: [PATCH 38/43] Move `Systems` section to `system.md` --- sisbasekt/core.md | 37 ------------------------------------- sisbasekt/core/systems.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 37 deletions(-) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index b76108a..9a81b68 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -31,43 +31,6 @@ Discord extension manager - Prefix Handling `Important!` *Note: Prefix handling must be open to the user as easily allow configuring an external prefix handler.* - -## Systems -Long-term, usually lifelong background procedures. - -Has the following attributes: - -| Field | Type | Description | -|----------------------|---------------------|-------------------------------------------------------------------------------------------------------------------| -| `name` | String | Name of the system | -| `description` | String? | A short description of the system | -| `expansions` | [Expansion] | An array of system expansions, or an empty array if none exist | -| `OnInit` | suspend fun | A function that runs on the start of the system's lifetime | -| `OnDisable` | suspend fun | A function that runs on the end of the system's lifetime | -| `CheckPreconditions` | suspend fun -> Bool | A function that runs before `OnInit`, if it returns `true` the system is loaded, otherwise the system is skipped. | - - -### Repeating -Background procedures that repeat at a set interval given by the user. - -Implemented by a `Expansion` that has the following attributes: -| Field | Type | Description | -|-------------|-------------|-----------------------------------------------------------------| -| `timeout` | Duration | The period of time that will be used for repeating the function | -| `OnElapsed` | suspend fun | The function that will be repeated once `timeout` elapses | - -### Discord-linked -Background procedures that reads/writes data to Discord. - -Implemented by a `Expansion` that has the following attributes: -| Field | Type | Description | -|-----------------|----------------------|----------------------------------------------------------------------| -| `applyToClient` | suspend fun (Client) | A function that will be applied to the discord client after `OnInit` | - -### Single-instance -Simple background procedures that are set once the bot loads and are used in other parts of the bot. - - ## Sisbase-Core Lifetime Description ### Initialization diff --git a/sisbasekt/core/systems.md b/sisbasekt/core/systems.md index 3d87247..090c2c1 100644 --- a/sisbasekt/core/systems.md +++ b/sisbasekt/core/systems.md @@ -2,3 +2,38 @@ `Type: Feature` Part of [`core`](../core.md) +Long-term, usually lifelong background procedures. + +## Data Description +Has the following attributes: + +| Field | Type | Description | +|----------------------|---------------------|-------------------------------------------------------------------------------------------------------------------| +| `name` | String | Name of the system | +| `description` | String? | A short description of the system | +| `expansions` | [Expansion] | An array of system expansions, or an empty array if none exist | +| `OnInit` | suspend fun | A function that runs on the start of the system's lifetime | +| `OnDisable` | suspend fun | A function that runs on the end of the system's lifetime | +| `CheckPreconditions` | suspend fun -> Bool | A function that runs before `OnInit`, if it returns `true` the system is loaded, otherwise the system is skipped. | + + +### Repeating +Background procedures that repeat at a set interval given by the user. + +Implemented by a `Expansion` that has the following attributes: +| Field | Type | Description | +|-------------|-------------|-----------------------------------------------------------------| +| `timeout` | Duration | The period of time that will be used for repeating the function | +| `OnElapsed` | suspend fun | The function that will be repeated once `timeout` elapses | + +### Discord-linked +Background procedures that reads/writes data to Discord. + +Implemented by a `Expansion` that has the following attributes: +| Field | Type | Description | +|-----------------|----------------------|----------------------------------------------------------------------| +| `applyToClient` | suspend fun (Client) | A function that will be applied to the discord client after `OnInit` | + +### Single-instance +Simple background procedures that are set once the bot loads and are used in other parts of the bot. + From 154b2715fa63204e53396baf02aab7ff4f0eae74 Mon Sep 17 00:00:00 2001 From: roridev Date: Mon, 1 Aug 2022 18:17:52 -0300 Subject: [PATCH 39/43] Add "Dependency Management" section --- sisbasekt/core/systems.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sisbasekt/core/systems.md b/sisbasekt/core/systems.md index 090c2c1..5fb6327 100644 --- a/sisbasekt/core/systems.md +++ b/sisbasekt/core/systems.md @@ -4,6 +4,8 @@ Part of [`core`](../core.md) Long-term, usually lifelong background procedures. +## Dependency Management + ## Data Description Has the following attributes: From d1c24674076b4f5bc12e3e1f40ea7cda8ca723fe Mon Sep 17 00:00:00 2001 From: roridev Date: Mon, 1 Aug 2022 18:19:23 -0300 Subject: [PATCH 40/43] Move "Dependency Management" section to `core.md` --- sisbasekt/core.md | 2 -- sisbasekt/core/systems.md | 2 ++ 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 9a81b68..fe5d81d 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -13,8 +13,6 @@ Discord extension manager - [Systems](core/systems.md) `META!` User-provided lifelong processes. Uses range from repeating jobs bound to a timer or connectors between the bot and an external data source. Systems can be manually unregistered during runtime via the `core.Manager::unregister` API. - Systems can depend on other systems using the `@DependsOn` annotation. - Systems can add "soft dependencies" using the `@Extends` annotation. - System Handling `Important!` Handles the lifetime of systems. diff --git a/sisbasekt/core/systems.md b/sisbasekt/core/systems.md index 5fb6327..e8f96a7 100644 --- a/sisbasekt/core/systems.md +++ b/sisbasekt/core/systems.md @@ -5,6 +5,8 @@ Part of [`core`](../core.md) Long-term, usually lifelong background procedures. ## Dependency Management +Systems can depend on other systems using the `@DependsOn` annotation. +Systems can add "soft dependencies" using the `@Extends` annotation. ## Data Description Has the following attributes: From feb4b41cede357b8b631c155a0fdcb3696bafafa Mon Sep 17 00:00:00 2001 From: roridev Date: Mon, 1 Aug 2022 19:22:49 -0300 Subject: [PATCH 41/43] Add `koin` dependency --- sisbasekt/core.md | 1 + 1 file changed, 1 insertion(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index fe5d81d..e211546 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -6,6 +6,7 @@ Discord extension manager ## Dependencies [PF4J](https://github.com/pf4j/pf4j) - Plugin Framework +[koin](https://github.com/InsertKoinIO/koin) - Dependency Injection [api](api.md) ## Features From 3cc3b7aaf8964131a1249bef8345f4465eeec174 Mon Sep 17 00:00:00 2001 From: roridev Date: Mon, 1 Aug 2022 20:16:19 -0300 Subject: [PATCH 42/43] Add "Metadata" section --- sisbasekt/core.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index e211546..011d34d 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -59,6 +59,10 @@ See the [sisbasekt.mod.json Documentation](./mod_json.md) for information about ## Developing extensions +### Metadata +In order for an extension to be loaded, the `sisbasekt.mod.json` file must be present at the root of the JAR file. +For more information on the Metadata File Format, [see above](core.md#configuration--metadata) + In order to make sure your extension is propperly supported, extension writers can annotate their systems with `@RequireApiVersion`. On the case of a backend not supporting said version that system will be disabled and a warning will be printed to the console. From 8b6c0b3dfb8bce797a6fab3ba86144036b237abd Mon Sep 17 00:00:00 2001 From: roridev Date: Mon, 1 Aug 2022 20:16:57 -0300 Subject: [PATCH 43/43] Add "Discord API Version Compatibility" header --- sisbasekt/core.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sisbasekt/core.md b/sisbasekt/core.md index 011d34d..f92cae2 100644 --- a/sisbasekt/core.md +++ b/sisbasekt/core.md @@ -63,6 +63,8 @@ See the [sisbasekt.mod.json Documentation](./mod_json.md) for information about In order for an extension to be loaded, the `sisbasekt.mod.json` file must be present at the root of the JAR file. For more information on the Metadata File Format, [see above](core.md#configuration--metadata) +### Discord API Version Compatibility + In order to make sure your extension is propperly supported, extension writers can annotate their systems with `@RequireApiVersion`. On the case of a backend not supporting said version that system will be disabled and a warning will be printed to the console.