Skip to content

Build platform-independent command interpreters & services with Kotlin

Notifications You must be signed in to change notification settings

jacksonrakena/rowi

Repository files navigation

Rowi

badge

com.abyssaldev.rowi

A Kotlin framework for building platform-independent command responders.
Automatic module discovery, parameter/type reading, and customization.
Adapted from internal utilities code at Galedu.
Named after the Okarito kiwi.

Feature highlights

  • Automatic command discovery through Kotlin annotations
  • Quick development cycle & less boilerplate with function commands
  • Custom pre-execution checks with ArgumentContract/CommandContract
  • Overridable command executables with CommandExecutable<*>
  • Customisable command discovery strategies
  • Automatic type and argument parsing
    • Add your own type parsers implementing TypeParser
  • Discord support with rowi-jda (for JDA)

How do Rowi commands work?

These examples will use Kotlin 1.4.22.

I'm glad you asked! Let's go over a basic Rowi command, using the default Command annotation.
Firstly, all commands are defined in a class that inherits from CommandModule (or a derivative).

class MyCommandModule : CommandModule()

Next, we define a command using Command and a function:

@Command(name = "add", description = "Adds two numbers.")
fun addNumbersCommand(request: CommandRequest, first: Int, second: Int)

Did you see how the parameters work?
In Rowi, parameters are automatically parsed from the input string and mapped to the function's expected parameters. You can add your own type parsers using TypeParser<T>, or install a Rowi integration to add pre-built ones.

The request object contains some data about the command call, and is a required parameter.

Now we'll make our command actually do something:

println("$first + $second = ${first+second}")

And then, during initialization, add our module to our Rowi builder:

commandEngineBuilder.addModules(MyCommandModule())

And that's it! Rowi will automatically index your module and register any valid commands, using the inbuilt Command strategy.

You can add your own strategies, or use strategies available from integrations.

A quick tour through Rowi integrations

Core

rowi-core contains all the library code necessary to make a command responder (shell terminal, chatbot, or utility program) - including type parsers for Java & Kotlin primitives (Int, Long, Boolean, etc), some basic command & argument contracts, and a default command discovery strategy that looks for functions with the Command annotation.

Discord

rowi-jda contains some helpful bindings for the JDA Discord library, including type parsers for Discord objects (Member, Role, User, etc), and command & argument contracts that reflect on Discord entity components. All rowi-jda contracts and type parsers depend on your custom request type inherting from JdaCommandResponse, which contains contextual data like the author of the message, the channel, the guild, and so on.

Other platforms

Officially supported Rowi bindings for Twitch and Slack are coming soon! 💫

Copyright

Copyright © 2019-2021 Abyssal and contributors, under the MIT License.
Aspects of Rowi pipeline design are inspired by Discord.Net.Commands and Qmmands.

Packages

No packages published

Languages