Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vyfor/cordex
🚀 A fast, powerful and easy-to-use Javacord framework.
https://github.com/vyfor/cordex
bot command cordex discord framework java javacord kotlin reflection
Last synced: 9 days ago
JSON representation
🚀 A fast, powerful and easy-to-use Javacord framework.
- Host: GitHub
- URL: https://github.com/vyfor/cordex
- Owner: vyfor
- License: mit
- Created: 2023-08-22T14:26:58.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-03-27T21:56:34.000Z (8 months ago)
- Last Synced: 2024-03-27T22:43:49.756Z (8 months ago)
- Topics: bot, command, cordex, discord, framework, java, javacord, kotlin, reflection
- Language: Kotlin
- Homepage: https://discord.gg/mw27xdA3wh
- Size: 241 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🧩 Cordex [](https://kotlinlang.org) [](https://jitpack.io/#vyfor/Cordex)
**🚀 A fast, powerful and easy-to-use [Javacord](https://javacord.org/) framework written in [Kotlin](https://kotlinlang.org/).**
**Cordex** is an innovative command framework designed to optimize the capabilities of Javacord, combining rich features and an intuitive syntax that simplifies the process of building Discord bots.
It presents a developer-friendly solution for defining command arguments in a manner reminiscent of command-line interfaces (CLI).
> [!WARNING]
> Keep in mind that this library is in beta, and may not be ready for production purposes just yet.
## 🔌 Requirements
In order to use Cordex, you'll need the following prerequisites:
- **Java**: `8 or later`
- **Kotlin**: `1.9.0`
- **Coroutines**: `1.7.3`
- **Javacord**: `3.9.0`
## 📦 Installation
### Gradle
```gradle
repositories {
...
maven("https://jitpack.io")
}
dependencies {
implementation("com.github.vyfor:Cordex:0.3.2")
}
```
### Maven
```xml
jitpack.io
https://jitpack.io
com.github.vyfor
Cordex
0.3.2
```
## ✨ Examples
### Setting up Cordex
Initialize Cordex by setting your bot token. You can configure the created DiscordApiBuilder inside the `api` block.
```kt
fun main() {
cordex("TOKEN") {
prefix { "~" }
api {
setAllIntents()
}
}
}
```
### Creating a Command
There are two ways of creating commands:
1. **Through inheritance:**
- Define a custom command by extending the `Command` class and implementing its execute function.
```kt
class ExampleCommand : Command("example") {
override suspend fun Arguments.execute(ctx: Context) {
// Command logic goes here
ctx.message.reply("This is an example command!")
}
}
```
2. **Through the DSL function:**
- Define a custom command by using the `command()` function and providing necessary fields.
```kt
command("example") {
execute { ctx ->
ctx.message.reply("This is an example command!")
}
}
```
#### Registering a text command
Add your newly created command to the command registry using the following methods:
- A plus sign followed by an instance of your command class.
- The `load("package")` method to load classes extending the `Command` class.
```kt
cordex("TOKEN") {
//...
commands {
+ExampleCommand()
load("me.blast.commands")
}
}
```
> [!WARNING]
> Specifying a package name isn't mandatory, but highly recommended. Not doing so may negatively impact the startup overhead of the bot.
### Error Handling
Cordex offers robust error handling capabilities to ensure your bot can gracefully manage unexpected situations.
#### Command execution error
Use `onError` to define how your bot responds when an exception occurs during command execution.
```kt
cordex("TOKEN") {
onError { event, command, ex ->
// Error handling logic goes here
event.message.reply("Error!")
}
}
```
#### Argument parsing error
Cordex defaults to sending a usage message on argument parsing errors. However, you can customize this behavior with your own function using `onParseError`:
```kt
cordex("TOKEN") {
onParseError { event, command, ex ->
// Error handling logic goes here
event.message.reply(
when (ex) {
is ArgumentException.Invalid -> "Invalid value provided for argument ${ex.argument.argumentName}"
is ArgumentException.Empty -> "No value provided for argument ${ex.argument.argumentName}"
is ArgumentException.Insufficient -> "Insufficient amount of values provided for argument ${ex.argument.argumentName}"
is ArgumentException.Missing -> "Missing required arguments: ${ex.arguments.joinToString(", ") { it.argumentName }}"
}
)
}
}
```
### Command Arguments
> Cordex follows the approach of handling arguments in a way similar to how command-line interfaces (CLI) do.
**There exist 3 types of arguments:**
- **Options**
- Options are arguments capable of accepting values.
- **Flags**
- Flags are arguments that are optional, and providing them assigns their value as true.
- **Positional arguments**
- Positional arguments are arguments provided without explicit naming.
You can define each of these argument types using their respective functions:
```kt
class ExampleCommand : Command("example") {
val option by option("Description") // --option, -o
val flag by flag("Description") // --flag, -f
val positional by positional("Description") // [--positional]
}
```
Names are optional; Cordex obtains them from variable names, using the first letter as the short name.
#### Accessing argument values
Argument values can be accessed in different ways:
1. `option.value`
2. `option()`
3. `option { it -> ... }`
### Beyond the Basics
Arguments may be optional, hold default values, accept multiple values, and have validators:
```kt
val name by option().multiple(1..2) // List (min: 1, max: 2)
val age by option().optional(18) { toInt() } // Int? (default: 18)
```
Validators also offer the capability to include custom error messages, achieved by throwing an exception with a message included.
### Predefined validators
Cordex provides a range of predefined validators you can utilize:
#### Primitive types
- `int()` `uInt()`
- `long()` `uLong()`
- `float()`
- `double()`
#### Discord entities
- `user()`
- `role()`
- `category()`
- `message()`
- `customEmoji()`
- `snowflake()`
- `textChannel()` `voiceChannel()` `threadChannel()` `stageChannel()` `forumChannel()` `channel(types...)`
#### And more
- `url()`
- `duration()`
- `date()`
- `dateTime()`
- `color()`
- `unicodeEmoji()`
- `enum()`
- `map()`
> [!NOTE]
> These methods combine multiple input values (from multi-value arguments) into a single string and try to convert the combined result to the appropriate type.
>
> If you want each input value to be converted separately, use the same function with a plural name. *e.g.* `users()` `roles()`
### Command Suggestions
**Cordex** offers a feature known as command suggestions, allowing the bot to proactively suggest commands that closely match any incorrectly provided by the user.
To enable this functionality, simply include the following line of code:
```kt
cordex("TOKEN") {
enableCommandSuggestion(DistanceAccuracy)
}
```
Here, the parameter `DistanceAccuracy` represents the level of precision in matching input string with defined commands.
### Pagination
You can create a paginator that goes through a given list using the `List.paginate` or `List.paginateDefault` function.
The `paginateDefault` function provides the same pagination features but with default handlers attached.
The syntax is as follows:
```kt
List.paginate(
channel = ctx.channel,
messageEvent = ctx.event,
itemsPerPage = 1,
onStart = { messageEvent, paginator, currentItems ->
MessageBuilder().setContent(currentItems.joinToString("\n"))
},
onPagination = { message, paginator, currentItems ->
MessageUpdater(message).setContent(currentItems.joinToString("\n"))
},
onEmpty = {
MessageBuilder().setContent("No items found")
},
removeAfter = 2.minutes,
canClose = true // Adds a button to close the paginator
)
```
> Take a look at [PaginationUtils.kt](src/main/kotlin/me/blast/utils/pagination/PaginationUtils.kt) to see a complete example.
### Command Interceptors
As the name suggests, command interceptors intercept a command's execution and run the given block of code.
The block must return a boolean value, indicating whether to continue the execution or not.
```kt
cordex("TOKEN") {
intercept("refresh") { event, command ->
event.server.get().id == 0123456789L
}
}
```
## 📚 Dependencies
**Cordex relies on these amazing libraries:**
- https://github.com/Javacord/Javacord
An easy to use multithreaded library for creating Discord bots in Java.
- https://github.com/felldo/JEmoji
Java Emoji (JEmoji) is a lightweight fast emoji library for Java with the purpose to improve and ease working with emojis
## 📝 TODO
[ ] Slash command support
[ ] `Attachment` argument type
[ ] Command categorization
[ ] Subcommands